Composer镜像源同步脚本编写指南-composer-PHP中文网

不能手写composer镜像同步脚本，因packagist自2021年起强制要求官方增量协议、签名验证及provider分片机制，手写脚本无法满足限流规避、完整性校验、增量拉取和composer.lock兼容性等核心需求。

composer镜像源同步脚本编写指南

Composer 镜像源同步不是靠写脚本“自己搭”，而是用官方支持的 packagist-mirror 工具或成熟镜像方案（如 Toran Proxy 的开源替代），手动写同步脚本极易出错、不兼容新版 Packagist 协议，且无法处理 webhook 回调、增量更新、签名验证等关键逻辑。

为什么不能手写 Composer 镜像同步脚本

Packagist 自 2021 年起强制要求所有镜像使用其官方同步协议（基于 packages.json 增量快照 + provider-includes 分片机制），并依赖 X-Provider-Checksum 和 Content-Signature 进行完整性校验。手写脚本通常：

直接 curl https://packagist.org/packages.json 下载全量文件 → 触发限流，且无法校验签名，同步结果不可信
忽略 provider-includes 中的分片 URL（如 providers/2023-04-xx.json）→ 漏包、元数据缺失
未处理 packages.json 中的 next 字段 → 无法实现真正的增量拉取
跳过 composer.lock 兼容性检查 → 导致用户 composer install 时解析失败

推荐方案：用 packagist-mirror 官方镜像工具

packagist-mirror 是 Packagist 团队维护的镜像服务基础组件，支持完整协议、自动增量、签名验证和 HTTP 缓存头透传。部署只需：

安装 Node.js 16+ 和 Redis（用于锁与缓存）
克隆仓库：git clone https://github.com/composer/packagist-mirror
配置 .env 文件，关键项包括：MIRROR_BASE_URL=https://your-mirror.example.com、UPSTREAM=https://packagist.org、REDIS_URL=redis://127.0.0.1:6379
启动服务：npm ci && npm start，默认监听 http://localhost:3000

它会自动轮询 https://packagist.org/packages.json?lastModified=xxx，只拉取变更部分，并将 provider 文件按分片存储到磁盘或 S3。

Discussion Composer

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

下载

若必须定制同步逻辑，只改钩子，不碰核心流程

packagist-mirror 提供 onPackageUpdate 和 onProviderUpdate 两个事件钩子，适合加日志、触发 CDN 刷新、或写入自定义元数据索引。例如：

module.exports = {
  onPackageUpdate: async (pkgName, pkgData) => {
    // 只在此处加轻量逻辑，不要阻塞主流程
    console.log(`Updated: ${pkgName}`);
    await fetch(`https://cdn.example.com/purge/${encodeURIComponent(pkgName)}`);
  }
};

切勿在钩子里执行 execSync('composer update') 或重写 packages.json —— 这会破坏签名一致性，导致下游 composer install --prefer-dist 失败。

同步后必须验证的三个点

镜像上线前，用真实项目验证以下三项，缺一不可：

执行 composer show monolog/monolog 能正确返回最新版信息，且 source 地址指向你的镜像域名
运行 composer create-project laravel/laravel test-app 成功，且 vendor/ 下所有包均来自镜像（检查 composer.lock 中 dist.url 域名）
修改 composer.json 添加一个新包后执行 composer update，能正常触发增量同步（查看服务日志中是否出现 fetching provider-includes/xxx.json）