国内镜像配置失败的根本原因是命令格式错误或执行上下文不匹配，正确命令为composer config -g repo.packagist composer https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9，且需确保用户、环境、配置层级一致。
大型 PHP 项目离不开 Composer 国内镜像，根本不是因为“下载快一点”，而是不配镜像，composer install 基本跑不通——卡在 Loading composer repositories 是常态，不是偶然。
composer config -g repo.packagist 总不生效？三个硬性条件漏一个就静默失效
这不是网络问题，是命令本身写错了，Composer 2.2+ 会直接 fallback 到https://packagist.org，且不报错、不提示。
常见错误包括：
- 键名写成 repos.packagist（多一个 s）或 packagist（少 repo.）
- 漏掉中间的 composer（它是 type 值，不是可选参数）
- URL 缺尾部斜杠：https://mirrors.aliyun.com/composer ❌ → 实际请求变成 /composerpackages.json 导致 404
正确命令只有一条：composer config -g repo.packagist composer <a href="https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9">https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9</a>
验证是否成功：运行 composer config -g repo.packagist，输出必须是完整 JSON，例如 {"type": "composer", "url": "<a href="https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9">https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9</a>"}。空、null、或仍是官方地址，说明没写进去。
宝塔、CI、Docker 里全局配置全是“空气”？得看实际执行用户
你在终端用root 配的，但宝塔后台默认用 www 用户跑命令，GitHub Actions 用 runner，Docker 构建里甚至没有 ~/.composer 目录。
它们各自读取自己家目录下的 ~/.composer/config.json，互不影响。
所以：
- 在宝塔里先 whoami 确认用户（通常是 www），再执行 sudo -u www composer config -g repo.packagist composer https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9
- CI 脚本别依赖全局配置，改用临时参数更可靠：composer install --repository-url=https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9
- Dockerfile 中建议把镜像地址通过环境变量注入，避免硬编码
换镜像后 still 卡在 Resolving dependencies？这和镜像无关
镜像只加速包元数据下载（packages.json）和 ZIP 文件下载（Downloading 阶段），**完全不参与依赖解析**。
如果你发现 composer update 卡几十秒甚至几分钟，重点排查：
- "php": "^7.4 || ^8.0" 这类宽泛约束，会让 Composer 尝试海量版本组合
- require-dev 里塞了未锁定版本的工具链，比如 "phpunit/phpunit": "^9"
- 项目中存在大量 dev- 分支依赖，或 composer.lock 长期未更新
临时解法是删掉 vendor 和 composer.lock，再 composer install；但治标不治本，真正要收紧的是版本约束。
项目级配置比全局更可靠，但追加方式容易踩坑
进项目根目录执行composer config repo.packagist composer https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9（不加 -g），它会往 composer.json 的 repositories 字段安全追加，key 固定为 packagist。
但注意：
- 如果原 "repositories": []（数组），命令会失败，需先手动改成 "repositories": {}（空对象）
- 别手写 "packagist.org": false —— 这会彻底关掉基础包校验，连 php 或 ext-json 都装不上
- 改完必须删掉 vendor 和 composer.lock，否则旧 lock 文件里的 hash 可能和镜像元数据不匹配
复杂点不在“怎么配”，而在于 不同执行上下文（用户、CI、容器）各自维护一套配置，且镜像只管下载，不管解析逻辑。稍不留神，你以为走的是阿里云，其实还在直连 packagist.org。
