Satis build 报错根本原因是 repositories 未生效或 require-all 与 require 混用；它不自动抓取 vendor/ 下包，只认显式声明的公开 Git 仓库或已发布 dist 包。
为什么 satis build 总是报错找不到包
根本原因通常是 composer.json 里声明的 repositories 没生效，或者 Satis 配置中 require-all 和 require 混用导致依赖解析失败。Satis 不会自动抓取你本地 vendor/ 下的包，它只认你明确列出的 Git 仓库或已发布的 dist 包。
实操建议：
- 确保每个包在 Satis 的
packages或require字段中以"vendor/name": "dev-main"形式显式声明，别指望它自动发现子目录 - Git 仓库必须公开可读（哪怕只是内网），且含有效
composer.json；私有 Git 要配github-oauth或http-basic，否则satis build会在 clone 阶段卡住 - 如果用
require-all: true，确认所有目标仓库都已打 tag 或有稳定分支（如main、master），否则 Satis 会跳过无版本信息的仓库 - 错误示例：
Could not fetch https://git.internal/pkg, will skip→ 检查该 URL 是否能被运行satis build的机器curl -I通
生成的 packages.json 为什么 Composer 安装时还是拉不到包
Satis 只生成静态元数据，不托管实际 zip/tar 包文件。如果你没配置 archive 或没把 dist 文件放对位置，Composer 会回退到从源码 clone，而私有 Git 地址往往不可达。
实操建议：
- 在 Satis 配置里加
"archive": {"directory": "dist", "format": "zip", "prefix-url": "https://your-satis.example.com"} - 确保 Web 服务器能把
/dist/vendor-name-package-name-zip-hash.zip这类路径正确映射到文件系统，且有读权限 - 运行
satis build后检查输出日志里有没有Writing package dist...行；没有说明 archive 没触发 - 验证方式：直接浏览器访问
https://your-satis.example.com/dist/foo-bar-1.2.3.zip，应该能下载，不能就说明路径或权限错了
如何让私有包支持 dev-master 这类开发版约束
Satis 默认只发布稳定版本（有 tag 的），dev- 前缀的分支不会自动进 packages.json，除非你强制开启 require-dependencies 或手动指定分支名。
实操建议：
- 在 Satis 配置中设
"require-dependencies": true，它会让 Satis 尝试解析并包含依赖中声明的dev-分支（但不保证全部成功） - 更可靠的方式：用
"require": {"vendor/pkg": "dev-feature/x"}显式拉特定分支，并确保该分支在 Git 仓库中存在且有composer.json - 注意：Satis 不会为你创建分支别名（如
"dev-feature/x as 1.0.x-dev"），这个必须写在包自身的composer.json的extra.branch-alias里 - 常见坑：
composer require vendor/pkg:dev-main失败 → 检查 Satis 输出的packages.json里是否真有"dev-main"这个 version 字段
composer update 很慢，甚至超时
不是网络问题，而是 Satis 生成的 packages.json 缺少压缩，或者 Composer 每次都去校验整个包列表的 hash。尤其当私有包数量超过 50，未启用 gzip 会导致单次请求 >2MB。
实操建议：
- Web 服务器必须开启
gzip（Nginx 加gzip on;，Apache 开mod_deflate），否则 Composer 下载元数据极慢 - 在 Satis 配置中加
"output-dir": "web"，然后让 Web 根目录直接指向web/，避免多一层路径重写开销 - 禁用 Composer 的 repo 签名校验（仅限内网）：
composer config --global repo.packagist.org.allow_ssl_downgrade true，防止证书链不全拖慢连接 - 别用
require-all: true扫几百个仓库——精确列出需要的包，Satis 构建和 Composer 解析都会快一个数量级
最常被忽略的一点：Satis 生成的 packages.json 是纯静态文件，但它依赖 Web 服务器正确设置 Content-Type: application/json 和 Cache-Control。漏掉任一，Composer 就可能反复下载或解析失败。
