不能直接用 Composer 的 repositories 指向 Git 仓库，因其默认只拉取 tagged release、每次安装都全量克隆（慢且无缓存）、不支持私有包统一索引与权限管理；Satis 通过生成静态 packages.json 解决这些问题。
为什么不能直接用 Composer 的 repositories 指向 Git 仓库？
因为 Composer 默认只拉取 tagged release，且每次安装都走 Git 克隆（慢、不稳定、无缓存），不支持私有包的统一索引、版本聚合、Web 查看和权限收敛。Satis 就是为解决这些而生：它把多个 Git 仓库打包成一个静态 packages.json，让 Composer 当作标准 Packagist 使用。
搭建 Satis 最小可行服务的关键三步
你不需要 PHP-FPM 或数据库，Satis 本身是个命令行工具，生成纯静态文件即可托管在 Nginx/Apache/甚至 GitHub Pages 上：
- 用
composer create-project composer/satis初始化项目，不要全局安装 —— 全局版常因依赖冲突导致satis build失败 - 写
satis.json，必须包含name、homepage、repositories（每个 repo 的type建议设为vcs，而非git；否则无法识别分支别名） - 运行
php bin/satis build satis.json web/，输出到web/目录，确保该目录可被 HTTP 访问（如http://pkgs.your.org/）
私有包无法加载？检查这四个硬性条件
Satis 不是代理，它只镜像你明确声明的仓库，且对源仓库有强约束：
-
composer.json中的name必须符合vendor/name格式，且与 Satis 配置中引用的 name 完全一致（大小写敏感） - Git 仓库必须有至少一个符合 SemVer 的 tag（如
v1.0.0或1.0.0），Satis 默认忽略dev-分支，除非显式配置"minimum-stability": "dev"并加"prefer-stable": false - 如果包含私有子依赖（比如另一个内部库），那个子依赖也必须出现在 Satis 的
repositories列表里，否则构建时会跳过，下游安装时报could not find package - HTTP 服务返回的
packages.json必须能被curl -I http://pkgs.your.org/packages.json正常访问，且响应头含Content-Type: application/json，Nginx 常因缺少types { application/json json; }导致 MIME 错误
如何让团队成员无缝切换到私有仓库？
别改每个项目的 composer.json，用 Composer 全局配置锁定私有源优先级：
composer config -g repositories.packages.type composer composer config -g repositories.packages.url "http://pkgs.your.org/"
这条命令会在 ~/.composer/config.json 中写入仓库配置，并自动设置 packagist.org 的 allow-plugins 和 secure-http 行为。注意：如果私有仓库用了 HTTP（非 HTTPS），必须额外执行 composer config -g secure-http false，否则 Composer 8+ 会直接拒绝连接。
真正容易被忽略的是：Satis 构建后不会自动刷新，所有新 tag 都需重新运行 build 命令 —— 你得把它接入 CI，在 push tag 后触发构建，否则下游永远看不到新版。
