Composer 镜像源配置生效需满足三条件:项目级 repositories 字段为空、键名正确为 repos.packagist、URL 末尾含斜杠;元数据缓存需手动清理或备份;离线部署须确保 lock 文件有效、vendor 为空、PHP 与 Composer 环境一致。

确认镜像源是否真被 Composer 调用
很多人执行 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 就以为配置生效,但实际日志里仍是 Downloading https://packagist.org/packages.json。原因有三个:
- 项目级
composer.json中存在"repositories"字段(哪怕只是空数组[]),会完全屏蔽全局配置 - 键名写错:
repos.packagist(复数)才是 Composer ≥ 2.2 的正确写法,repo.packagist在新版中静默忽略 - URL 缺少末尾斜杠:
https://mirrors.aliyun.com/composer❌ 返回 404;https://mirrors.aliyun.com/composer/✅ 才有效
验证方式:运行 composer install -vvv | head -n 5,第一行 URL 必须是镜像域名;再执行 composer config -g repo.packagist,输出必须是完整 JSON 对象或带斜杠的 HTTPS URL。
手动备份 packages.json 和 provider-*.json 文件
Composer 的元数据缓存不是靠 composer clear-cache 清掉的——它只删 ZIP 包和部分文件缓存,对决定“有没有这个包”的 packages.json 和 provider-*.json 几乎无效。这些文件藏在 ~/.composer/cache/repo/https---mirrors-aliyun-com-composer/ 这类路径下(URL 中的 / 被转义为 ---)。
- 先查路径:
composer config --global cache-dir - 再进
repo/子目录,找对应镜像的转义目录:ls -d $(composer config --global cache-dir)/repo/https---* - 手动打包整个目录:
tar -czf composer-repo-backup.tgz $(composer config --global cache-dir)/repo/https---mirrors-aliyun-com-composer - Windows 用户路径类似:
%APPDATA%\Composer\cache\repo\https---mirrors-aliyun-com-composer,需用 7-Zip 或 PowerShell 压缩
备份后可在断网机上解压还原,让 composer install 读到本地元数据,避免卡在 Could not fetch packages.json。
使用 circleci/circleci-cli 和 circleci/orb-tools-orb SDK 来组合和验证 CircleCI Orbs。自动化 orb 打包、使用 conventional-changelog 进行语义化版本控制,并发布到 CircleCI Orb Registry。
网络中断时强制刷新元数据而非重试旧缓存
直接换镜像源不能解决同步中断——它只改了请求目标,没动 Composer 的元数据缓存策略和并发行为。真正卡住你的,是 packages.json 本地缓存过期后仍被复用,加上并发下载触发 TLS 复用失败,导致中途 reset 或 timeout。
- 用
composer update --refresh强制重拉packages.json等元数据,跳过本地缓存校验 - 加
--no-plugins --no-scripts防止插件或脚本隐式触发额外请求 - 若已中断,别急着
clear-cache,先删掉对应镜像的 repo 目录:rm -rf $(composer config --global cache-dir)/repo/https---mirrors-aliyun-com-composer - 再跑
composer show monolog/monolog,确认是否重新拉取成功
离线环境部署前必须检查的三个硬性条件
元数据备份只是辅助手段,真要扛住网络抖动或彻底断网,必须提前验证以下三点是否满足:
-
composer.lock文件必须存在且 JSON 格式合法(可用php -l composer.lock快速验证) -
vendor/目录不能提前存在——离线部署要求 clean slate,否则旧包可能干扰锁文件比对 - PHP 环境必须一致:版本号(含小版本)、启用的扩展(
mbstring、openssl、zlib)、以及 Composer 自身版本(建议与构建机完全相同)
特别注意:composer.json 里写的 "require" 版本范围(如 "^8.0")在离线时毫无意义——composer install 只读 composer.lock,不解析任何版本约束。备份元数据能缓解中断,但无法绕过环境一致性这个底层前提。

















