项目专属镜像更可控，因它仅作用于当前项目composer.json中的repositories字段，避免全局配置覆盖导致CI异常、私有包失效等问题；必须用复数"repositories"、键名"packagist"、URL末尾带斜杠，并重生成composer.lock才能生效。
项目专属镜像不是全局替换，而是让当前项目只走指定源，避免影响其他项目或 CI 环境。它比全局配置更可控，也更容易调试依赖冲突。
为什么不能只用 composer config -g
全局配置（composer config -g repo.packagist）会覆盖所有项目的源行为，CI 脚本、私有包拉取、多 PHP 版本共存时容易出问题。项目专属配置则写在当前项目的 composer.json 里，只生效于该目录及其子命令执行上下文。
- 全局镜像失效时，项目仍可能 fallback 到 packagist.org —— 因为 Composer 2.x+ 优先读项目级
repositories - 私有包仓库和公共镜像混用时，必须靠项目级
repositories显式声明顺序 -
composer install时若没加--no-cache，但 PHP 小版本变了（比如从 8.3.5 升到 8.3.6），缓存仍不命中 —— 这和镜像配置无关，但常被误判为“镜像没生效”
正确写法：在 composer.json 中声明 repositories
直接编辑项目根目录下的 composer.json，在顶层 JSON 对象中添加 repositories 字段。注意不是 repo.packagist，也不是 repos.packagist，必须是复数 repositories，且结构要合法。
示例（阿里云镜像）：
{
"name": "laravel/laravel",
"type": "project",
"repositories": {
"packagist": {
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
}
},
...
}
- 键名必须是
"packagist"（小写，单数），不是"packagist.org"或"default" -
url必须以https://开头，末尾带斜杠，否则返回 404 - 改完后运行
composer update --lock或删掉composer.lock再composer install，否则旧 lock 文件会继续走历史源
混合源场景：私有包 + 阿里镜像共存
如果你的项目同时引用公司私有包（如 mycorp/utils）和 Laravel 官方包，不能只配一个 packagist，得把私有源放在前面，再 fallback 到镜像：
"repositories": [
{
"type": "composer",
"url": "https://packages.mycorp.com"
},
{
"packagist": false
},
{
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
}
]
- 数组形式声明，顺序即优先级：先查私有源 → 关闭默认 packagist → 最后走阿里镜像
-
"packagist": false是关键，否则 Composer 仍会悄悄连官方源查元数据 - 不要漏掉
composer update --lock，否则composer.lock里记录的还是旧 provider 地址
验证是否真正生效
别只看下载速度，要看实际请求路径和缓存行为：
- 运行
composer install -vvv，观察日志里是否出现https://mirrors.aliyun.com/composer/p/provider-laravel~10.0.json类似路径 - 检查
vendor/composer/installed.json里的dist.url，应为阿里镜像域名下的 ZIP 地址，而非github.com或packagist.org - 如果仍卡在
Downloading packages.json，大概率是composer.json里repositories结构写错，或composer.lock没刷新
项目专属镜像真正的难点不在配置语法，而在于锁文件、PHP 平台约束、私有源权限三者的耦合 —— 改完 composer.json 后，一定要重生成 lock 文件并确认 vendor 下载来源。
