如何优雅地构建企业级私有包仓库？Composer搭配Satis搭建私服全记录

直接上手用 Satis 搭建私有 Composer 仓库，听起来简单，但不少团队都踩过坑。问题往往不是出在配置本身，而是后续的维护逻辑。最常见的痛点，莫过于“包不更新”、“权限失控”和“镜像同步失败”这三座大山。说到底，症结往往藏在 satis.json 的构建逻辑和 Web 服务的触发时机里。

为什么 satis build 总是不生效？

首先要明确一点：Satis 本身不是一个常驻服务，它只是一个静态文件生成器。这意味着，每次你修改了 satis.json，比如添加了新仓库，都必须手动执行一遍 php bin/satis build 命令。这步操作，恰恰是最容易被遗忘的环节。

另一个高频错误点，在于输出目录的配置。Build 命令生成的静态文件，必须被正确映射到 Web 服务器（如 Nginx）的可访问路径下。很多人习惯性地把输出目录设为 /var/www/html，却忘了配置关键的 MIME 类型，导致 Composer 客户端访问时直接抛出 Unable to load package list 的错误。

• 路径一致性是关键：确保 build 命令的输出目录与 Web 服务器的根目录完全一致，例如：php bin/satis build satis.json /var/www/satis。
• Nginx 需显式支持 JSON：在 server 配置块中，为 .json 文件添加正确的 Content-Type：add_header Content-Type application/json;。
• 慎用内置开发服务器：不要图省事用 php -S 来运行，它无法完全支持 Composer 所需的 HTTP 状态码和重定向行为，会在后续使用中埋下隐患。

satis.json 中 repositories 和 require-all 怎么配才不漏包？

这里的配置逻辑需要理清：repositories 列表定义的是你“希望收录”的代码源，而 require-all 则决定了“实际打包哪些”。

如果把 require-all 设为 true，Satis 会尝试解析所有仓库的 composer.json 并合并其完整的依赖树。这听起来很省事，但风险极高——只要其中任何一个私有包缺少 dist 或 source 字段，整个构建过程就会中断。更稳妥的做法，是采用显式声明。

• 弃用 require-all：避免使用 "require-all": true，转而明确列出每个需要的包及其版本约束，例如："require": { "vendor/package-a": "dev-main", "vendor/package-b": "^2.1" }。
• 完善仓库定义：每个 repository 必须包含 type（推荐 vcs）和可访问的 url。对于 GitLab 私有项目，URL 中需要嵌入访问令牌："url": "https://token:x-oauth-basic@gitlab.example.com/group/repo.git"。
• 处理未打 Tag 的分支：如果包还没有打 Git tag，Satis 默认会跳过。此时需要在 satis.json 中增加 "minimum-stability": "dev" 配置，并确保对应的分支（如 dev-main）存在且配置了正确的 branch-alias。

如何让开发者不用改 composer.json 就能用私服？

让团队无缝切换是关键。虽然可以通过全局配置 composer config -g repos.packagist.org false 来禁用官方 Packagist，但这过于激进，可能影响其他项目。更安全的做法，是添加一个全局的私有仓库源。

执行命令 composer config --global repos.my-private-repo composer https://satis.example.com 即可。这里有个魔鬼细节：URL 末尾必须加上斜杠 /。否则，Composer 在拼接 packages.json 请求地址时，会生成一个错误的链接（如 https://satis.example.compackages.json），导致请求失败。

• 验证配置：执行 composer config --global repo.my-private-repo，检查返回的 URL 是否完整无误。
• 避免工具栈重叠：如果公司已经使用了 Artifactory 或 Nexus 这类成熟的制品库管理工具，就不要再强行引入 Satis 了。它们本身就原生支持 Composer 仓库类型，并能自动处理认证、袋里和缓存，Satis 在此场景下反而成了冗余层。
• CI/CD 中的前置步骤：在持续集成流水线中触发 Satis build 之前，务必先执行 git fetch --all --tags。这一步能确保拉取到所有远程分支和最新的标签，否则新打的 tag 将无法被 Satis 发现和收录。

话说回来，搭建过程本身并不复杂，真正的挑战往往来自后续的协作与维护。试想这样一个场景：某个团队悄悄修改了私有包的 composer.json，将 autoload 配置从 PSR-0 改为了 PSR-4，却忘了同步更新命名空间。Satis 的全量构建会成功，但其他成员在执行 composer install 后，会发现类根本找不到。这种问题不会导致构建报错，却足以让依赖它的应用运行时崩溃。

这就是 Satis 的局限性：它不负责校验 autoload 配置的正确性。因此，必须依靠构建前的 CI 检查来兜底，确保每次更新都不会破坏下游的依赖关系。这才是保障私有仓库长期稳定运行的关键所在。