php bin/satis build 未生成 packages.json 的根本原因是构建环境问题而非命令错误：git 权限不足、version 字段非法（如 "dev-main"）、output-dir 路径不规范或 web 服务器配置未对齐导致文件不可访问。
php bin/satis build 为什么没生成 packages.json
不是命令错了，是构建环境卡在 Git 拉取或版本解析上。Satis 不报错跳过，而是静默忽略问题包，最终 packages.json 为空。
常见原因包括：
- 运行
php bin/satis build的用户无法免密 clone 仓库：SSH 方式要确认ssh -T git@gitlab.internal能通；HTTPS 方式得提前执行git config --global credential.helper store并输一次密码 - 目标仓库根目录下没有合法的
composer.json，或其中version字段写了"dev-main"这类非法值（Satis 解析失败就跳过） -
satis.json中output-dir是相对路径（如"web"），但当前工作目录不固定，导致文件写到意料之外的位置；建议统一用绝对路径，例如"/var/www/satis/web"，并确保 Web 用户有读权限
packages.json 返回 404 或 “Could not fetch”
这不是 Satis 没跑，是 Composer 根本没访问到你生成的 JSON 文件。根本原因是 Web 服务器配置和 Satis 输出路径没对齐。
检查这三点：
- Nginx/Apache 的
root必须精确指向satis.json中output-dir的值（比如"/var/www/satis/web"），否则https://satis.example.com/packages.json就是 404 - Web 服务器没把
packages.json当作索引文件：Nginx 需加index packages.json;，Apache 要启用DirectoryIndex packages.json -
satis.json里homepage写的是"https://satis.example.com"，但实际部署在子路径（如https://example.com/satis），所有 dist URL 和元数据都会错乱——homepage必须和最终可访问的根 URL 完全一致
客户端 composer.json 怎么写 repositories 才生效
必须写在你要装私有包的那个项目的顶层 composer.json 里，不是 Satis 自己的配置文件，也不是私有包自身的 composer.json。
Discussion Composer
下载
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
关键格式要求：
-
type必须是"composer"，不能是"vcs"或漏掉；URL 指向托管packages.json的根地址，且必须以/结尾（"https://satis.example.com/"✅，"https://satis.example.com"❌） - 务必在
repositories数组最前面加上{"packagist.org": false}，否则同名包会从官方源拉取，覆盖你的私有版本 - 多个源时顺序决定优先级：Composer 从上到下查找，第一个匹配就停止；私有源要放第一位
- 别把
require写进repositories里——那是顶层字段，放错位置整个配置会被忽略
dist ZIP 下载失败或回退到 source
不是网络问题，是 ZIP 文件没生成、路径拼错，或 MIME 类型不对。
排查重点：
- 确认
satis.json中启用了archive配置，并设置了prefix-url（如"https://satis.example.com/dist"），且该路径能被公开 GET 访问 - Nginx 需显式声明 JSON 和 ZIP 的 MIME 类型：
types { application/json json; application/zip zip; }，否则返回 HTML 或空响应 - 检查 ZIP 文件是否真实存在于
output-dir对应的dist/子目录下；Satis 默认不生成 ZIP，必须配置"archive": {...}并设"format": "zip" - 如果用了自签名证书或 HTTP 内网地址，项目级或全局需执行
composer config secure-http false，否则 Composer 8+ 直接拒绝连接
真正容易被忽略的是：Satis 构建后不会自动刷新。所有新 tag 都需重新运行 php bin/satis build，否则下游永远看不到新版——你得把它接入 CI，在 push tag 后触发构建。
