satis不能搭建镜像服务，仅生成静态文件；必须用web服务器托管output-dir并正确配置nginx/apache路径、mime类型，客户端需在composer.json顶层声明type为composer的私有源、url以/结尾且禁用packagist.org。
不能用 Satis 搭建“镜像服务”——它不代理请求、不缓存流量、不实时同步，只生成静态文件。你要的不是镜像，而是私有包仓库；Satis 能做的，是把 Git 仓库打包成 ZIP、生成 packages.json，再由 Web 服务器托管供 Composer 拉取。
为什么 satis build 成功后 composer install 还是报 404
根本原因是 Web 服务器没把 packages.json 暴露在正确路径下。Satis 不起服务，只写文件；你得手动让 Nginx/Apache 把 output-dir 当作根目录，并确保访问 https://pkg.example.com/packages.json 返回 HTTP 200 + Content-Type: application/json。
-
output-dir写的是/var/www/satis，但 Nginx 的root指向了/var/www/html→ 请求直接 404 - Nginx 默认找
index.html，而 Satis 不生成这个文件 → 访问https://pkg.example.com/返回 403 或欢迎页 -
satis.json中homepage是https://pkg.example.com，但实际部署在子路径如https://example.com/satis→ 所有dist.url都拼错，ZIP 下载全失败 - 没配 Nginx 的
types { application/json json; }→ 浏览器或 Composer 收到text/plain，拒绝解析
composer.json 里加了 repositories 为什么还是找不到包
配置位置和语义必须严格匹配 Composer 解析规则。错一个字段，整个源就被忽略，且无提示。
-
repositories必须是项目根级composer.json的顶层字段，不能嵌在require、config或其他对象里 -
url值必须以/结尾："https://pkg.example.com/"✅，"https://pkg.example.com"❌（Composer 会拼成//packages.json） - 必须显式禁用官方源：
"packagist.org": false，否则同名包优先从 packagist.org 拉，你的私有版本被覆盖 - 私有源要放在
repositories数组第一位，Composer 按顺序查找，不会合并同名包
satis.json 哪些字段写错会导致静默丢包
Satis 构建过程不报错，但包没进索引，下游永远看不到——这是最隐蔽的坑。
-
repositories写成子字段（比如塞进config里）或只写 URL 字符串 → 整个源被跳过，不报错 -
require-all: true和require同时存在 → 冲突，构建可能成功但索引为空 - 目标 Git 仓库根目录下没有合法
composer.json，或name字段含大写字母/下划线（如MyPackage或my_package）→ Satis 直接跳过该仓库，不提示 - Git tag 不符合语义化格式（如
1.2或dev-main）→require-all: true默认不收录，除非加"minimum-stability": "dev"
构建后 ZIP 包下载失败的常见原因
即使 packages.json 可访问，ZIP 下载仍可能卡住或 404，问题出在路径映射和权限上。
-
archive.prefix-url没配，或配了但不可公开访问 →dist/下的 ZIP 地址是相对路径，Composer 拼出错误 URL - Web 服务器未开放
dist/目录的读取权限 → 返回 403，但 Composer 日志只显示 “failed to download” - 用了 HTTPS 私仓但
satis build运行用户没配 Git 凭据 → 构建时跳过该包，静默丢包，packages.json里根本没这条记录 - ZIP 文件名含特殊字符（如空格、中文），Nginx 默认拒绝服务 → 检查
log_format和error_log，确认是否返回 400
真正麻烦的不是配置项多，而是每个环节都依赖前序步骤精确到位：Git 仓库合规、Satis 构建无静默失败、Web 服务路径对齐、客户端声明无语法错位——漏掉任意一环，composer install 就卡在 loading 状态，日志里却找不到明确报错。
