composer怎么搭建私有库_composer私有仓库搭建教程

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 "ComposerPackageVersionVersionParser" 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 不够

Satis 看似简单，但它的“静态性”是一把双刃剑：省去了运维成本，却把所有校验逻辑推给了配置——name 对不上、tag 缺失、MIME 错、URL 不可达，任何一个点断掉，composer 就只会安静地报错，不告诉你哪错了。真正花时间的从来不是搭建，而是对照日志逐条验证这四类硬约束。