Satis 是静态构建工具而非私有 Packagist，需手动运行 build 命令生成全量静态索引，不支持自动监听、实时更新或增量构建；其性能受限于单进程全量操作，适合小团队低频发布。
为什么 satis 不是“私有 Packagist”，而是一个静态构建工具
很多人以为搭个 satis 就能像 Packagist 那样自动抓取、实时索引所有内网包，结果跑起来发现：新提交的 composer.json 改了，require 里加了新包，composer install 却报错说找不到——根本没生效。
因为 satis 不监听 Git 仓库变化，也不提供 HTTP API 接收推送；它只在你手动运行 php bin/satis build 时，按配置里的 repositories 列表去拉取指定分支的 composer.json，生成一堆静态 JSON 和 ZIP 包，扔进 Web 目录完事。
- 每次更新包或改版本号，必须重新
build，否则客户端永远看不到 -
satis.json里写的是「哪些 Git 地址 + 哪些分支」，不是「监听哪些仓库」 - 生成的
packages.json是全量重写，不增量更新，大项目构建慢，别指望它扛 CI 频繁触发
内网 Git 仓库地址怎么写才让 composer 拉得到
常见错误是直接把公司 GitLab 页面 URL（比如 https://gitlab.example.com/group/project）塞进 satis.json 的 repositories，结果 satis build 报 Could not fetch 或 401。
原因：Satis 默认用 Composer 的 VCS 驱动拉代码，它要的是可被 git clone 的地址，不是浏览器页面地址；而且得确保运行 satis build 的机器能免密访问该 Git 服务。
- GitLab/Bitbucket 用 SSH 地址最稳：
git@gitlab.example.com:group/project.git，提前配好 SSH key - HTTP(S) 地址必须带
.git后缀，且开启 Git over HTTP（比如 GitLab 的gitlab.example.com/group/project.git） - 如果用 HTTP Basic Auth，不能把密码硬编码在 URL 里（
https://user:pass@gitlab...），会被 Satis 忽略；得靠auth.json或环境变量COMPOSER_AUTH - 私有包的
composer.json里name必须唯一（如internal/utils），且和 Satis 配置里的name一致，否则不会被收录
composer install 找不到私有包？检查这三处 config
本地 composer.json 写了 "internal/utils": "^1.2"，也配了仓库，但执行 composer install 还是提示 Could not find package internal/utils。
问题往往不在 Satis 侧，而在客户端 Composer 的配置漏项。Satis 生成的只是个静态源，能否访问、是否信任、怎么认证，全靠本地 composer.json 或全局 auth.json 控制。
-
repositories必须显式声明类型为composer，URL 指向 Satis 生成的packages.json路径（如"https://satis.internal/packages.json"），不是 Git 地址 - 若 Satis 站点用了自签名 HTTPS 证书，需在
composer config中关掉验证：composer config -g secure-http false，否则直接拒绝连接 - 如果 Satis 本身做了 HTTP Basic Auth（比如 Nginx 层加了
auth_basic），必须在项目根目录放auth.json，内容为：{"http-basic":{"satis.internal":{"username":"u","password":"p"}}
小团队够用但别硬扛高并发：Satis 的性能和扩展边界
一个 50 人团队，20 个私有包，每天手动 build 1–2 次，Satis 完全没问题。但一旦想让它支撑 CI 每次 PR 都自动 publish + build，就会卡住。
根本瓶颈在「单进程、全量构建、无缓存」：每次 build 都会重 clone 所有仓库、重解析所有 composer.json、重打包所有 dist，哪怕只有一个包改了一行。
- 100+ 包时，一次 build 可能超过 2 分钟，期间
packages.json处于中间态，其他composer install可能读到损坏文件 - 没有内置锁机制，多台机器并发
build到同一输出目录，大概率产出不一致的索引 - 不支持按包粒度触发更新，也没 Webhook 回调，CI 集成得自己套 shell 脚本轮询或监听文件变化
- 真要高频发布，不如切到
toran-proxy（已停更）或Private Packagist，或者用 GitHub Packages + Composer 2.2+ 的artifact仓库模式
最常被忽略的一点：Satis 生成的 ZIP 包默认用 dist 方式下载，但它不会自动压缩 —— 如果你的私有包含大量测试文件或文档，composer install 会拉下整个仓库，而不是仅 source。得在每个包的 composer.json 里明确写 "archive": {"exclude": ["/tests", "/docs"]}。
