Satis是静态包索引生成器而非镜像服务，其核心是通过satis.json明确声明require或require-all来纳入包索引，否则即使仓库存在也会静默跳过；构建后需确保archive配置启用、Web服务器正确提供ZIP路径与application/zip MIME类型，并在客户端composer.json中将私有源置顶且显式禁用packagist.org。

Satis 不是“镜像服务”，它只是静态生成 `packages.json` 和 ZIP 包的构建工具；想用它做企业级私有仓库，关键不在“搭服务”，而在“控配置、稳输出、防漏包”。

为什么 satis build 后 composer install 找不到包？

绝大多数情况不是网络或权限问题，而是 satis.json 里没真正把包“纳入索引”。Satis 不会自动扫描 Git 仓库所有 tag —— 它只看你明确写进 require 或 require-all 的内容。

• require-all: true：会拉取 repositories 列表中每个仓库的所有 tag + stable 分支（如 v1.0.0、1.2），但跳过 dev- 前缀分支，除非你设 "skip-dev": false
• require: { "vendor/package": "*" }：只匹配该包的合法 tag（必须是语义化版本，如 1.0.0；dev-main 不算）；若仓库没打任何 tag，这个包就直接消失
• 如果用了 type: "vcs" 却误写成字符串 URL（如 "url": "https://git.internal/pkg"），而没包在 require 里声明，Satis 构建时会静默跳过，不报错也不收录

如何让 dist ZIP 正常下载，而不是 fallback 到 git clone？

Composer 默认优先走 --prefer-dist，但前提是 Satis 生成了可用 ZIP，并且 Web 服务器能正确返回 application/zip MIME 类型和可访问路径。

Discussion Composer

围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par

下载

• 必须在 satis.json 中启用 archive 配置：

  "archive": {
    "format": "zip",
    "skip-dev": true,
    "directory": "dist"
  }

• 生成的 ZIP 路径形如 dist/vendor-package/1.0.0-hash.zip，Nginx/Apache 必须允许该路径被公开访问（无 rewrite 截断、无 403）
• 检查响应头：curl -I https://satis.internal/dist/vendor-package/1.0.0-abc123.zip 应含 Content-Type: application/zip；否则浏览器或 Composer 可能拒绝下载
• 若仍 fallback 到 source，运行 composer install -v 看具体提示 —— 常见原因是 ZIP 文件 404，或 dist.url 字段在 packages.json 里拼错了（比如少了个 /）

客户端 composer.json 怎么配才不翻车？

项目级配置比全局配置更可控，也更容易审计。重点不是“加进去”，而是“顺序+隔离+认证”。

• 把私有源放在 repositories 数组**第一位**：composer 按顺序查找，命中即停，避免先去 packagist.org 找一圈再 fallback
• 显式禁用公共源：

  "repositories": [
    { "type": "composer", "url": "https://satis.internal/" },
    { "packagist.org": false }
  ]

  否则即使私有包存在，也可能因网络抖动或缓存导致拉取失败后意外走公网
• 认证信息绝不能写进 composer.json；统一用 auth.json（权限 600）：

  {
    "http-basic": {
      "satis.internal": { "username": "read-only", "password": "xxx" }
    }
  }

• CI 环境别依赖 auth.json 文件挂载 —— 改用 COMPOSER_AUTH 环境变量注入 JSON 字符串，更灵活也更安全

为什么 packages.json 越来越大，composer update 开始超时？

Satis 默认把所有收录包的所有版本塞进一个 JSON 文件，100 个包 × 平均 15 个版本 ≈ 2MB+，PHP 解析时内存爆、超时、OOM 都很常见。

• 删掉不用的包：定期清理 satis.json 中已下线项目的 repositories 和 require 条目
• 限制版本范围："require": { "vendor/pkg": "^2.0" } 比 "*" 更收敛，减少无效版本写入
• 拆分仓库：按业务线或稳定性分级（如 internal-stable / internal-dev），各自独立 satis.json 和构建目录，避免一个大包拖垮全部
• 别信“自动更新”——Satis 没 webhook、不监听 Git 事件；必须靠定时脚本或 CI 触发 satis build，且每次构建前建议 rm -rf dist/* 清旧包

Satis 的脆弱点不在功能，而在它完全不隐藏配置细节：一个字段写错、一个 tag 漏打、一个 MIME 头缺失，都会导致下游项目悄无声息地拉错源或装不上包。上线前务必用 composer show vendor/package 和 curl -s https://satis.internal/packages.json | jq '.packages."vendor/package"' | head -n 20 交叉验证。