Satis不是开箱即用服务，而是静态文件生成器；必须手动build、配Web服务器托管packages.json、在项目composer.json中显式声明type为composer且URL以/结尾、禁用packagist.org，否则composer install必报错。
不是难，是多数人把 Satis 当成“开箱即用的服务”在用——它只生成静态文件，不跑 HTTP 服务，不自动同步，不代理请求。你配错 repositories 位置、漏掉 "packagist.org": false、Web 服务器没托管好 packages.json，composer install 就必然报 Could not fetch packages.json 或 could not find package。
为什么 satis build 后 composer install 还是找不到包？
绝大多数情况不是网络不通，而是 Composer 根本没连上你生成的 packages.json，或者连上了但内容无效。
-
satis.json中的output-dir是/var/www/satis，但 Nginx 的root指向的是/var/www/html，导致https://satis.example.com/packages.json返回 404 - Web 服务器没把
packages.json设为默认索引，你访问https://satis.example.com/时它去找index.html，而 Satis 默认不生成这个文件 -
satis.json里homepage写的是https://satis.example.com，但实际部署在子路径（如https://example.com/satis），所有dist.url和元数据都会拼错 - HTTP 服务返回了 HTML 页面（比如 Nginx 默认欢迎页），说明请求根本没落到
packages.json上
客户端 composer.json 怎么写才真正生效？
必须写在你要装私有包的那个项目的根级 composer.json 里，不能写在 Satis 自己的配置中，也不能放在 require 下面。
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
-
repositories必须是顶层字段，且类型明确写成"type": "composer" - URL 必须和
satis.json中的homepage完全一致，包括末尾斜杠："https://packages.internal/"≠"https://packages.internal" - 务必加
"packagist.org": false，否则同名包会从官方源拉取，覆盖你的私有版本 - 私有源要放在
repositories数组第一位，Composer 按顺序查找，不会合并同名包
satis.json 哪些字段写错会导致静默丢包？
Satis 构建过程不报错，但包没进索引，下游就永远看不到——这是最隐蔽的坑。
-
repositories里写了 HTTPS 私有 Git 地址，但没配git config --global credential.helper store，或没用 token，构建时 clone 失败，Satis 直接跳过，不提示 - 用了
"type": "vcs"，但 URL 写成字符串（如"url": "https://git.internal/pkg"）而没包在require或require-all里声明，Satis 静默忽略 -
require-all: true时，目标仓库没打任何符合语义化版本规范的 tag（如v1.2.0或1.2.0），dev-main不算，该包直接消失 -
require写成"acme/*": "*"—— Satis 不支持 glob，只会跳过整条规则
dist ZIP 总 fallback 到 git clone？检查这三处
Composer 默认走 --prefer-dist，但前提是 ZIP 可用、可访问、MIME 正确。
-
satis.json必须启用archive配置："archive": { "format": "zip", "skip-dev": true, "directory": "dist" } - Nginx/Apache 必须允许公开访问
dist/路径，且返回Content-Type: application/zip；用curl -I https://satis.example.com/dist/vendor-package/1.0.0-hash.zip验证 - 检查生成的
packages.json里每个包的dist.url字段是否拼对了——常见错误是少了个/，比如"https://satis.example.comdist/..."
真正容易被忽略的是：Satis 不支持增量更新，新 tag 必须手动或通过 CI 触发 satis build；还有，packages.json 文件一旦变大（比如超 5MB），Composer 加载时可能内存爆满或解析超时，得考虑按业务线拆分仓库。
