Composer如何发布私有Packagist_搭建Satis私有仓库教程【专业】

不能直接用 composer install 私有 git 仓库，因需本地配置认证、不支持版本稳定解析与团队复用，必须通过 Satis 等私有 Packagist 实现可发现性与可分发性。

为什么不能直接用 Composer install 私有 Git 仓库？

Composer 默认支持通过 git 协议或 httpS 克隆私有仓库，但前提是：你本地已配置好 ssh 密钥或 Git 凭据，且 composer.json 中的 repositories 类型设为 vcs。问题在于——这无法被团队其他成员复用，也不支持版本约束（如 "dev-main" 或 "1.2.0"）的稳定解析，更不提供包搜索、依赖图谱、Web 界面等能力。

真正需要私有 Packagist，本质是解决「可发现性」和「可分发性」：让任意能访问仓库服务的机器，仅靠 composer require vendor/package 就能拉取、缓存、校验、安装。

常见踩坑点：

• 误以为加个 "type": "vcs" 到 repositories 就等于有了私有仓库——这只是临时绕过方案，不是发布流程
• 把 Satis 配置成全量扫描 Git 服务器（如 gitee/gitlab），结果每次 build 都超时或漏包——Satis 不自动发现仓库，必须显式列出 packages
• 忽略 require 和 require-dev 的作用域差异，导致 Satis 构建时把测试工具也打进 dist 包，体积暴涨

如何用 Satis 搭建最小可用私有仓库？

Satis 是最轻量、最可控的私有 Packagist 替代方案，它不运行服务，只生成静态 packages.json 和 dist 归档，适合内网或 CI/CD 场景。

实操要点：

• 新建 satis.json，核心字段必须包含：name（仓库名）、homepage（输出目录 URL 前缀）、repositories（明确列出每个私有包的 Git 地址）、require-all 或 require（指定哪些包要纳入索引）
• 确保所有私有仓库的 composer.json 中有合法 version 字段（或打 Git tag），否则 Satis 无法识别可用版本
• 执行 php bin/satis build satis.json web/，生成的 web/packages.json 就是 Composer 能读取的源数据
• 把 web/ 目录用 nginx/apache 托管，确保能通过 HTTP 访问到 https://pkgs.your.org/packages.json

示例 satis.json 片段：

{   "name": "Your Private Repository",   "homepage": "https://pkgs.your.org",   "repositories": [     { "type": "vcs", "url": "https://git.your.org/internal/logger.git" },     { "type": "vcs", "url": "https://git.your.org/internal/http-client.git" }   ],   "require-all": true,   "archive": {     "Directory": "dist",     "format": "tar",     "skip-dev": true   } }

如何让 Composer 客户端信任你的私有仓库？

关键不在「加源」，而在「加源 + 关闭安全校验 + 处理认证」三步闭环。缺一不可。

常见错误现象：Could not fetch https://pkgs.your.org/packages.json, please review your configured sources，往往是因为以下任一环节失败：

• composer config -g repositories.your-name composer https://pkgs.your.org —— 必须用 composer 类型，不是 vcs
• 内网仓库无 HTTPS 或证书自签：需在全局 config 中设 "secure-http": false（仅限可信内网）
• 仓库启用了 Basic Auth：需提前运行 composer config -g http-basic.pkgs.your.org username password，否则请求直接 401
• Git 仓库本身需要 Token 认证：Satis 构建时要用 auth.json 配置凭据，否则 clone 失败，packages.json 缺失该包

验证是否生效：运行 composer show -p | grep your-vendor，应能列出私有包；再试 composer require your-vendor/logger，看是否走 pkgs.your.org 下载 dist 包而非直连 Git。

Satis 构建慢 / 包缺失 / 版本不更新？排查这三点

Satis 不是守护进程，构建即快照。所有问题都源于「输入配置」与「Git 状态」不一致。

• 构建慢：默认会 clone 每个仓库并 checkout 所有 tag/branch。用 "only": ["1.2.0", "dev-main"] 限定版本范围，或启用 "no-api": true 跳过 github/GitLab API 查询（适用于自建 Git）
• 包缺失：检查 Satis 日志中是否有 Skipping package ... because no version could be determined。90% 是因为 Git 仓库没打 tag，或 composer.json 缺 version，或分支名不符合 dev- 前缀规范
• 版本不更新：Satis 不监听 Git 变更。必须重新运行 build，且建议配合 Git hook 或 CI 在 push tag 后自动触发——否则新 tag 永远不会进 packages.json

真正容易被忽略的是：Satis 生成的 packages.json 里每个包的 dist.url 默认指向 GitHub/GitLab 的 zipball，而不是你自己的 dist/ 目录。务必确认 archive.directory 和 homepage 路径拼接后，能真实返回 tar 文件（例如 https://pkgs.your.org/dist/your-vendor/logger/1.2.0.zip）。