全局配置composer config -g无法跨机同步，因其写入各机器独立的~/.composer/config.json，ci容器、宝塔www用户、docker runner用户等均读取不同路径；且repo.packagist键名须准确、必填composer类型值、url末尾必须带/，否则静默失效；项目级composer.json中repositories需以数组格式显式禁用"packagist.org": false并指定镜像，同时config.platform须精确到php小版本，并提交composer.lock确保多机一致。
为什么全局配置 composer config -g 在多机间根本不同步
因为全局配置写在 ~/.composer/config.json，而这个路径对每台机器、每个用户都独立存在。CI 容器没家目录、宝塔用 www 用户、Docker 构建用 runner 用户——它们读的压根不是同一个文件。更隐蔽的是：有人用 sudo composer config -g 写进了 root 的配置，但 PHP 进程以 www-data 跑，结果镜像完全不生效。
常见错误现象：Loading composer repositories 卡住十几秒，curl -v https://packagist.org/packages.json 真实发出请求；本地装得快，CI 报 Could not find package；新人拉完代码直接 composer install，却走官方源下载。
-
composer config -g repo.packagist必须拼写准确——repo（单数），不能是repos，否则静默失败 - 命令必须带
composer类型值：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/，漏掉中间的composer会 fallback 到默认源 - URL 末尾必须有
/，否则请求变成/composerpackages.json，404 - Windows 用户改完需重启终端，否则环境变量未刷新
composer.json 里怎么写才真正生效（Composer 2.2+）
只加 "repositories": {"packagist.org": {"type":"composer", "url":"https://mirrors.aliyun.com/composer/"}} 不够，Composer 2.2+ 会忽略它，元数据请求仍硬编码走 packagist.org。
必须用数组格式，且首项显式禁用官方源：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（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/"
}
]
-
{"packagist.org": false}必须是独立对象，不能合并进下一项（比如写成{"packagist.org": false, "type": "composer", ...}无效） - 镜像
url末尾必须带/，这是硬性要求，否则所有元数据请求 404 - 已有私有 VCS 仓库（如 GitLab 内部包）要插在第二项之后，不能删掉第一项
- 如果项目原来
"repositories": {}（空对象），运行composer config repo.packagist composer https://mirrors.aliyun.com/composer/可安全合并；如果是数组格式[]，命令会报错，必须手动改
改完 composer.json 为什么 composer install 还是从官方源下
因为 composer.lock 里存的是旧 dist URL 和 hash，Composer 完全不查新 repositories 配置——它只还原快照，不重新解析源。
必须手动清理：
- 删掉
vendor/和composer.lock - 再执行
composer install（不是update），才会重新读composer.json、生成新lock文件 - CI 脚本里必须加
rm -f composer.lock && rm -rf vendor，否则缓存复用旧 lock -
composer update --dry-run不验证源是否生效，输出不可信
config.platform 不配小版本号等于白配
镜像只加速下载，真正决定装哪个版本的是 composer.lock + config.platform。如果只写 "php": "8.1" 或 "^8.1"，Composer 会忽略该约束，按实际 PHP 版本解析依赖，导致多机间版本不一致。
必须精确到小版本：
"config": {
"platform": {
"php": "8.1.10",
"ext-zip": "8.1.10",
"ext-mbstring": "8.1.10"
}
}
-
platform必须放在composer.json根级config对象下，不能嵌套在extra或写成platform.php - 改完后必须删
vendor/和composer.lock，否则旧 lock 仍按原平台解析 - 验证是否生效：
composer show php输出应为version : 8.1.10；composer install --dry-run日志里要有Platform configuration: php 8.1.10 -
composer.lock必须提交到 Git，这是多机一致的底线——没有它，install就退化成update
composer.json 是否成为可提交、可验证、可强制执行的契约。任何依赖“人去配”的方式，在三人以上团队或 CI 环境中都会失效。
