satis build生成的静态文件需三要素齐备才能被Composer识别：必须用Web服务托管output-dir、客户端composer.json显式声明私有源、且禁用packagist.org；缺一即404或fallback至公网。
直接用 satis build 生成的文件不能被 Composer 自动识别，必须配 Web 服务托管 + 客户端显式声明源 + 禁用 packagist.org，三者缺一不可。
确保 satis 命令全局可用
装完 composer global require composer/satis 不代表就能用：系统找不到 satis 命令是后续所有步骤失败的最常见起点。
- Linux/macOS 检查
~/.composer/vendor/bin是否在$PATH中，运行which satis验证 - Windows 用户需把
%USERPROFILE%\AppData\Roaming\Composer\vendor\bin加进系统环境变量 - 报
command not found时别重装，先改 PATH；否则satis build直接失败，连 Git 拉取都触发不了
satis.json 必须含三个顶层字段且结构正确
漏掉任一字段、嵌套错层、路径写相对路径，都会导致构建无声失败或 packages.json 为空。
-
repositories是顶层数组，每个元素必须是完整对象：{"type": "vcs", "url": "https://git.internal/lib"}，不能只写字符串 URL -
require-all: true或require（如"vendor/package": "*"）二者只能选其一，不能共存 -
output-dir强烈建议用绝对路径（如/var/www/satis），避免构建时因工作目录变化导致权限或路径解析异常 -
homepage必须是最终可访问的根 URL（如https://pkg.example.com/），结尾带斜杠，否则 Composer 会拼出/packages.json/packages.json
Web 服务必须正确托管 output-dir 并返回合法 JSON
satis build 只生成静态文件，不启动任何服务。没 Web 服务器，composer install 就会 404。
- Nginx/Apache 的 root 必须指向
output-dir（如root /var/www/satis;） - 访问
https://pkg.example.com/packages.json必须返回 HTTP 200 +Content-Type: application/json；Nginx 需加types { application/json json; } -
dist下 ZIP 文件路径由 Satis 自动生成（如dist/vendor-package/version-hash.zip），Web 服务器要允许该路径被公开 GET 到 - 若用 HTTP 协议（非 HTTPS），客户端必须提前执行
composer config -g secure-http false，否则拒绝连接
客户端 composer.json 必须显式声明并禁用默认源
即使私有仓库完全正常，项目里不改配置，Composer 仍默认只查 packagist.org。
- 在项目
composer.json的repositories字段中添加：{"type": "composer", "url": "https://pkg.example.com/"} - 同时必须设置：
"packagist.org": false（注意是布尔值false，不是字符串"false"） - 执行
composer clear-cache，否则旧缓存可能掩盖配置生效问题 - 如果用
composer create-project，需额外加--repository=https://pkg.example.com/参数
最容易被忽略的是 homepage 结尾斜杠和客户端 "packagist.org": false 这两个细节——它们不报错，但会让整个私有源形同虚设。Satis 本身不处理请求，它只是“编译器”，所有路由、协议、缓存逻辑都落在 Web 服务和客户端配置上。
