Composer中文镜像环境下Composer加载本地仓库规则-composer-PHP中文网

中文镜像不影响本地仓库加载，但会干扰path/vcs仓库发现——因默认启用packagist.org代理，需在repositories顶部显式添加{"packagist.org": false}关闭兜底源，且path/vcs配置须满足路径绝对、git已提交、版本写dev-main等三要素。

composer中文镜像环境下composer加载本地仓库规则

中文镜像不影响本地仓库加载，但会干扰 path/vcs 类型仓库的发现和解析——关键不是镜像本身，而是它默认启用 packagist.org 代理，而本地仓库必须显式禁用该代理才能被识别。

为什么开了阿里云镜像后 path 仓库突然失效

不是镜像“坏了”本地包，而是 Composer 在启用 repo.packagist 镜像后，默认仍会把 packagist.org 当作兜底源。当它尝试从镜像拉取你 require 的包时，发现没命中，就会跳过你的 repositories 里声明的 path 条目——哪怕配置完全正确，也静默忽略。

验证方式：运行 composer install -vvv，看日志里是否出现 Loading repository from ... 及对应本地路径；若只有 Reading .../packages.json（来自镜像地址），说明 path 根本没被扫描
根本原因：镜像配置未同步关闭 packagist.org，导致 Composer 认为“所有包都该走镜像”，本地源被绕过
修复只需一行：在项目 composer.json 的 repositories 数组最顶部加 {"packagist.org": false}

path 仓库 + 中文镜像的正确配置结构

必须同时满足三要素，缺一不可：

repositories 是顶层数组，与 require 同级，不能嵌套在 config 或其他字段下
第一项必须是 {"packagist.org": false}，关掉默认源干扰
第二项起才是你的 path 条目，例如：{"type": "path", "url": "../my-utils"}
require 里的包名，必须和本地包 composer.json 中的 name 字段**逐字符一致**（包括大小写、vendor 名）

示例片段：

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

{
    "repositories": [
        {"packagist.org": false},
        {"type": "path", "url": "../my-utils"}
    ],
    "require": {
        "acme/utils": "dev-main"
    }
}

vcs 本地 Git 仓库在镜像环境下更易出错

镜像对 vcs 类型影响更大，因为 Composer 会先尝试用镜像源解析包名，再 fallback 到 vcs；而本地 vcs 要求绝对路径 + 合法 Git 仓库，稍有偏差就报 Could not find package。

url 必须是绝对路径：file:///Users/me/my-pkg（macOS/Linux）或 file:///C:/projects/my-pkg（Windows），./ 或 ../ 全无效
本地目录必须有 Git 提交：至少一次 git commit，空仓库或未初始化直接被跳过
require 版本只能写 dev-main 或 dev-master，不能写语义化版本号（如 1.0.0），否则匹配失败
调试时加 -vvv 看日志，确认是否出现 Executing command (CWD): git rev-parse --git-dir —— 没这行说明 Git 校验根本没触发

CI/CD 和上线前最容易漏掉的点

本地开发配得再准，CI 构建失败往往是因为：

CI 环境默认设 COMPOSER_DISALLOW_PLUGINS=1，导致 path 和 vcs 仓库被强制禁用，报 Could not find package
上线前没删掉 repositories 里的 path 条目，也没把 require 改成真实版本号（如 "acme/utils": "^2.1"），导致生产环境依赖无法解析
镜像配置写在全局（composer config -g），但 CI 容器里没执行该命令，或用了不同用户权限，导致镜像未生效，回退到慢速官方源