为团队开发统一配置Composer全局镜像的规范流程-composer-PHP中文网

团队开发不应依赖个人全局镜像，而应将镜像配置写入项目级composer.json的repositories数组，首项必须为{"packagist.org": false}，次项为镜像源，且需删除vendor与composer.lock后执行composer install以确保生效。

为团队开发统一配置composer全局镜像的规范流程

团队不该依赖个人全局镜像

团队开发中，靠每个成员自己运行 composer config -g repo.packagist 配置全局镜像，本质是把环境一致性押在“人不犯错”上。一旦有人漏配、配错路径、用 root 执行、或 IDE 缓存旧配置，就会出现“别人能装，我卡在 packagist.org”的问题。更麻烦的是，CI/CD 流水线跑在无家目录的 Docker 容器里，composer config -g 写进去的配置根本不会持久生效。

统一镜像必须写进 composer.json 的 repositories 字段

真正可控、可版本化、跨环境一致的方式，是把镜像声明直接写进项目根目录的 composer.json，且必须满足三个硬性条件：

必须是 "repositories" 数组（不是对象），且该数组**第一个元素**是 Packagist 镜像定义
必须显式禁用官方源：{"packagist.org": false} 是独立项，不能合并到其他仓库对象里
镜像 URL 必须以 / 结尾，例如 https://mirrors.aliyun.com/composer/，少斜杠会导致 404 并静默 fallback

正确示例（放在 composer.json 顶层）：

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": "composer",
    "url": "https://mirrors.aliyun.com/composer/"
  }
]

改完 composer.json 后必须删 vendor 和 composer.lock

Composer 不会重新解析已存在的 composer.lock——它照着里面记录的 dist URL 直接下载，完全无视你刚加的镜像配置。常见错误是只改了 composer.json 就跑 composer update，结果包还是从 packagist.org 拉。

必须手动执行：rm -rf vendor composer.lock
再运行：composer install（不是 update）
CI/CD 中要确保缓存策略不保留旧 composer.lock 或 vendor/，否则每次构建都走错源

优先用 repos.packagist.org 替代 repo.packagist（Composer 2.2+）

新版 Composer 推荐用更精确的键名 repos.packagist.org，尤其当项目涉及子域名请求或自定义 metadata 时，fallback 行为更可靠。命令写法略有不同：

旧方式（仍兼容）：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
新方式（推荐）：composer config -g repositories.packagist.org '{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}'
Windows PowerShell 用户注意：JSON 字符串需双引号包裹并转义内部引号，或直接切 CMD 执行

最易被忽略的点是：即使你用了新键名，只要项目 composer.json 里存在 repositories 字段，它就仍会覆盖全局设置——所以团队规范的核心，从来不是“怎么配全局”，而是“不让全局有机会生效”。