局部修改比全局配置更可靠，因为全局配置仅对当前用户生效，在宝塔（www用户）、ci/cd（runner用户）或docker容器中常因用户权限或目录缺失而根本未被读取；项目级配置直接写入composer.json的repositories字段，路径明确、环境无关、可git跟踪。
为什么局部修改比全局配置更可靠
全局镜像配置（composer config -g repo.packagist）在宝塔、CI/CD 或 Docker 容器里经常失效——不是优先级低，是压根不被读取。比如宝塔用 www 用户执行命令，而你用 root 配的全局配置，www 根本看不到 ~/.composer/config.json；GitHub Actions 默认没有 ~/.composer 目录。项目级配置写进 composer.json 的 repositories 字段，路径明确、权限可控、环境无关。
执行局部镜像配置的正确命令
进项目根目录后运行这条命令：
composer config repo.packagist composer https://mirrors.aliyun.com/composer/
注意三点：
- 不加
-g参数，否则改的是全局配置 - 键名必须是
repo.packagist（单数，不能是repos.packagist或repositories） - URL 必须以
/结尾，否则拼出/composerpackages.json导致 404
执行后检查 composer.json 是否新增了这段：
"repositories": {
"packagist": {
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
}
}
如果原来就有 "repositories": []，得先手动改成 "repositories": {} 再运行，否则报错。
局部配置后仍卡住或报错的排查点
局部配置生效后还卡在 Loading composer repositories，大概率是缓存或锁文件残留：
- 删掉
vendor/和composer.lock：它们硬编码了旧源地址，不清就一直重试失败路径 - 运行
composer clear-cache：尤其要清掉~/.composer/cache/files/下可能损坏的 ZIP - 验证真实请求地址：用
composer install -vvv 2>&1 | head -n 10 | grep Downloading，第一行 URL 才是实际走的源 - Windows 用户注意：杀毒软件常静默拦截
.bat文件生成，换 Git Bash 或加--no-scripts
局部换源后 checksum 失败怎么办
镜像本身不改变校验逻辑，但坏缓存会让 composer install 拿着旧 ZIP 去新源上校验，必然失败。必须强制跳过缓存并启用校验：
composer install --no-cache --force-checksums
这个组合有三重作用：
-
--no-cache：跳过~/.composer/cache/files/，从镜像重新下载 ZIP -
--force-checksums：校验失败时立刻退出，不尝试解压损坏包，避免污染vendor/ - 不带
--no-dev或--prefer-dist，防止因参数干扰掩盖真实问题
真正容易被忽略的是：哪怕你配对了镜像，只要 composer.lock 没删、缓存没清、checksum 没强制，它就永远在旧错误路径上循环。
