换源是必做第一步，需全局切换至阿里云镜像；延长超时至600秒；强制ipv4避免fallback延迟；清缓存为失败后首要操作；ci/cd必须复用缓存。
换源不是可选项，是必做第一步
国内访问 packagist.org 默认走境外链路，DNS 解析慢、TLS 握手卡顿、连接超时是常态——这不是你网络差，是路由本身就不友好。不换源，其他优化效果微乎其微。
- 全局切换到阿里云镜像（推荐）：
composer config -g repos.packagist composer https://mirrors.aliyun.com/composer/ - 临时只对当前项目生效（CI/CD 或多源混用场景）：
composer config repos.packagist composer https://mirrors.aliyun.com/composer/ - 验证是否生效：
composer config -l | grep repos.packagist，输出应为阿里云地址，而非https://packagist.org
注意：别用已停服的 Laravel China 镜像（https://packagist.phpcomposer.com），它自 2025 年底起已不可用；腾讯云、华为云镜像虽可用，但阿里云节点稳定性和同步延迟目前最优。
超时不是等得不够久，是默认值根本不适合国内网络
Composer 默认 http.timeout 是 300 秒（5 分钟），process-timeout 是 300 秒——但实际下载一个大包（如 symfony/symfony 全量 dist）在弱网下很容易突破这个阈值，直接中断，且不重试。
- 延长全局超时（建议设为 600）：
composer config -g http.timeout 600和composer config -g process-timeout 600 - 单次命令临时加长（调试时更安全）：
COMPOSER_PROCESS_TIMEOUT=600 composer install - 如果公司内网强制代理，记得配好：
composer config -g http-proxy http://your-proxy:8080；否则会卡在 DNS 解析后无响应
别碰 disable-tls true——它关的是 HTTPS 验证，不是提速，而是埋下证书校验绕过和中间人风险，纯属掩耳盗铃。
IPv6 不是未来，是当前 Composer 卡住的隐形元凶
很多 Linux/macOS 环境默认启用了 IPv6，而 Composer 底层用 PHP cURL 发请求时，会先尝试 AAAA 记录（IPv6 地址）。一旦目标服务器或中间链路不支持 IPv6，就会卡在 Trying [2a02:xxxx::1]:443... 几秒后再 fallback 到 IPv4——这“几秒”在依赖上百个包时会累加成分钟级延迟。
- 强制走 IPv4（唯一可靠方式）：
COMPOSER_IPV4=1 composer install - 永久生效（Linux/macOS）：
echo 'export COMPOSER_IPV4=1' >> ~/.bashrc && source ~/.bashrc - Windows 用户：系统环境变量中添加
COMPOSER_IPV4 = 1
composer config 命令根本不能禁用 IPv6，所有试图通过 config 设置 github-protocols 或改 repositories 的做法都无效——这是底层网络栈行为，只能靠环境变量干预。
缓存不是锦上添花，是避免重复失败的关键防线
每次 composer install 失败后不清缓存就重试，大概率会复现相同错误。因为损坏的 zip 包、中断的元数据文件仍留在 ~/.composer/cache 里，Composer 会优先复用它们。
- 出错后第一反应不是重跑，而是清缓存：
composer clear-cache - 确认缓存路径：
composer config cache-dir，检查该目录是否可写（尤其 Docker 容器内挂载卷权限问题） - 手动补包应急（仅限某个包死活下不下来）：找到对应
cache/files/下的哈希目录，放入已下载好的 zip，再跑install，Composer 会跳过下载直接校验
最常被忽略的一点：CI/CD 流水线里没复用 Composer 缓存目录，等于每次从零开始下载——哪怕用了镜像，也白白浪费带宽和时间。BuildKit 的 --mount=type=cache 或 GitHub Actions 的 actions/cache 必须配。
