satis 是官方推荐的轻量级静态包仓库生成工具，通过 satis.json 配置 name、homepage 和 repositories 三要素即可初始化；构建失败常见于 git 权限、version 字段非法或 packages.json 为空；客户端需在 composer.json 中显式添加 type: "composer" 的私有源并禁用 packagist.org；dist 下载回退 source 多因 zip 未生成或域名/mime 配置错误；satis 不支持增量更新，建议脚本自动化维护配置。
Composer 本身不提供私有包托管能力，satis 是官方推荐的轻量级静态包仓库生成工具——它不运行服务，而是把 composer.json 编译成可被 composer install 直接拉取的静态 JSON 和 ZIP 文件，适合内网或 CI 环境。
如何初始化一个最小可用的 Satis 配置
satis 的核心是配置文件（通常叫 satis.json），它定义了哪些包要收录、怎么构建、输出到哪。最简配置只需三要素：
-
name：仓库显示名（任意字符串） -
homepage：最终生成页面的根 URL（如https://packages.internal），影响所有包的dist.url -
repositories：源仓库列表，支持vcs（Git）、package（手动定义单个包）、composer（代理其他 Composer 源）
示例：
{
"name": "Internal Packages",
"homepage": "https://packages.internal",
"repositories": [
{ "type": "vcs", "url": "https://git.internal/project-a" },
{ "type": "vcs", "url": "https://git.internal/project-b" }
],
"require-all": true
}注意：require-all 表示收录所有分支/Tag；若只想要稳定版，改用 "require": { "project-a": "*" } 并确保对应仓库 composer.json 中 version 字段规范（如 1.2.0，不能是 dev-main）。
构建时常见失败原因和修复方式
执行 php bin/satis build satis.json web/ 后报错，多数卡在 Git 拉取或版本解析环节：
-
Failed to clone https://git.internal/project-x, could not read packages from it：Satis 运行用户无 Git 权限，或未配置 SSH key（HTTPS 方式需提前git config --global credential.helper store并输一次密码） -
Could not parse version constraint dev-main: Invalid version string "dev-main"：目标仓库composer.json中version字段写了开发分支名，应删掉该字段，让 Composer 自动从 Git Tag 推断 - 生成的
packages.json里包数量为 0：检查repositories地址是否拼写正确，且对应 Git 仓库根目录下存在有效的composer.json
客户端如何安全接入私有仓库
项目中启用私有源，必须显式添加到 composer.json 的 repositories，且优先级高于 Packagist。关键点：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 必须用
type: "composer"，URL 指向satis输出目录的根（即包含packages.json的路径），不是satis.json路径 - 建议加
packagist.org的禁用开关，避免意外命中公网同名包："packagist.org": false - 若私有仓库走 HTTPS 且证书不可信（如自签），需在
config中设"secure-http": false（仅限内网环境）
示例：
"repositories": [
{ "type": "composer", "url": "https://packages.internal" },
{ "packagist.org": false }
],
"config": {
"secure-http": false
}
为什么 dist 包下载总是回退到 source
satis 默认只生成 dist 的 ZIP URL，但实际下载失败时 Composer 会自动 fallback 到 source（Git clone）。这通常是因为：
- 生成时没加
--skip-scripts或权限不足，导致 ZIP 打包失败，packages.json中dist字段为空 -
homepage配置的域名无法被客户端 DNS 解析，或 Web 服务器未正确配置 MIME 类型（application/zip） - 目标 Git 仓库未设置
archive支持（如私有 GitLab 需开启Download as archive功能）
验证方法：直接浏览器访问 https://packages.internal/dist/vendor-name-package-name-zip-hash.zip，看能否下载。不能则说明 ZIP 未生成或路径不可达。
真正麻烦的不是搭建，而是每次新增包都要改 satis.json + 重新全量构建——satis 不支持增量更新，小团队建议用脚本自动扫描 Git 仓库并生成配置，否则很快就会卡在维护上。
