satis 需web服务器托管静态文件、客户端显式声明私有源并禁用packagist.org才能生效；安装后须确保satis命令在path中；satis.json须含顶层数组repositories、require-all/require及绝对路径output-dir；git仓库需含合法composer.json；构建后需配置web服务正确返回packages.json；客户端须配置repositories和"packagist.org": false并清缓存。
不能直接“装完就用”，Satis 生成的是静态文件，必须配 Web 服务器托管 + 客户端显式声明源 + 禁用 packagist.org 才能生效。
安装 satis 命令行工具要确保 PATH 可达
全局安装最省事：composer global require composer/satis。但关键不是装上，而是让系统能找到 satis 命令：
- 检查
~/.composer/vendor/bin是否在$PATH中（Linux/macOS）或用户环境变量里（Windows） - 运行
which satis或satis --version验证是否可执行 - 如果报 command not found，别重装，先修正 PATH；否则后续所有构建都会卡在“找不到命令”
satis.json 必须包含 repositories、require-all/require、output-dir 三要素
缺一不可，且结构不能错位。常见失效配置就是把 repositories 写成子字段，或漏掉 output-dir：
-
repositories是顶层数组，每个元素必须是完整对象：{"type": "vcs", "url": "https://git.internal/lib"}，不能只写字符串 URL - 要用所有 tag/branch，写
"require-all": true；若只想要特定包，改用"require": {"vendor/package": "*"}，二者不能共存 -
output-dir推荐写绝对路径（如/var/www/satis），避免构建时权限或路径解析出错 - 目标 Git 仓库根目录下必须有合法
composer.json，且含正确name字段（小写字母+短横线，不能含大写或下划线）
构建后必须用 Web 服务托管 output-dir，且路径要对齐
satis build 只生成一堆文件，不启动任何服务。没 Web 服务器，composer install 就会 404：
- 把
output-dir目录设为 Web 根路径（例如 Nginx 的root /var/www/satis;） - 访问
https://pkg.example.com/packages.json必须返回 HTTP 200 +Content-Type: application/json（Nginx 要加types { application/json json; }） - URL 必须以
/结尾（如"url": "https://pkg.example.com/"），否则 Composer 会拼成.../packages.json错误路径 - dist ZIP 文件路径由 Satis 自动生成（如
dist/vendor-package/version-hash.zip），Web 服务器必须允许该路径被公开访问
客户端 composer.json 必须禁用 packagist.org 并显式声明源
即使 Satis 仓库完全正常，项目里不改配置，Composer 仍默认只查 packagist.org：
-
repositories字段必须在项目composer.json顶层，不能嵌套在其他字段里 - 必须加
"packagist.org": false，否则私有包永远被忽略 - 如果私有仓库用 HTTP（非 HTTPS），还得执行
composer config -g secure-http false（Composer 8+ 强制要求） - 改完记得清缓存：
composer clear-cache，否则旧索引可能干扰新包识别
真正容易被忽略的点：Satis 不自动感知 Git 新 tag，每次发版都得手动或通过 CI 触发 satis build。它不是服务，是快照生成器——你建的不是“镜像”，是某一时点的包快照。
