Composer镜像代理是企业应对开源供应链中断的核心缓冲层，通过Nginx反向代理+缓存+鉴权实现统一管控、安全审计与私有包共存，避免因packagist.org不可达导致CI中断或上线延期。
Composer 镜像代理不是“换源”那么简单，而是企业应对开源供应链中断的核心缓冲层。当 packagist.org 因网络策略、区域封锁或服务故障不可达时，本地镜像能维持 composer install 和 composer update 的连续性，避免构建卡死、CI 中断、上线延期。
为什么不能只改 composer.json 的 repos 配置？
单纯在项目级 composer.json 里写死镜像地址（如 "https://packagist.phpcomposer.com"）有三个硬伤：
- 无法统一管控：每个项目自行配置，镜像地址、超时策略、缓存有效期不一致，安全扫描和审计无从下手
- 绕过权限体系：镜像未做鉴权，任何人都能拉取敏感内部包（比如含密钥的私有 SDK），也拦不住恶意依赖注入
- 不兼容私有包托管：Composer 私有仓库（如 Satis 或 Private Packagist）需与镜像共用认证/路由逻辑，单独改
repos会导致composer require找不到私有包
推荐架构：Nginx + Proxy Cache + Auth Request 模块
真正可落地的企业级方案，是用 Nginx 做反向代理层，而非直接部署 Satis 或 Toran。它轻量、可控、易观测，且能复用现有运维能力。
关键配置要点：
-
proxy_cache_path必须挂载到 SSD 或高速 NAS，避免缓存写入成为瓶颈；建议设置max_size=100g inactive=7d - 对
/packages.json和/p2/路径启用proxy_cache_valid 200 302 1h，但对具体 ZIP 包（/dist/）设为24h，防止频繁重下载 - 必须启用
auth_request模块对接企业 LDAP/OAuth2，所有请求先过鉴权网关；未授权用户返回401，不走缓存也不透传上游 - 在
location /块中添加add_header X-Composer-Cache $upstream_cache_status;，便于排查缓存命中率
常见故障：404 Not Found 却日志显示 upstream 200
这是最典型的镜像代理误配置现象——Nginx 缓存了上游的 404 响应（比如某个包被作者删了），后续请求直接返回缓存的错误页，根本没发给 packagist.org。
解决方法只有两个：
- 在
proxy_cache_valid中显式排除 404：proxy_cache_valid 200 302 1h; proxy_cache_valid 404 1m; - 定期用脚本清理过期 404 缓存：
find /var/cache/nginx/composer -name "*404*" -mmin +60 -delete
别信“清空缓存目录就能好”——Nginx 会重建缓存索引，旧 404 条目仍可能被复用。
私有包与镜像共存的关键路径规则
企业往往既有公有依赖（laravel/framework），也有自研私有包（corp/utils）。必须让 Composer 客户端无感切换，靠的是 composer config --global repositories 的优先级机制和 Nginx 的路由分流。
正确做法是：
- 在全局配置中声明两个仓库：
composer config --global repositories.packagist composer https://repo.packagist.org和composer config --global repositories.corp composer https://private.corp.com - Nginx 根据 Host 头或路径前缀分流：
if ($host ~* "^private\.corp\.com$") { proxy_pass https://satis-backend; }，其他全部走镜像代理 - 确保私有仓库的
packages.json中所有 dist URL 都走https://private.corp.com/dist/xxx.zip，而非绝对公网地址，否则镜像层无法拦截
漏掉最后一点，私有包 ZIP 文件就会绕过镜像直连内网，一旦网络分区，composer install 会卡在 “Downloading xxx.zip” 并超时。
