Satis私有仓库需用create-project隔离安装，satis.json须满足name/homepage存在且homepage可访问、repositories类型为vcs、包名大小写严格匹配、Git仓库含SemVer tag四条件，Nginx需配置application/json MIME类型，全局config锁定源优先级。
Satis 是目前最轻量、最可控的 Composer 私有仓库方案——它不依赖 PHP-FPM、数据库或后台服务，只生成静态文件，扔到 Nginx/Apache/GitHub Pages 就能用。但直接 composer global require composer/satis 容易因全局依赖冲突导致 satis build 失败，这是绝大多数人卡住的第一步。
别全局安装 Satis，用 create-project 初始化项目
全局安装看似方便，但 satis 本身对 composer 版本和插件敏感，尤其在 PHP 8.2+ 或启用了 allow-plugins 限制的环境中，极易报错：Class "Composer\Package\Version\VersionParser" not found。
- 正确做法：在私有仓库管理目录下运行
composer create-project composer/satis --stability=stable --no-interaction - 这会拉取一个隔离的、带完整依赖的 Satis 副本，路径类似
./satis/bin/satis - 后续所有构建都走这个本地二进制，彻底避开全局环境干扰
satis.json 必须满足四个硬性条件，否则包根本不会被收录
常见现象是执行 php bin/satis build satis.json web/ 后，packages.json 里空空如也，或者提示 could not find package。这不是网络问题，而是配置没过校验关。
-
"name"和"homepage"必须存在，且homepage必须是可被 HTTP 访问的域名（哪怕只是http://localhost，用于本地调试） - 每个
repositories条目必须用"type": "vcs"，不是"git"或"package"；写成"git"会导致分支别名（如dev-main）无法识别 - 目标 Git 仓库的
composer.json中"name"必须严格匹配（大小写敏感），例如"acme/utils"不能写成"ACME/utils"或"acme-utils" - Git 仓库至少得有一个符合 SemVer 的 tag（如
v1.0.0），satis默认忽略所有dev-分支，除非显式加"minimum-stability": "dev"和"prefer-stable": false
部署后 curl 不通 packages.json？Nginx MIME 类型常被忽略
把 web/ 目录配给 Nginx 后，浏览器能打开首页，但 composer install 报错：Invalid response code 404 或 Unable to load package info。用 curl -I http://pkgs.your.org/packages.json 一看，返回的是 Content-Type: text/plain —— 这是典型 MIME 配置缺失。
- Nginx 默认不识别
.json后缀，需在http或server块中显式声明：types { application/json json; } - 同时确认该 URL 能被
curl直接访问（无重定向、无认证拦截），composer不会处理跳转或表单登录 - 如果用 GitHub Pages，确保
packages.json在根路径，且仓库设为 public（Pages 不支持 private 仓库的自定义域 + HTTPS 混合）
团队不用改每个项目的 composer.json，用全局 config 锁定源优先级
让所有开发者自动走私有源，而不是靠复制粘贴 repositories 到每个项目，关键不是“加配置”，而是“压优先级”——让私有源比 packagist.org 更早被查询。
- 执行：
composer config -g repositories.packages.type composer - 再执行：
composer config -g repositories.packages.url "http://pkgs.your.org/" - 这条命令会写入
~/.config/composer/config.json（新版 Composer），并自动关闭secure-http对该源的强制要求（避免 HTTPS 未配置时失败） - 注意：如果私有源需要认证（比如 Basic Auth），还得同步配置
~/.config/composer/auth.json，仅靠config不够
composer 就只会安静地报错，不告诉你哪错了。真正花时间的从来不是搭建，而是对照日志逐条验证这四类硬约束。 
