Composer中文镜像，PHP开发者提效的神器！-composer-PHP中文网

composer中文镜像是解决安装卡死、包找不到等痛点的刚需，配置需满足单数小写repo.packagist、type为composer、https加末尾斜杠三条件，否则静默降级；项目级配置比全局更可靠，且镜像不加速依赖解析和新包同步延迟。

composer中文镜像，php开发者提效的神器！

Composer中文镜像不是“锦上添花”，而是解决composer install卡死、could not find package报错、新人半天配不好环境的刚需。配对了，速度能从5分钟压到15秒；配错了，它会静默走回https://packagist.org，你还以为是网络问题。

为什么`composer config -g repo.packagist`总不生效？

90% 的失败不是网络或镜像本身，是命令写错三个硬性条件，且 Composer 不报错、不提示、不 fallback —— 它直接忽略配置，默默连官方源。

repo.packagist 必须是单数、小写、无 s：写成 repos.packagist 或 packagist.org 都无效
中间的 composer 是 type 值，不是可选参数：漏掉就当普通仓库处理，元数据请求仍发往官方源
url 必须是 HTTPS + 末尾斜杠：比如 https://mirrors.aliyun.com/composer/，少斜杠会拼出 /composerpackages.json 导致 404，然后静默降级
Windows 用户改完没重启终端，PHP 进程读不到新环境变量；Linux/macOS 下若用 sudo 执行，实际生效的是 root 配置，而构建用户可能读不到

怎么确认当前走的是哪个源？

别信命令输出，也别看 composer diagnose —— 它只检查语法和本地连通性，不验证镜像是否真在服务。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

运行 composer config -g repo.packagist，正确结果必须是完整 JSON：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}
返回空、null、或纯字符串如 https://packagist.org → 没写进去，立刻重试
即使全局配置成功，项目级 composer.json 中的 repositories 字段仍会优先覆盖它，且不报任何警告
想绕过所有配置临时验证，加 --repository-url= 参数跑一次：composer show laravel/framework --repository-url=https://mirrors.tuna.tsinghua.edu.cn/composer/

项目级配置比全局更可靠，尤其在 CI 和协作中

GitHub Actions、GitLab CI、宝塔面板默认以 www 或 runner 用户运行，它们根本读不到你本地用户的全局配置。项目级配置写进 composer.json，一提交就同步，行为可预期。

进项目根目录，执行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意：不带 -g）
它会自动在 composer.json 顶层生成或更新 "repositories" 对象，key 固定为 "packagist"，不会覆盖已有私有源
如果项目已有 "repositories": [] 数组结构，这条命令会失败；此时需手动编辑，确保格式合法，且不要写 "packagist.org": false 这类禁用项
改完务必删掉 vendor/ 和 composer.lock，再跑 composer install —— 否则旧锁文件仍指向官方源的包哈希

换镜像后还是卡在 “Resolving dependencies”？那和镜像无关

镜像只加速下载，不参与依赖解析。如果你发现 composer update 卡在 “Resolving dependencies” 几十秒甚至几分钟，说明问题出在约束逻辑本身：

"php": "^7.4 || ^8.0" 这类宽泛版本约束会让 Composer 尝试遍历大量不兼容组合
require-dev 里塞了太多未锁定版本的工具链（如 phpunit/phpunit: ^10.0），每次都要重新求解
用了大量 dev-main 或 vcs 类型包，Composer 得逐个 fetch 元数据，而镜像不缓存这些动态内容
这类问题换阿里云、清华、SJTUG 任意镜像都无效，得收紧约束、拆分 require-dev、用 composer.lock 锁死版本

最常被忽略的一点：镜像同步有天然延迟窗口。刚发布的包，哪怕只差 3 分钟，也可能在镜像里查不到 —— 此时 Composer 会 fallback 到官方源，而国内直连大概率超时失败。遇到 Package not found，先 curl -I https://mirrors.aliyun.com/composer/packages.json 看状态码，再决定是等几分钟，还是临时切回官方源拉一次。