私有 packagist 服务首选 satis 而非 packagist-private，因其轻量、稳定、仅需静态文件；配置需设 type="composer"、禁用 packagist.org、正确声明 satis.json 字段，并注意 git 权限、证书、缓存及 zip 完整性。
私有 Packagist 服务必须用 satis 或 packagist-private？
不是必须，但绝大多数中小团队选 satis 更稳。它不跑 Web 服务，只生成静态 packages.json，配合 Nginx 就能当源用；而 packagist-private（或 fork 官方 Packagist）要维护 PHP-FPM、数据库、队列，上线后还要处理 CSRF、登录、包审核等逻辑——除非你真需要 Web 界面和权限分级，否则纯属加负。
常见错误现象：composer install 卡住、报 Could not parse version constraint，往往是因为用了未适配 Composer 2.x 的旧版 satis 镜像，或生成的 packages.json 缺少 mirrors 或 notify-batch 字段。
-
satis最低要求 PHP 7.4，推荐用satis:latestDocker 镜像（官方维护） - 配置文件
satis.json中必须声明name和homepage，否则 Composer 会拒绝加载该源 - 若私有包含
dev-分支，需在satis.json中显式开启"require-dependencies": true，否则依赖树不全
如何让 composer.json 正确指向私有源并优先拉取
不能只靠 repositories 数组追加，顺序和类型决定优先级。Composer 默认把 packagist.org 当作隐式 packagist 类型源，而自定义源默认是 composer 类型——它不会自动 fallback，也不会覆盖同名包的官方版本。
使用场景：公司内部有 myorg/utils，同时 packagist.org 上也有同名包，但你要确保项目只装私有的。
- 在项目根目录
composer.json中，把私有源放在repositories数组**首位**，且显式指定"type": "composer" - 必须加上
"packagist.org": false，禁用默认源，否则同名包可能被“污染” - 示例片段：
{ "repositories": [ { "type": "composer", "url": "https://packagist.myorg.com" } ], "packagist.org": false } - 执行
composer clear-cache后再install，否则 Composer 可能仍从本地缓存读取旧元数据
satis build 生成失败或包没更新？检查这三处
最常卡在 Git 拉取或版本解析环节，而不是 JSON 生成本身。Satis 不会自动 clone 私有仓库，也不处理 SSH key 权限问题。
常见错误现象：satis build satis.json web/ 输出 Skipping package myorg/utils, no suitable releases found，或直接报 Cloning into bare repository failed。
- 确认
satis.json中repositories列表里的每个 Git URL 都能被构建机无交互访问（推荐用 HTTPS + token，如https://token:x-oauth-basic@github.com/myorg/utils.git） -
"require-all": true仅表示“拉所有已知包”，不等于“自动发现新仓库”；新增包必须手动加进satis.json的repositories或启用providers扫描 - 如果包
composer.json中version字段写死（如"version": "1.0.0"），Satis 会忽略 Git tag，导致无法识别发布版本；应删掉该字段，靠 tag 自动推导
私有源响应慢或 HTTPS 证书报错怎么办
不是 Composer 配置问题，而是部署层没做对。Satis 生成的是纯静态文件，瓶颈只可能出在 Web 服务或网络路径上。
性能影响：未启用 gzip、未设置 Cache-Control: public, max-age=3600，会导致每次 composer update 都重新下载几 MB 的 packages.json。
- Nginx 配置中必须开启
gzip_static on，并提前用gzip -k packages.json生成packages.json.gz - 若用自签名证书，不要在 Composer 全局关 TLS 验证（
composer config -g secure-http false），而应在composer.json的私有源条目里加"options": {"ssl": {"verify_peer": false}} - 路径别写错：Satis 默认输出到
web/packages.json，Nginx root 应指向web/，而非整个 Satis 项目目录，否则vendor/可能被意外暴露
最易被忽略的一点：Satis 不校验包 ZIP 文件完整性，上传后若网络中断导致 ZIP 截断，Composer 解压时会静默失败，报错却是 Invalid zip file 或 Corrupted zip archive——得去私有源服务器上手动 unzip -t 检查每个包。
