正确配置 composer config -g repo.packagist 是提升本地 php 开发效率的关键，需严格满足三个条件：键名必须为 repo.packagist（不能多 s）、第二个参数必须是 composer、url 必须为 https 且末尾带斜杠；否则静默失效。
composer config -g repo.packagist 这条命令配对了，本地 PHP 开发效率才能真正提起来。不配镜像，composer install 卡在 Downloading 或 Loading composer repositories 是常态，不是你网络差，是默认连 packagist.org 的物理链路和 TLS 握手根本扛不住国内环境。
为什么 composer config -g repo.packagist 总是没效果
90% 的失败不是网络问题，而是三个硬性条件漏掉一个就静默失效：
-
repo.packagist不能写成repos.packagist或repositories.packagist——多一个s，命令不报错但完全不生效 - 第二个参数必须是
composer，这是仓库类型声明，漏掉会导致 Composer fallback 到官方源（尤其在旧版中更隐蔽） - URL 必须是 HTTPS + 末尾带斜杠：
https://mirrors.aliyun.com/composer/✅，https://mirrors.aliyun.com/composer❌（少斜杠会拼接出错，返回 404）
验证是否成功：运行 composer config -g repo.packagist，输出必须是完整 JSON 对象，例如 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}。空、null、或仍显示 https://packagist.org 都说明没写进去。
宝塔、CI、systemd 里镜像不生效？用户权限搞错了
宝塔面板点「一键部署」卡住，不是镜像没配，而是它用 www 用户执行命令，而你 composer config -g 配的是当前登录用户（比如 root）的配置。
PHP 8.5.5 查实际执行用户：在宝塔【终端】里运行 sudo -u www composer config -g repo.packagist，如果为空，说明该用户没配。
正确做法：用对应用户重配，例如：
sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
CI 脚本或 systemd 服务同理——别依赖全局配置，改用临时参数更可靠：
composer install --repository-url=https://mirrors.aliyun.com/composer/
项目级配置比全局更安全，但命令会清空已有私有源
进项目根目录后执行 composer config repo.packagist composer https://mirrors.aliyun.com/composer/（不加 -g），这条命令不是追加，而是全量替换composer.json 中的 repositories 字段。
如果你原本已定义 Git 私有源（如 "my-vcs": {"type": "vcs", "url": "https://git.example.com/pkg"}），执行后整个 repositories 会被清空。
想保留私有源，得手动编辑 composer.json，确保 repositories 是对象格式，并显式包含 packagist 镜像项，同时保留 "packagist.org": true（千万别写 false）。
改完必须删掉项目里的 vendor/ 目录和 composer.lock 文件，再执行 composer install（不是 update）。
验证镜像是否真在用？看日志，别只信输出
composer config -g repo.packagist 输出正常，不代表请求真发到了镜像站。最直接的验证方式是加 -vvv 参数跑一次安装：
composer install -vvv 2>&1 | grep -i 'mirrors\.aliyun\|tuna\.tsinghua'
如果看到类似 Downloading https://mirrors.aliyun.com/composer/p2/topthink/framework.json 的日志，才算真正走通。
另外注意：composer diagnose 也会检查当前活跃仓库，但它的输出容易误读——重点看 Repo.packagist 行是否匹配你设的域名，而不是只看 OK 字样。
镜像同步有延迟（阿里云通常 ≤5 分钟），但若某包在镜像站查不到，Composer 2.9.6 不会自动 fallback，而是直接报错。这时候临时换源或等几分钟再试，比怀疑配置更高效。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
