Composer配置不生效的主因是优先级覆盖：项目级repositories字段会完全屏蔽全局repo.packagist设置；此外，Composer 2.2+推荐用repositories.packagist.org，旧键名可能被静默忽略，且URL末尾缺/、HTTP协议、缓存未清、路径错位等均会导致静默失效。
composer config -g repo.packagist 命令为什么有时不生效
因为 Composer 的配置优先级是：项目级 repositories > 全局 repo.packagist > 默认官方源。只要当前目录下有 composer.json，且里面含 "repositories": {...} 字段（哪怕只有一行空对象），全局设置就完全被忽略。
常见误判点：
- 执行
composer config -g repo.packagist有输出，不代表当前项目在用它；得进项目目录后运行composer config repo.packagist看是否为空 - 某些老项目手动写了
"packagist": false，这会直接禁用 packagist.org，但也不走镜像——得删掉或显式补上镜像定义 - CI/CD 中用
sudo composer config -g，结果写进了root用户的~/.composer/config.json，而构建进程以普通用户运行，根本读不到
repos.packagist.org 和 repo.packagist 到底该用哪个
2026 年主流环境（Composer ≥2.2）应优先用 repos.packagist.org，但兼容性要求高时仍可坚持用 repo.packagist。
关键区别：
-
repo.packagist是 1.x 时代延续下来的键名，2.x 全版本都支持，Windows、旧 CI 镜像里最稳 -
repos.packagist.org是 2.2+ 引入的“具名仓库”抽象，更符合语义；但 2.5+ 某些 patch 版本会静默忽略repo.packagist，只认这个新键 - 验证方式：执行
composer config -g repos.packagist.org和composer config -g repo.packagist分别看输出，哪个非空，当前生效的就是哪个
怎么验证镜像真正在用，而不是只改了配置
配置写对 ≠ 请求走镜像。必须观察实际 HTTP 请求行为。
推荐三步验证法：
- 清缓存再试：
composer clear-cache，避免旧包从本地缓存加载，绕过网络请求 - 最小化触发下载：
composer init -n && composer require monolog/monolog --no-install，这样不会真的解压，只发起元数据请求 - 抓真实 URL：
composer update -vvv 2>&1 | grep "GET https"，看到mirrors.aliyun.com才算成功；若出现packagist.org或Could not resolve host: mirrors.aliyun.com，说明 DNS、代理或 hosts 被拦截
自动化脚本里写镜像命令要注意什么
自动化部署（如 Dockerfile、CI 脚本）中写 composer config -g，容易因环境差异失败。
必须处理的细节：
- URL 末尾必须带
/，例如https://mirrors.aliyun.com/composer/✅，少一个斜杠会导致拼出https://mirrors.aliyun.com/composer/packages.json这类错误路径，返回 404 - Windows 环境下，PowerShell 可能因执行策略阻止命令，建议加
--no-interaction参数，并确保%APPDATA%\Composer目录存在且可写 - 不要依赖
composer diagnose输出判断——它只读配置，不发请求；真正要的是日志里那行GET https://... - fallback 机制不能靠脚本自动启用，必须显式写 JSON：
composer config -g repositories.packagist.org '{"type":"composer","url":"https://mirrors.aliyun.com/composer/","fallback":true}'
最易被忽略的一点：镜像地址本身不是万能的。阿里云、腾讯云等全量镜像虽快，但同步有延迟（通常 5–30 分钟），新发布的包可能还没同步过去。如果项目依赖刚 push 的 dev 分支或私有 tag，得确认镜像是否已拉取，否则 fallback 机制也救不了——它只对 404 生效，对 401/500 不重试。
