不需要自建镜像服务，绝大多数场景用repositories混合源即可闭环；仅当需安全审计、离线部署或统一鉴权时才应搭建私有镜像，因Packagist全量镜像无法解决私有包查找问题。
不需要自建镜像服务来管理企业内部公共类库，绝大多数场景下用 repositories 配置混合源就能闭环；只有当安全审计、离线部署或统一鉴权成为硬性要求时，才值得投入资源搭私有镜像。
为什么直接同步 Packagist 全量元数据是错的起点
企业内部类库（如 acme/utils、acme/logger）根本不在 packagist.org 上，单纯镜像它只会让 composer install 报 Could not find package acme/utils —— 因为 Composer 根本不会去你镜像的域名下找这个包。
常见错误现象包括：
- 配置了
https://mirror.internal.company.com，但拉私有包时仍走外网 - CI 构建失败，日志显示
Invalid signature（因未分发 signing-key） - 开发者
composer update后没拿到最新版，因为镜像没重建元数据
真正需要的不是“把 Packagist 搬进内网”，而是“让 Composer 知道去哪里找我的包”。这靠 repositories 就能解决，无需代理、无需同步、不改命令。
用 repositories 混合源替代镜像的实操写法
在项目 composer.json 里声明多个源，Composer 会按顺序查找：先找阿里云镜像拉开源包，再查内网 Satis 或 Nexus 下载私有包。
示例配置：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
{
"repositories": [
{
"type": "composer",
"url": "https://mirrors.aliyun.com/composer/"
},
{
"type": "composer",
"url": "https://packages.acme.com/"
}
],
"require": {
"monolog/monolog": "^2.10",
"acme/utils": "^3.2"
}
}
关键点：
-
url必须以/结尾，否则拼出//packages.json导致 404 - 私有源类型必须是
composer，不能写成vcs或漏掉type - 如果私有源是 Satis 生成的静态站，确保 Nginx 支持
.jsonMIME 类型（application/json） - 不要在
repositories里混用package和composer类型——前者需手动写每个包的 dist 信息，后者自动索引全量
Satis 构建私有镜像时最常踩的三个坑
Satis 是轻量可控的选择，但它不是开箱即用的服务，而是一个静态生成器。构建失败、漏包、--prefer-dist 仍走 Git，基本都卡在这几处。
最小可行 satis.json 必须包含：
{
"name": "acme/internal-packages",
"homepage": "https://packages.acme.com",
"repositories": [
{"type": "vcs", "url": "https://gitlab.acme.com/php/utils"},
{"type": "vcs", "url": "https://gitlab.acme.com/php/logger"}
],
"require-all": true,
"archive": {
"directory": "dist",
"format": "zip",
"skip-dev": true
}
}
关键配置说明：
-
require-all: true表示拉取所有匹配仓库的稳定版，不加它默认只处理dev-master -
archive.format必须设为zip或tar，否则composer install --prefer-dist无法下载预编译包 - 运行
php bin/satis build satis.json web/后，Nginx 的root必须指向web/，且确保packages.json可通过https://packages.acme.com/packages.json访问 - Git 仓库的
composer.json中name字段必须和你在项目中require的完全一致（包括大小写和斜杠方向）
生产环境上线前必须验证的三件事
本地跑通不等于 CI 或 Docker 构建能过。以下检查项漏掉任一，上线就可能失败：
- 确认 CI 容器里执行
composer config -g repo.packagist输出为空 —— 因为项目级repositories会覆盖全局配置，所以必须确保项目composer.json已提交且无语法错误 - 在 Dockerfile 中，
composer install前要加composer clear-cache，否则旧缓存可能 fallback 到 packagist.org - 私有包若含
ext-*扩展依赖（如ext-redis），镜像和repositories都不生效 —— 这类包由 PHP 编译安装，得在基础镜像里提前装好
最易被忽略的是：Satis 生成的 packages.json 不带签名，而某些企业安全策略强制要求 verify-signature。此时要么关掉校验（composer config -g secure-http false），要么用 Private Packagist 或自签证书配 Nginx，别指望 Satis 自己搞定。
