搭建本地Composer镜像源同步服务器-composer-PHP中文网

composer config -g repo.packagist 仅修改客户端源地址，不部署镜像服务；真正搭建镜像需运行支持实时同步、缓存、校验的 http 代理服务（如 packagist-mirror 或 artifactory），satis 仅为静态生成器，不满足动态版本与全量同步需求。

搭建本地composer镜像源同步服务器

composer config -g repo.packagist 不是搭建镜像，只是换源

很多人执行 composer config -g repo.packagist composer https://your-mirror.internal/ 后以为“本地镜像建好了”，其实这只是把 Composer 的元数据请求地址指向了你指定的 URL——背后那个服务还得你自己搭。如果该 URL 没有运行真正的镜像服务（比如 packagist-mirror 或 Satis），Composer 会直接报 Could not fetch packages.json 或卡在 Loading composer repositories。

关键区别在于：

composer config 是客户端配置，不部署任何服务
真正“搭建镜像源”意味着你得运行一个能响应 /packages.json、/p2/vendor/name/1.0.0.json 等路径的 HTTP 服务
镜像服务必须能缓存、同步、重写、校验官方源的元数据和 ZIP 包，不是简单 rsync 或 nginx 目录索引就能替代

用 Satis 只适合离线/少量私有包场景

Satis 是静态索引生成器，不是实时镜像服务。它适合内网隔离、发布固定版本包、或只同步几个内部组件的团队。

典型问题包括：

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

运行 php bin/satis build satis.json web/ 才生成一次索引，改了某个包的 composer.json 不会自动更新
默认只下载 dist ZIP，不保留 source（即 Git 地址），除非你在 satis.json 里显式加 "archive": {"skip-dev": false}
不支持 dev-main、^2.0 这类动态版本约束，Composer 会报 Could not find package
没有 HTTP 接口代理能力，无法处理 Packagist 协议里的 provider 请求流（如 provider-laravel~10.0.json）

要全量同步 packagist.org，必须用代理型镜像服务

如果你需要支持任意 Composer 包、语义化版本、实时 composer require、CI 自动拉新包，Satis 就不够用了。得上代理型服务：

packagist-mirror（阿里云开源）：Go 实现，依赖 OSS 存 ZIP、Redis 管队列，需自己配基础设施；支持秒级同步、Webhook 回调、简易管理页
Artifactory / Nexus Repository：开箱即用的 UI，填 upstream 为 https://packagist.org 即可自动缓存；免费版功能受限（如 Nexus OSS 不支持 Composer proxy）
Private Packagist（商业）：权限控制、审计日志、私有包托管、Webhook 全都有，但按 seat 收费

注意：repositories + type: "path" 或 type: "package" 都不在此列——它们连 HTTP 服务都不是，纯本地开发辅助，不能被其他机器访问。

验证本地镜像是否真正可用，别只看 config 输出

执行 composer config -g repo.packagist 返回 URL 并不等于镜像就通了。必须实测 HTTP 响应：

手动 curl -I https://your-mirror.internal/packages.json，确认返回 200 且 Content-Type: application/json
查一个已知存在但尚未被镜像拉取过的包，比如 curl -I https://your-mirror.internal/p2/laravel/framework/10.40.0.json；若返回 404，说明该 provider 文件还没触发同步，不是配置问题，是镜像服务没完成首次拉取
检查镜像服务日志，确认有没有 Redis 连接失败、OSS 权限拒绝、GitHub Token 过期等静默错误
删掉项目里的 vendor/ 和 composer.lock，再跑 composer install -vvv，观察每一步请求是否都发向你的镜像域名，而非 packagist.org

最常被忽略的一点：镜像服务运行用户（如 www-data）和执行 composer install 的用户（如 CI 的 runner）不一致时，composer config -g 写入的配置根本不会被读到——得在对应用户上下文里重新配置，或改用项目级 repositories 字段。