Composer install卡在Downloading的主因是镜像未生效：必须严格执行composer config -g repo.packagist composer https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9，键名、type值、URL末尾斜杠缺一不可；项目级repositories会覆盖全局配置；还需启用parallel-downloads 8提升并发。

composer install 卡在 Downloading... 不是网络问题，大概率是没配对镜像源，或者配了但被覆盖、没生效。

---

composer config -g repo.packagist 命令必须写对

这条命令是全局镜像配置的核心，错一个字符就白配：

• 键名是 repo.packagist，不是 repos.packagist（多一个 s 就完全不认）
• composer 是 type 值，不能省略，也不能写成 composer-type 或其他变体
• URL 必须以 https:// 开头，且结尾带斜杠 /，例如：
  • ✅ 正确：<a href="https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9">https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9</a>
  • ❌ 错误：<a href="https://www.php.cn/link/f3ed1977e3554ea76e333ff63ff2e940">https://www.php.cn/link/f3ed1977e3554ea76e333ff63ff2e940</a>（缺末尾 /）
  • ❌ 错误：<a href="https://www.php.cn/link/9d3c8a28bff4572cbe0221dcc6b489cc">https://www.php.cn/link/9d3c8a28bff4572cbe0221dcc6b489cc</a>（用 http 可能被拒绝）

验证是否写入成功：运行 composer config -g repo.packagist，输出应为类似这样的 JSON：

{"type": "composer", "url": "https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9"}

---

项目级 repositories 会直接屏蔽全局镜像

Composer 的源优先级是：项目级 > 全局 > 默认源。只要当前目录下 composer.json 里有 repositories 字段，全局配置就自动失效——哪怕它是个空对象。

常见踩坑点：

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

• "repositories": {} → 全局镜像被静默屏蔽
• "repositories": [] → 运行 composer config repo.packagist 会报错
• "packagist.org": false 却没定义新的 packagist key → 所有包都拉不到

安全写法（直接编辑 composer.json）：

{
  "repositories": {
    "packagist": {
      "type": "composer",
      "url": "https://www.php.cn/link/1569ae888190eb8c53b218b0d529e1e9"
    }
  }
}

注意：packagist 是固定 key 名，不能改成 aliyun 或其他名字。

---

parallel-downloads 不开，再快的镜像也跑不满带宽

Composer 2.2+ 支持并行下载，但默认只开 3 个并发线程。相当于把 10Gbps 网络压成 300Mbps 用。

执行这条命令启用高并发： composer config -g parallel-downloads 8

• 推荐值是 8；设为 10 容易触发临时文件句柄不足或 DNS 并发限制
• 该配置仅对 Composer 2.2+ 生效；低于此版本需升级或改用 --prefer-dist + 清缓存组合技

---

镜像地址本身不是万能解药，真正卡住的往往不是“没换源”，而是“换错了位置”“被覆盖了”“并发锁死了”。尤其在团队项目里，composer.json 里一行 repositories 就能让所有人的全局配置形同虚设。