适合新手PHP程序员的Composer镜像源教程-composer-PHP中文网

配镜像源需严格验证配置、清除缓存及旧文件，否则无效；全局配置易受用户环境影响，推荐项目级配置；换源后必须执行 composer clear-cache 并删除 vendor/ 和 composer.lock 才能生效。

适合新手php程序员的composer镜像源教程

配镜像源不是“换地址就行”，90% 的卡顿和失败都源于命令写错、用户错位或缓存残留——不验证、不清旧文件，换再多次也没用。

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

这条命令看着简单，但漏掉任意一个硬性条件，Composer 就会静默忽略，继续连 packagist.org，且不报错、不提示。

repo.packagist 必须拼写完全正确：多一个 s（repos.packagist）、大小写混用（Repo.Packagist）或加前缀（repositories.packagist）都会失效
composer 是强制 type 值，不能省略，也不能写成 vcs 或留空
镜像 URL 必须是 HTTPS，且末尾带 /：例如 https://mirrors.aliyun.com/composer/ ✅，少斜杠会拼出 /composerpackages.json 导致 404
必须加 -g 参数，否则只改当前项目 composer.json，换目录即失效

验证是否真写进去了，只看这一条命令输出：composer config -g repo.packagist。正确结果必须是完整 JSON：{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}；返回空、null 或报 Key not found，说明没写对，立刻重试。

项目级配置比全局更可靠

全局配置写在 ~/.composer/config.json 里，但在宝塔、GitHub Actions、Docker 或多用户环境下，执行命令的用户（如 www、runner）往往读不到你配的路径。项目级配置直接写进 composer.json，Git 可追踪、CI 可复现、新人拉代码就能用。

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

进项目根目录（确保有 composer.json），运行：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意：不加 -g）
它会自动在 composer.json 顶层添加或合并 "repositories" 字段，前提是原字段是对象 {}，不是数组 []；如果是数组，命令会报错，需先手动改成 "repositories": {}
别手写 "packagist.org": false 到某个仓库对象内部——它必须和 "packagist" 同级，放在 "repositories" 对象里，否则无效

项目级配置优先级高于全局，且不受用户上下文影响，团队协作时应默认采用这种方式。

换源后仍卡在 Loading composer repositories 或 Class not found

这不是镜像没切对，而是旧缓存和旧锁文件还在强行拉官方源地址。

先清缓存：composer clear-cache
必须删掉 vendor/ 和 composer.lock —— composer update 没用，它照着旧 lock 文件里的 dist.url（比如 https://api.github.com/）去下载，根本不会走新镜像
再执行：composer install -vvv，观察日志里首次请求的 packages.json 地址是不是 https://mirrors.aliyun.com/composer/packages.json
如果 vendor/autoload.php 存在但报 Class not found，大概率是依赖没装全，而不是 autoloader 问题；此时别乱改 autoload 配置，先确认 composer install 是否真正成功完成

阿里云 vs 腾讯云镜像怎么选

阿里云镜像同步最及时、CDN 覆盖最广，适合作为默认源；腾讯云镜像对某些新发布包延迟略高（通常 1–3 分钟），但稳定性好，适合已有私有源需并行的场景。

全局推荐阿里云：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
项目级临时切腾讯云：composer config repo.packagist composer https://mirrors.cloud.tencent.com/composer/
若 composer require xxx 找不到最新版，可临时回退官方源测试：composer config --unset repos.packagist
旧镜像如 https://packagist.phpcomposer.com 已停用，访问直接 404，务必核对 URL 是否有效

最关键的不是选哪家镜像，而是每次换源后都做三件事：验证配置输出、清缓存、删 vendor 和 composer.lock —— 少一步，就可能白忙一小时。