Composer装不上或慢90%非网络问题，而是镜像未生效（repo.packagist键名必须单数、type值必填composer、URL末尾须带/）、缓存未清、配置写错或权限不对；需执行config -g三命令并clear-cache验证。
Composer装不上、装得慢，90%不是网络问题，而是镜像没生效、缓存没清、配置写错或权限没对。装完不配加速项，第一次 composer install 就会卡在 downloading 或 Resolving dependencies，实际耗时可能比安装本身长 10 倍。
为什么 composer config -g repo.packagist 总是静默失败
这条命令极易“看似成功实则无效”，必须同时满足三个硬条件：
-
repo.packagist不能写成repos.packagist（多一个s就被完全忽略） - 中间必须带
composer这个 type 参数：composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/✅；漏掉composer就 fallback 到默认源 ❌ - URL 必须是 HTTPS + 末尾带斜杠：
https://mirrors.aliyun.com/composer/✅；https://mirrors.aliyun.com/composer❌（少斜杠会 404）
验证是否真正生效：运行 composer config -g repo.packagist，输出必须是类似 {"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} 的完整 JSON 对象。空、null 或仍是 https://packagist.org 都说明没写进去。
装完立刻要跑的三行加速命令
别等第一次 composer install 卡住才补——此时缓存已污染，重配也白搭：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/-
composer config -g parallel-downloads 10（Composer 2.2+ 支持，旧版用concurrent.http.max-parallel-downloads） composer config -g prefer-dist true
执行完必须立刻 composer clear-cache。否则它仍从旧缓存读 packages.json 和元数据，镜像等于白配。验证方式：分别运行 composer config -g repo.packagist、composer config -g parallel-downloads、composer config -g prefer-dist，三个都应输出对应值。
项目级配置覆盖全局？查这三点
换源后还是慢，大概率是项目自己“不听话”：
- 检查项目根目录
composer.json是否有repositories字段——它会直接覆盖全局repo.packagist配置 - 运行
composer config --list和composer config --list --global对比，确认实际生效的是哪个配置 - 宝塔、CI 或计划任务常以
www用户运行，但composer config -g写的是root配置（路径为/root/.composer/config.json），www根本读不到；应切到对应用户下执行：sudo -u www composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
--prefer-dist 不是万能开关，这些情况它会直接失败
强制走 dist 模式只在特定场景有效，多数时候默认策略已最优：
- 包没发布 dist（比如 dev 分支、私有 GitLab 未配
dist字段）→ 报错Could not find a matching version of package xxx - 项目
composer.json里写了"prefer-source": true→ 它会覆盖全局prefer-dist，必须手动删掉 - PHP ZIP 扩展未启用或版本低于 7.2 → 解压失败，报错
ZipArchive::extractTo(): Invalid or uninitialized Zip object - Windows 路径含中文 → 某些 ZIP 包解压后文件名乱码，自动 fallback 到 source，但不会提示原因
真正影响速度的关键从来不是加不加 --prefer-dist，而是镜像是否生效、缓存是否干净、xdebug 是否关闭、parallel-downloads 是否设到 10。Resolving dependencies 阶段完全不走网络，卡住跟镜像无关，只跟 composer.json 里的版本约束松紧度有关——写 "*" 或 "^1.0 || ^2.0" 会让求解器指数级爆炸。
