Composer镜像加速：PHP项目依赖安装指南

命令未生效是因为四个硬性条件缺一不可：键名必须为单数repo.packagist、中间参数必须是composer（type值）、URL须以https://开头且末尾带/、必须加-g；任一缺失均静默回退至packagist.org。

composer config -g repo.packagist 命令为什么没生效

不是 Composer 没反应，是它静默失败了——根本不会报错，但所有请求照旧发往 packagist.org。必须同时满足四个硬性条件：

• repo.packagist（单数，不能写成 repos.packagist 或 packagist）
• 中间参数必须是 composer（这是仓库类型声明，漏掉就 fallback 到官方源）
• URL 必须以 https:// 开头且末尾带 /（https://mirrors.aliyun.com/composer/ ✅，https://mirrors.aliyun.com/composer ❌）
• 必须加 -g（不加就是项目级配置，会写进当前目录的 composer.json，不是你想要的全局效果）

验证是否成功：运行 composer config -g repo.packagist，输出应为 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} 或至少是完整 URL 字符串。如果为空、null、或仍是 https://packagist.org，说明完全没写进去。

项目里已有私有源，怎么安全加镜像

别跑 composer config repo.packagist composer https://mirrors.aliyun.com/composer/ ——这条命令会全量替换 composer.json 中的 repositories 字段，把你原有的 Git 私有源、Satis 源一并清空。

• 正确做法：手动编辑 composer.json，在 "repositories" 数组里追加一项：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
• 务必确保根节点（不是 repositories 内部）没有 "packagist.org": false ——写了这个，基础包如 php、ext-json 都校验失败
• 改完后删掉 vendor/ 和 composer.lock，再执行 composer install（不是 update），否则 hash 不匹配会报错

宝塔、CI、Docker 里镜像还是慢

你在终端用 root 执行了 composer config -g，但宝塔后台默认以 www 用户运行，GitHub Actions 用 runner 用户，Docker 容器里可能是 www-data 或自定义用户——它们读的是各自家目录下的 ~/.composer/config.json，跟你本地的配置完全无关。

立即学习“PHP免费学习笔记（深入）”；

• 排查方法：在对应环境里直接执行 whoami 确认用户，再用该用户身份运行 composer config -g repo.packagist 查看输出
• 给 www 用户配镜像：sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
• CI 脚本中别依赖全局配置，改用临时参数：composer install --repository=https://mirrors.aliyun.com/composer/

卡在 “Resolving dependencies” 不是镜像问题

镜像只加速元数据下载和 tarball 解压，不影响依赖解析阶段。“Resolving dependencies” 卡住，说明 Composer 正在本地暴力穷举满足 composer.json 所有约束的版本组合——尤其当你写了 "*"、"^1.0 || ^2.0" 或 "minimum-stability": "dev" 时，求解器会指数级爆炸。

• 删掉 "minimum-stability": "dev" ——稳定版能直接砍掉 80% 的求解时间
• 收紧 PHP 版本约束："php": "^8.1" 比 "php": ">=7.4" 少查几百个包的兼容性元数据
• 确保 composer.lock 已提交进 Git，并在部署中始终用 composer install（不是 update）
• 临时禁用 xdebug：php -d xdebug.mode=off $(which composer) install，它会让解析慢 5–10 倍

缓存路径落在机械盘、WSL2 挂载的 Windows 目录或加密卷上，I/O 就成瓶颈——这点最容易被忽略，但影响比换源还大。