🚀 远程 Mac 或 GitLab Runner 跑 PHP 流水线时，Composer 常见瓶颈是跨境超时、私服鉴权与
composer.lock 漂移。下文含 镜像链对照表、composer config 示例、并行与代理退避及缓存键。延伸阅读 Gradle Maven 矩阵、Git npm 镜像优化、拉取重试 FAQ；首页、博客、购买、帮助免登录。
场景与瓶颈：跨境拉取超时、鉴权与 lock 一致性
1）跨境超时：多 Job 并发打海外索引时往返时延放大，易出现连接错误与元数据卡顿。
2）鉴权断裂：GitLab 私库或 Satis 若令牌主机名、只读权限或受保护变量未对齐，下载阶段直接四零一。
3）锁文件漂移：流水线上误跑更新会改 composer.lock；源列表不一致触发哈希校验失败；缓存键过粗会串包。
| 决策维度 | 优先选型 | 谨慎场景 |
|---|---|---|
| 源拓扑 | 企业聚合镜像优先，公网镜像兜底 | 仅单一境外源且无退避 |
| 安装命令 | 提交锁文件后仅用安装命令只读还原 | 在共享机上随意更新依赖 |
| 并行度 | 限制并发连接并观察磁盘队列 | 默认最大并发顶满弱网出口 |
Packagist、国内镜像与企业私服：链式回源对照表（可执行 composer config）
原则：企业源在前，完整索引在后；关默认官方源时须显式备用。
| 源角色 | 典型用途 | 可执行配置示例 |
|---|---|---|
| 企业私服或 Satis | 内网包、审计、白名单版本 | composer config repositories.corp composer https://packages.example.com |
| 国内公共镜像 | 跨境加速稳定 dist 下载 | composer config repositories.aliyun composer https://mirrors.aliyun.com/composer/ |
| 官方 Packagist | 镜像缺包或合规允许直连 | composer config repositories.packagist composer https://repo.packagist.org |
| GitLab 私有 Composer 包 | 组内发布的路径型仓库 | composer config repositories.gitlab vcs https://gitlab.example.com/group/pkg.git |
关默认官方源可在 composer.json 的 repositories 写 "packagist.org": false 再列镜像。切换后 composer clear-cache；改锁文件须评审。
与 GitLab CI 并行：HTTP 代理与重试退避清单
参数与行为清单
- 并发封顶：
COMPOSER_MAX_PARALLEL_HTTP=8~12，共享机先低后升。 - 非交互：
COMPOSER_NO_INTERACTION=1；超级用户变量仅在有审计时用。 - 代理：
HTTPS_PROXY出口，NO_PROXY写内网 GitLab 与私服。 - 令牌：受保护变量拼
COMPOSER_AUTH（gitlab-token或http-basic），主机名与配置一致。 - 退避：壳层
sleep 2/4/8重试三次；限流先降并发。
矩阵 Job 可错峰拉取或组级预热；失败日志进产物便于看重试与响应头。
远程 Mac 上缓存目录、COMPOSER_CACHE_DIR 与 CI 缓存键
共享盘建议 COMPOSER_CACHE_DIR=$CI_PROJECT_DIR/.composer-cache，避免主目录争用；远程 Mac 可独立数据盘或软链到高速盘。
GitLab cache:key:files:[composer.lock] 加前缀区分分支；锁变则冷启动防串包。缓存暴涨先查中断临时文件。
export COMPOSER_CACHE_DIR="$PWD/.composer-cache"
composer install --no-dev --no-interaction --prefer-dist
五步落地（远程 Mac 与 GitLab 通用）
按序执行
- ①
composer validate --no-check-publish，锁文件已提交。 - ② 写入
repositories顺序，流水线打印composer config -l。 - ③ 配好
COMPOSER_AUTH与NO_PROXY，跑下载冒烟。 - ④ 封顶并行加二四八退避，看失败率与耗时。
- ⑤ 锁文件缓存键上线，记录冷启动与命中。
FAQ：401、限流与哈希校验失败
私服或 GitLab 包返回 401？
核对主机名与令牌键；权限含读库；合并请求检查变量是否注入。
遇到 429 或明显限流？
降并行、合并重复流水线、走企业聚合源，必要时夜间预热。
content-hash 或校验失败？
清空本 Job 缓存目录；勿混用源码与发行包；查代理是否截断大包。
锁文件与 CI 解析不一致？
比对源列表、插件与 PHP 小版本；同镜像复现后再改锁并评审。