镜像源配置错误导致安装卡死，主因是URL末尾多斜杠、协议错误或使用已下线地址，Composer会静默回退至packagist.org；应执行composer config -g repo.packagist composer https://mirrors.aliyun.com/composer（无尾部斜杠），清除项目级配置并验证输出，同时注意ZIP包同步延迟及私有仓库需单独配置。
镜像源配置错误导致安装卡死
国内用户配错镜像 URL 是最常见中断原因，比如末尾多加斜杠、协议写错、或用了已下线的旧地址。Composer 会静默回退到 packagist.org，但不报错，只在 downloading 阶段无限等待。
验证当前镜像是否生效：composer config -g repo.packagist。正确输出应为 https://mirrors.aliyun.com/composer/（注意：无尾部斜杠）；若显示 packagist.org 或带斜杠的 URL，说明配置未生效或被覆盖。
修复方式：
- 执行
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer（结尾无斜杠） - 删掉项目级配置（如有）：
composer config --unset repos.packagist.org - 确认全局配置优先级高于项目级：运行
composer config -g --list --verbose | grep "repo.packagist"，确保只出现一次且值正确
镜像同步延迟引发的 ZIP 下载失败
阿里云、腾讯云等镜像站虽快，但 dist ZIP 包并非实时同步——元数据（packages.json）更新快，而实际 ZIP 文件可能滞后数分钟甚至更久。此时 Composer 会拿到新版本号，却从镜像站拉不到对应 ZIP，最终报 Failed to download vendor/package: file not found 或 404。
这不是网络问题，而是镜像站缓存未就绪。临时绕过方式：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 加
--prefer-dist强制走 dist（避免 fallback 到慢速 git clone） - 用
composer install --no-cache --verbose查看具体失败 URL，再手动curl -I测试该 ZIP 地址是否返回200 - 若确认是镜像延迟，可临时切回官方源试装：
composer config -g repo.packagist composer https://packagist.org（仅限单次）
私有包或 GitHub 依赖未配置独立仓库
镜像源只代理 packagist.org 的公开包，对 github.com、gitlab.com 或私有 Git 仓库的依赖完全无效。一旦 composer.json 中含 "type": "package" 或 "repositories" 指向非 packagist 源，Composer 仍会直连原始地址，极易因 DNS 或 TLS 卡住。
必须显式配置对应仓库：
- 对 GitHub 包，加
"repositories": [{"type": "vcs", "url": "https://github.com/vendor/repo"}]到composer.json - 对私有 GitLab，用
"type": "git"并确保 SSH key 或 token 可用 - 禁用自动 fallback：
composer config -g github-protocols https，避免 ssh 协议触发交互式提示
镜像响应异常时的 fallback 行为不可控
当镜像站返回 503、504 或空响应时，Composer 默认不会自动重试其他源，也不会降级到本地缓存，而是直接中断并报 cURL error 7 或 Connection refused。它不区分“源不可用”和“包不存在”，统一按失败处理。
降低 fallback 失败风险的操作：
- 启用并行下载但限制并发数：
composer config -g parallel-downloads 6（Docker 环境尤其重要，避免临时文件竞争） - 设重试次数：
composer config -g http.max-retries 3（Composer 2.2+ 支持） - 禁用非必要环节：
composer install --no-scripts --no-plugins --no-dev，减少因脚本超时引发的连锁失败
真正卡住时，别反复重试——先 composer clear-cache 清掉可能污染的临时 ZIP，再结合 --dry-run 看哪些包被跳过，哪些还在列 Installing。残留状态比想象中更脆弱，尤其是 vendor/composer/installed.json 被截断后，后续所有 autoload 都会失效。
