Satis是官方推荐的轻量级静态私有Packagist生成器，需手动build、Nginx托管packages.json、客户端显式声明type为composer且URL以/结尾、禁用packagist.org，否则composer install必报错。
为什么 packagist.org 官方源在国内慢得像卡住，而简单换镜像还不够？
因为 Composer 的 packagist.org 默认源是全球统一的，但它的元数据（packages.json、provider-list.json 等）体积大、更新频繁，且不支持按需拉取。单纯用 composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/ 只能加速下载，无法解决私有包托管、内部依赖闭环、审计合规等真实需求。
真正需要私有 Packagist，不是为了“更快”，而是为了：
– 托管公司内部 SDK、基础组件等 private 包（"type": "library" 或 "type": "metapackage"）
– 避免把敏感代码推到 GitHub/GitLab 公共仓库
– 统一版本策略（如强制要求 dev-main 不允许发布）
– 与内部 LDAP/OAuth 集成鉴权
如何用 Satis 搭建轻量级私有 Packagist（不选 Private Packagist 或 Toran）
Satis 是 Composer 官方推荐的静态包仓库生成器，适合中小团队——它不运行服务，只生成 JSON + ZIP 文件，可直接扔进 Nginx/Apache，零运维压力，也天然兼容中文镜像源逻辑。
- 安装：运行
composer create-project composer/satis --stability=stable，得到一个可执行的bin/satis - 配置
satis.json必须指定"repositories"为内部 Git 地址（如"https://git.internal.company/sdk-core"），不能写github.com类公共地址 - 关键字段
"archive": {"directory": "dist", "format": "zip", "skip-dev": true}决定是否生成 ZIP 包——不开这个，下游composer install会回退到git clone，无法离线部署 - 生成命令必须加
--no-interaction和--skip-errors：否则某个私有库权限失败或composer.json格式错误，整个构建就中断
示例最小 satis.json：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
{
"name": "internal/packagist",
"homepage": "https://packagist.internal.company",
"repositories": [
{"type": "vcs", "url": "https://git.internal.company/sdk-core"},
{"type": "vcs", "url": "https://git.internal.company/utils"}
],
"require-all": true,
"archive": {"directory": "dist", "format": "zip"}
}
怎么让团队所有人的 Composer 自动走你的私有源，又不破坏对公共包的访问？
不能全局替换 packagist.org，否则 monolog/monolog 这类公共包就找不到了。正确做法是用 composer config 设置 repo.packagist 为复合源（Composite Repository）。
- 先禁用默认源：
composer config -g repo.packagist false - 再添加两个独立源：
– 私有源：composer config -g repos.internal composer https://packagist.internal.company
– 镜像源（阿里云）：composer config -g repos.aliyun composer https://mirrors.aliyun.com/composer/ - 注意顺序：Composer 按配置顺序查找包，所以要把
repos.internal放在repos.aliyun前面，确保internal/sdk-core优先从私有源解析 - 验证是否生效：运行
composer config -g repos，输出中应看到两个composer类型源，且packagist.org为false
常见报错和绕过方法：Failed to download internal/sdk-core, could not authenticate against git.internal.company
这不是 Composer 错，是 Git 凭据没透传过去。Satis 构建时读取私有 Git 库，需要 SSH key 或 HTTP Basic Auth，但默认环境下没加载。
- SSH 方案：在构建机上配置
~/.ssh/config，为git.internal.company指定IdentityFile，并确保bin/satis运行用户能读取该 key - HTTP 方案：在
satis.json的repositoriesURL 中硬编码凭证（不推荐）或改用https://token:x-oauth-basic@git.internal.company/sdk-core - 最稳方案：用
git config --global url."https://token@".insteadOf "https://"，让所有 HTTPS Git 请求自动注入 token - 另一个坑：
composer install时提示Package internal/sdk-core has no installation candidates，大概率是 Satis 没生成对应版本（比如 Git 分支名不是1.0而是v1.0.0），检查packages.json里有没有该版本的dist描述
私有 Packagist 的核心不是“搭起来”，而是让每个 composer.json 里的 require 能被无感解析——这取决于 Satis 构建时能否准确提取版本号、是否生成了 ZIP、以及客户端源配置是否形成有效 fallback 链。漏掉任一环，就会回到手动 git clone 的原始状态。
