Composer config -g repo.packagist 命令没生效主因是键名写错（应为单数repo）、缺type值“composer”、URL末尾无斜杠，三者任一出错即静默回退官方源；项目级配置更可靠，且换源后需清缓存并重装依赖。
composer config -g repo.packagist 命令为什么没生效
90% 的“配了还是慢”问题，根本不是网络差，而是这条命令静默失败——不报错，但根本不走镜像。必须同时满足三个硬条件：
• repo.packagist 键名不能写成 repos.packagist（多一个 s 就彻底忽略）
• 中间必须带 composer 这个 type 值，漏掉就 fallback 到 https://packagist.org
• URL 必须是 HTTPS 且末尾带斜杠：https://mirrors.aliyun.com/composer/ ✅，https://mirrors.aliyun.com/composer ❌（少斜杠会拼出 404 路径）
验证是否成功：运行 composer config -g repo.packagist，输出必须是类似 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} 的完整 JSON 对象；空、null 或仍显示官方地址，说明没写进去。
项目级配置比全局更可靠，尤其在 CI/CD 和团队协作中
全局配置看似省事，但在宝塔、GitHub Actions、Docker 构建等场景下极易失效——因为它们以 www 或 runner 用户运行，读不到你本地 root 或个人用户的 .composer/config.json。
正确做法是进项目根目录，执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意不加 -g）
这条命令会自动向 composer.json 的 repositories 字段追加条目，不覆盖已有私有源，也不破坏 JSON 格式。
如果项目已有 "repositories": [] 数组，命令会安全追加；如果原为对象结构 "repositories": {}，它会转为标准数组并插入。
改完务必运行 composer update --lock，让 composer.lock 记录新源地址，否则旧 lock 文件仍指向海外元数据。
换源后仍卡在 “Resolving dependencies”？和镜像无关
镜像只加速网络下载，不解决本地依赖求解卡顿。Resolving dependencies 阶段完全离线，Composer 在本地穷举满足所有约束的版本组合。
常见诱因包括：
• "php": "^7.4 || ^8.0" 这类宽泛版本约束，导致求解器尝试大量组合
• 大量未锁定的 dev 分支依赖，如 "monolog/monolog": "dev-main"
• require-dev 里塞了太多工具包（如 phpunit/phpunit、friendsofphp/php-cs-fixer），尤其当它们自身依赖复杂时
• 启用了已废弃插件（如 fxp/composer-asset-plugin），它会额外请求 Bower/NPM 源，而这些源无国内镜像
此时应收紧版本约束、删减 dev 依赖、升级到现代替代方案（如用 yarn 管理前端资源），而非继续折腾镜像。
换源后报 hash does not match 或 package not found？删 vendor 和 lock 重来
镜像同步存在延迟，且本地缓存可能残留旧源的元数据。首次换源后若出现校验失败或包找不到，不要尝试修复，直接执行：
• rm -rf vendor/ composer.lock（Windows 用 rd /s /q vendor && del composer.lock）
• composer clear-cache
• composer install
旧 composer.lock 记录的是官方源的哈希值，与镜像返回的元数据不兼容；保留它只会引发签名冲突或解析错误。
临时验证是否真走镜像？加 -vvv 参数运行命令，日志里会明确打印出实际请求的 URL，一眼就能确认是不是发到了 mirrors.aliyun.com 或其他镜像域名。
立即学习“PHP免费学习笔记（深入）”；
