必须严格执行composer config -g repo.packagist composer https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9，键名、type值、URL末尾斜杠缺一不可，否则静默回退官方源；验证需输出完整JSON，换源后须删vendor和composer.lock重装。
composer config -g repo.packagist 必须写对，否则根本没走镜像
国内开发者执行 composer create-project 或 composer install 卡在 Downloading，90% 是因为这条命令没生效——不是网络差，是 repo.packagist 没配对。它不报错，但静默 fallback 回 <a href="https://www.php.cn/link/ec811d0d775adc62776ba80fadd4ed19">https://www.php.cn/link/ec811d0d775adc62776ba80fadd4ed19</a>，你完全察觉不到。
- 键名必须是
repo.packagist（不是repos.packagist，多一个s就失效） - 第二个参数必须是
composer（这是 type 值，漏掉就当没配） - URL 必须是 HTTPS 且末尾带斜杠：
<a href="https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9">https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9</a>✅，<a href="https://www.php.cn/link/f3ed1977e3554ea76e333ff63ff2e940">https://www.php.cn/link/f3ed1977e3554ea76e333ff63ff2e940</a>❌ - 必须加
-g，否则只改当前目录的composer.json，换个项目就回退
验证是否真写进去了：运行 composer config -g repo.packagist，输出必须是类似 {"type": "composer", "url": "<a href="https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9">https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9</a>"} 的完整 JSON。空、null、报错或只返回 URL 字符串（新版行为），都说明失败。
composer install 换源后报 hash 不匹配？删 vendor 和 lock 重来
立即学习“PHP免费学习笔记（深入）”；
镜像只加速下载，不改变包内容；但元数据同步有延迟，旧 composer.lock 记录的是官方源的哈希值，和新镜像返回的元数据不兼容。
- 首次配置镜像后，别试图保留旧
composer.lock - 直接删掉项目根目录下的
vendor/和composer.lock - 再执行
composer install（不是update），让 Composer 重新拉取元数据并生成新 lock 文件 - 如果用 CI 或宝塔部署，同样要确保构建前清理这两项，否则可能因哈希校验失败中断
composer config repo.packagist 在项目里执行会覆盖已有私有源
进项目根目录后执行不加 -g 的命令，看似方便，实则危险：它会全量替换 composer.json 中的 repositories 字段，不是追加。
- 原本有私有 Git 源（如
"my-vcs": {"type": "vcs", "url": "<a href="https://www.php.cn/link/892a87979eb79f4c51f589a3d1f60074">https://www.php.cn/link/892a87979eb79f4c51f589a3d1f60074</a>"}）？这条命令会直接清空整个repositories - 正确做法：手动编辑
composer.json，在repositories数组里加一条{"type": "composer", "url": "<a href="https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9">https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9</a>"}，同时确保顶层有"packagist.org": false（注意：不是写在repositories里面） - 或者用
composer config --merge（Composer 2.4+ 支持），但多数人环境版本不够，老老实实手改更稳
composer update 卡在 Resolving dependencies？和镜像无关
镜像只影响元数据检索和 tarball 下载阶段，不参与依赖解析。如果卡在这里，说明问题出在本地约束或包声明上。
-
"php": "^7.4 || ^8.0"这类宽泛版本约束会让 Composer 尝试大量组合 -
require-dev里塞了太多工具链（phpunit、phpstan、psalm同时存在） - 大量未锁定的 dev 分支引用，比如
"monolog/monolog": "dev-main" - 解法不是换镜像，而是收紧 PHP 版本、锁定关键 dev 包、拆分
require-dev到不同环境
真正容易被忽略的是执行用户权限问题：你在终端里用 root 配了全局镜像，但宝塔、Docker、CI 流水线实际以 www 或 runner 用户运行，它们读不到你的配置。
