satis.json 中 name 和 homepage 是硬性要求，因 Satis 将其写入 packages.json 顶层作为仓库元数据，缺失会导致下游 Composer 解析失败或静默跳过；homepage 还决定 dist 包下载根路径。
satis.json 必须手写，不能靠 composer config 生成，缺字段会导致下游 composer install 直接失败。
为什么 satis.json 里 name 和 homepage 是硬性要求
这两个字段不是可选装饰。Satis 生成的 packages.json 会把它们作为仓库元数据写入顶层，下游 Composer 在解析源时若发现缺失，会报 Could not parse version constraint 或静默跳过该源。尤其 homepage 还决定了包下载链接的根路径——比如设为 "https://pkgs.internal"，那所有 dist 包最终 URL 就是 https://pkgs.internal/dist/vendor/pkg.zip。
archive 配置不生效？检查这三处
-
directory是相对路径：它相对于你执行php bin/satis build的当前目录，不是相对于satis.json所在位置 -
format只接受"zip"或"tar"：填"tgz"或"tar.gz"会被忽略，Satis 不报错但也不生成归档 -
skip-dev: true必须显式设置：否则 Satis 会尝试归档dev-master、dev-feature/x这类分支，导致构建卡住或生成大量无效文件
只更新某几个包，而不是全量重建
全量构建在包多时很慢，且容易因某个仓库临时不可达而失败。用 --repository-url 或直接指定包名更可控：
- 按仓库更新：
php bin/satis build satis.json web/ --repository-url https://git.internal/lib-a.git - 按包名更新：
php bin/satis build satis.json web/ vendor/package-a vendor/package-b - 两者混用也行，Satis 会先过滤仓库，再从中匹配包名
离线部署的关键不是“静态”，而是 dist 归档是否真实存在
Satis 默认只生成 packages.json 和索引页，不下载任何代码。所谓“离线可用”，前提是 archive 配置已启用，且构建后 dist/ 目录下确实有对应版本的 .zip 文件。验证方式很简单：找一个包的 dist URL（比如从生成的 packages.json 里复制），用 curl -I 看返回是否为 200。如果返回 404，说明归档没成功，别急着配客户端。
