Satis不是开箱即用的私有源服务，而是静态站点生成器，需手动执行bin/satis build生成packages.json，并通过Web服务器暴露该文件路径供Composer客户端访问。
为什么 satis 不是“装上就能用”的私有源工具
它本质是个静态站点生成器，不是运行时服务。你跑一次 bin/satis build，它就扫一遍 composer.json 里写的包，拉代码、打标签、生成一堆 packages.json 和压缩包链接——然后就结束了。没有后台进程，不监听端口，也不自动更新。
常见错误现象：composer require 报错 Could not find package xxx at any version，但你确认包已提交、tag 已打、satis.json 也写了；问题往往出在没重新 build，或者 web 服务器没正确暴露生成的 packages.json 路径。
- 必须手动触发
bin/satis build satis.json web/才会刷新元数据 - 生成的
web/packages.json必须能被curl -I http://your-internal-mirror/web/packages.json访问到（HTTP 200） -
satis.json中的repositories列表只影响本次 build 的扫描范围，不决定客户端怎么连你这个源
如何让内网项目真正从你的 Satis 源安装包
关键不在 Satis 怎么建，而在 Composer 客户端怎么配。Satis 生成的是一个标准 Packagist 兼容的静态源，所以客户端只需把 repositories 指向那个 packages.json 地址即可。
使用场景：公司内网 GitLab 私有仓库 + 本地 Nginx 挂载 Satis 输出目录。
- 确保 Satis 输出目录（如
/var/www/satis/web）被 Nginx/Apache 映射为http://satis.internal/ - 项目根目录的
composer.json加上：{ "repositories": [ { "type": "composer", "url": "http://satis.internal/" } ], "require": { "company/internal-sdk": "^1.2" } } - 不要加
"packagist.org": false除非你真想完全禁用公网源——否则私有包找不到时 Composer 还会 fallback 到 packagist.org
satis.json 里最常写错的三个配置项
它们直接决定哪些包能进你的私有源、以什么形式存在、是否可被依赖解析。
-
"name"：只是生成页面的标题，不影响功能；但若和repositories.url混淆，容易误以为这是源地址 -
"output-dir"：必须是绝对路径或相对于satis.json的相对路径；写成"./web"在某些 CI 环境下会因工作目录不同而写错位置 -
"repositories"列表中每个 repo 的"type"值只能是"vcs"、"package"或"composer"；写成"git"或"github"会导致 build 静默跳过该仓库
参数差异示例：VCS 类型必须带完整 Git URL（"https://git.internal/company/sdk.git"），不能只写路径；而 "package" 类型则需手动声明 "version" 和 "dist"，适合打包二进制或 ZIP 归档。
build 太慢？几个实际有效的提速手段
Satis 默认会对每个 VCS 包执行 git clone --mirror，尤其当私有 Git 服务器响应慢或网络不稳定时，卡住是常态。
- 用
--skip-errors参数避免单个失败包中断整个 build（bin/satis build --skip-errors satis.json web/） - 加
"archive": {"directory": "dist", "format": "zip", "skip-dev": true}可减少每次 install 时的解包开销，但首次 build 会更久 - 对稳定 tag 包，建议在
satis.json中显式指定"only-stable": true，跳过 dev 分支扫描 - 如果所有包都托管在同一个 GitLab 实例，启用
"gitlab-domains"并填入域名，能让 Satis 复用 HTTP Basic Auth 凭据，避免反复弹认证
性能影响明显：未设 only-stable 时，一个含 20 个包的源可能耗时 6+ 分钟；加上后通常压到 90 秒内。但要注意——dev 分支变更不会自动进源，必须手动 trigger build。
最容易被忽略的是权限与缓存：Satis 进程需要对 Git 仓库有读权限，且默认不复用系统级 git 缓存；如果多个项目共用同一台构建机，建议在 ~/.gitconfig 中开启 core.precomposeUnicode 和 http.postBuffer，否则大仓库容易中途断连。
