项目级配置更可靠，因写入composer.json可提交Git、适配CI/CD及权限隔离环境；需运行composer config repo.packagist composer https://mirrors.aliyun.com/composer/，确保repositories为对象而非数组，并清缓存重装验证。
直接改 composer.json 的 repositories 字段
项目级配置比全局更可靠，尤其在 CI/CD、团队协作或宝塔等权限隔离环境中。它写进 composer.json，拉代码即生效，不依赖执行用户家目录下的 ~/.composer/config.json。
进项目根目录（确保有 composer.json），运行：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
这条命令会自动在 "repositories" 字段里追加 "packagist" 条目，不覆盖已有私有源——但前提是原 "repositories" 是一个空对象 {}，不是空数组 []。
- 如果
composer.json里已有"repositories": []，命令会失败；需先手动改成"repositories": {} - 如果已有
"repositories": {"my-private": {...}}，该命令会安全合并，生成{"my-private": {...}, "packagist": {...}} - 别手写
"packagist.org": false—— 这会彻底屏蔽镜像回退机制，镜像临时不可用时composer install直接中断
手动编辑 composer.json 的常见错误
手写容易出格式或语义错误，Composer 对 JSON 格式极其敏感，一个逗号错位或引号不闭合就会导致 composer install 报错。
正确结构必须是：
"repositories": {
"packagist": {
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
}
}
关键点：
-
"packagist"是键名，不是"packagist.org"或"repos.packagist" -
"type": "composer"不可省略，也不能写成"type": "composer-proxy"等无效值 -
"url"必须以https://开头，且末尾带/；少斜杠会拼出/composerpackages.json，返回 404 - 整个
"repositories"字段必须是对象（{}），不能是数组（[]）；否则 Composer 会忽略所有子项
改完后必须清缓存并重装
即使 composer.json 写对了，旧的 vendor/ 和 composer.lock 仍含官方源的包哈希与元数据，Composer 会优先读取它们并尝试从 packagist.org 校验，结果就是卡在 Downloading 或报 hash does not match。
必须执行：
composer clear-cache-
rm -rf vendor/ composer.lock（Windows 用rd /s/q vendor && del composer.lock） -
composer install --no-cache（禁用缓存，强制走新源）
注意：composer update 不会重新加载镜像配置，它只基于现有 composer.lock 解析依赖；要验证镜像是否真被使用，必须删 lock 文件后重装。
验证是否真正走镜像
光看 composer config repo.packagist 输出 URL 没用，得确认网络请求实际发到了镜像站。
最实锤的方式是抓一次真实请求：
curl -v -H"User-Agent: Composer/2.9.6" -H"Accept: application/json" https://mirrors.aliyun.com/composer/packages.json 2>&1 | grep "Connected to"
输出中必须出现 Connected to mirrors.aliyun.com 才算生效。如果看到 Connected to packagist.org 或卡在 DNS 解析，说明配置没起作用，或被更高优先级设置覆盖。
另外，运行 composer install -vvv，日志里出现的域名必须是 mirrors.aliyun.com（或你配的其他镜像域名），而不是 packagist.org。这点容易被忽略：很多开发者配完就跑 install，但没加 -vvv，根本看不到实际请求地址。
