composer在国内必须配置中文镜像源，否则因dns解析慢、tls握手超时等导致卡在downloading或报错；正确命令为composer config -g repo.packagist composer https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9，键名、type值、url结尾斜杠三者缺一不可。
composer 默认直连 packagist.org，在国内基本没法用——不是慢，是常卡在 Downloading、报 could not find package 或直接 TLS 握手超时。配中文镜像不是“锦上添花”，而是 PHP 项目能跑起来的前提。
composer config -g repo.packagist 命令总不生效？检查这三处硬性要求
composer config -g repo.packagist 静默失败是最常见的坑：不报错、不提示，但请求照旧发往海外源。
- repo.packagist 键名不能多一个 s（repos.packagist 是无效字段）
- 中间的 composer 是 type 值，必须显式写出，漏掉它就 fallback 到默认源
- URL 必须是 HTTPS 且末尾带 /：https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9 ✅，https://mirrors.aliyun.com/composer ❌（少斜杠会导致路径拼接出错，返回 404）
执行后立刻验证：composer config -g repo.packagist 输出应为完整 JSON，例如 {"type": "composer", "url": "@#@#@#@#@#@#@#@#@#@0"}。空、null 或报 Key does not exist，说明根本没写进去。
项目级配置比全局更可靠，尤其在 CI/CD 和团队协作中
全局配置依赖执行用户（比如你在终端用root 配了，但宝塔或 GitHub Actions 用 www 或 runner 用户运行，就读不到），而项目级配置直接写进 composer.json，拉代码即生效。
- 进项目根目录，运行：composer config repo.packagist composer https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9（不加 -g）
- 该命令会自动向 composer.json 的 repositories 字段追加条目，不覆盖已有私有源
- 如果项目已有 "repositories": {}，命令能安全 merge；如果是 "repositories": []（数组），命令会失败，需先手动改为对象格式
- 切记：别手写 "packagist.org": false，否则关掉基础源，镜像一宕就全崩
换源后仍卡在 Downloading？清缓存 + 重装是唯一解法
镜像只加速下载，但旧缓存里存着packagist.org 的元数据，Composer 会优先读缓存并尝试从旧地址校验——结果就是卡在 DNS 或 TLS 握手，根本没发请求到镜像。
- 先清缓存：composer clear-cache
- 删掉 vendor/ 和 composer.lock
- 再跑：composer install --no-cache（禁用缓存强制走新源）
- 别保留旧 composer.lock：它记录的是旧源的包哈希，和镜像返回的元数据不兼容，必然报 hash does not match怎么确认镜像真在用？看网络请求，别信 config 输出
composer config -g repo.packagist 只显示你设了什么，不显示是否被覆盖或是否生效。
- 实测命令：composer show monolog/monolog -vvv 2>&1 | grep "Downloading"
- 日志里必须出现 mirrors.aliyun.com 或 mirrors.tuna.tsinghua.edu.cn 等镜像域名
- 如果看到 https://packagist.org 或 repo.packagist.org，说明 fallback 触发了，配置没起作用
复杂点在于：项目级 repositories 字段一旦存在，全局配置就完全失效；而某些 IDE（如 PHPStorm）会缓存配置，改完得重启才识别。这些细节不踩一遍，很难意识到问题不在网络，而在配置链路本身。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
