packages.json生成失败的首要原因是satis未成功扫描私有仓库：需确认repositories中url带.git后缀、git仓库可匿名克隆或含token认证、根目录有合法composer.json、分支名符合默认规范（如main/master），且require-all与require配置合理，避免静默跳过。
packages.json 生成失败，先看 Satis 是否真在扫描你的私有仓库
Satis 不是“配完就跑”，它只按 satis.json 里 repositories 列表逐个拉取 Git 元数据。如果生成的 packages.json 为空或不包含你的包，说明 Satis 根本没成功访问那个仓库。
常见卡点：
-
url写成网页地址（如https://gitlab.example.com/group/repo），必须带.git后缀（https://gitlab.example.com/group/repo.git） - Git 仓库不可匿名克隆：Satis 默认不走 SSH agent，也不读
auth.json；若需认证，得用 HTTPS + Token 写进 URL，例如https://oauth2:glpat-xxx@gitlab.example.com/group/repo.git - 仓库里没有合法的
composer.json：Satis 会跳过整个仓库，连 warning 都不打——静默忽略是常态 - 分支名不标准：Satis 默认只识别
main、master、dev等常见默认分支；自定义分支（如release/2.0）需显式加到require或用--require参数指定
require-all 和 require 的选择直接影响 packages.json 内容范围
"require-all": true 是最省事的写法，但它会把所有能解析出 name 的 tag 和分支全塞进 packages.json，体积大、加载慢，且容易混入测试分支或废弃版本。
更可控的做法是显式声明 require：
- 只列你真正要发布的包：
"acme/utils": "*"比"require-all": true更精准 - 版本约束要合理：
"acme/utils": "dev-main"只收录main分支的快照，适合开发中包；"acme/utils": "^2.0"则只收带v2.xtag 的稳定版 - 别漏掉私有依赖链：如果你的
acme/utils依赖另一个私有包acme/core，而acme/core没出现在satis.json的repositories里，Satis 就无法解析其元数据，acme/utils也会被跳过
build 命令执行后，packages.json 仍 404？检查 web 目录结构和权限
Satis 构建完只是生成一堆静态文件，不启动 HTTP 服务。你看到 404，90% 是 Web 服务器没正确指向输出目录，或文件权限拦住了读取。
- 确认构建命令输出路径与 Web 根目录一致：比如运行
php bin/satis build satis.json web/，那 Nginx 的root必须设为该web/的父目录，且确保web/packages.json文件真实存在 - HTTP 访问路径必须以
/结尾：https://packages.example.com/✅，https://packages.example.com❌（后者会导致 Composer 请求packages.json时拼成https://packages.example.compackages.json） - Linux 下检查文件权限：
web/packages.json至少需644，目录需755；若用 Docker，注意挂载卷的 UID/GID 是否导致容器内不可读 - Nginx/Apache 要允许访问
.json文件：Apache 需确认没禁用mod_mime；Nginx 要有types { application/json json; }并确保没被location ~ \.php$规则误拦截
生成的 packages.json 里包版本对不上？重点查 stability 和 branch-alias
Composer 安装时根据稳定性（stable / RC / dev）和分支别名决定选哪个版本。Satis 生成的 packages.json 里每个包版本都带 type 和 extra.branch-alias 字段，错一个就匹配失败。
- 私有包
composer.json里没设"minimum-stability": "dev"，Satis 仍会把它标为"stability": "stable"，但实际没打任何v1.0.0tag —— 导致composer require acme/utils找不到可用版本 - 分支别名没对齐：
"extra": {"branch-alias": {"dev-main": "2.0.x-dev"}}是常见写法，但如果主项目composer.json设了"prefer-stable": true，而你又只推了dev-main，就会 fallback 失败 - 时间戳问题：Satis 默认缓存 Git 信息（
cache-dir），改了 tag 或分支后不清理缓存，packages.json里的版本列表不会更新；加--no-cache参数重跑 build 可验证
生成逻辑本身不复杂，但每层都依赖下层准确：Git 仓库可读 → 包含有效 composer.json → name 字段与 require 严格一致 → stability 策略匹配 → Web 服务可访问 → 客户端配置禁用 packagist.org。漏掉任意一环，packages.json 就只是个空壳。
