私有仓库拉取慢或超时主因是composer默认配置未适配其响应特征：需关闭并行、调高process-timeout与composer_process_timeout双超时、禁用use-include-path、强制--prefer-dist、挂载高速cache-dir，并避免误配镜像源。
私有仓库拉取慢或超时，基本不是网络“连不上”，而是 Composer 默认配置没适配私有源的响应特征：并发请求压垮内网 Git 服务、元数据缓存缺失、TLS 握手耗时高、没设重试策略。关键得关掉并行、调高超时、加缓存、绕过不必要校验。
composer config -g use-include-path false 为什么必须执行
默认开启时，Composer 会遍历 include_path 中所有目录查找类文件，哪怕你只用私有 Git 包——这在 CI 或 Docker 容器里极易触发 I/O 阻塞，尤其挂载卷路径深时。关掉它能避免无意义扫描，实测在 GitLab Runner 上减少 2–5 秒启动延迟。
操作建议：
- 全局执行：
composer config -g use-include-path false - 若项目依赖了某些老式 PEAR 风格包（极少见），才需保留；否则一律关闭
- CI 脚本中应放在
composer install前，避免被缓存覆盖
process-timeout 和 COMPOSER_PROCESS_TIMEOUT 双设置才保险
process-timeout 是 composer.json 或 config 中的字段，控制单个进程（如 git clone）最大等待时间；COMPOSER_PROCESS_TIMEOUT 是环境变量，优先级更高、且部分旧版 Composer（如 2.2.x）只认它。私有 GitLab/GitHub 仓库常因 SSH 密钥加载、Webhook 触发或自签名证书导致首字节延迟，光设 config 不够。
实操建议：
- 本地调试：运行
COMPOSER_PROCESS_TIMEOUT=600 composer install - CI 中（如 GitHub Actions）：在
env:下显式写COMPOSER_PROCESS_TIMEOUT: 600 - 别只信
composer config -g process-timeout 600，它对私有 VCS 源效果有限
私有仓库必须禁用 --prefer-source 的真实原因
私有 Git 仓库往往没托管 dist 包（zip/tarball），但 Composer 默认对 VCS 类型仍尝试走 --prefer-source（即 clone），而 clone 操作受 Git 协议、SSH 配置、服务器并发连接数限制极大。一次 git clone --depth=1 失败后默认只重试 1 次，远不如下载 zip 稳定。
解决办法是强制走 dist（如果私有源支持）：
- 确认私有 Packagist 镜像或 Satis 服务已启用 dist 构建（查看其
packages.json是否含"dist"字段） - 安装时加
--prefer-dist，并确保私有源 URL 是 HTTPS 形式（非 git@） - 若必须用 git@，则应在 ~/.ssh/config 中预设
ConnectTimeout和ServerAliveInterval，否则 SSH 层超时由系统决定，Composer 控不住
cache-dir 挂载到 /tmp 或 SSD 目录才能起效
私有包的 zip 缓存和元数据（repo/ 下的 JSON）若落在 NFS、Docker 默认 volume 或 Windows 共享盘上，解压一个 20MB 的 dist 包可能耗时 8 秒以上——缓存反而成瓶颈。Composer 默认缓存路径（如 $COMPOSER_HOME/cache）在容器里常指向低速层。
正确做法：
- 设为内存盘路径：
composer config -g cache-dir "/tmp/composer-cache" - CI 中用带版本号的路径防冲突：
COMPOSER_CACHE_DIR=$HOME/.composer-cache-$PHP_VERSION - 验证是否真用了新路径：
composer config -g cache-dir输出应为绝对路径，且ls -l $(composer config -g cache-dir)确认属主可写
私有仓库优化最易被忽略的点：镜像源配置对私有 VCS 无效，但很多人还在往 repo.packagist 里硬塞 GitLab 地址；真正要调的是 Git 协议层和缓存路径，而不是换源。另外，composer update 在私有环境中尽量少用，install + 锁文件才是稳定基础。
