PHP开发团队如何高效使用Composer私有仓库-composer-PHP中文网

必须显式添加"packagist.org": false禁用默认源，否则私有仓库仅作fallback；url末尾斜杠不可省，satis需确保packages.json可公开访问且返回200。

php开发团队如何高效使用composer私有仓库

私有仓库URL配置必须显式禁用packagist.org

项目里加了私有源却始终 Could not find package vendor/name？根本不是网络或路径问题，而是 Composer 默认仍会优先查 packagist.org，你的私有仓库只是 fallback——哪怕 URL 完全正确，只要没关掉默认源，私有包就永远不会被匹配。

必须在项目级 composer.json 的根层级写明：

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://satis.example.com/"
    }
  ],
  "packagist.org": false
}

"packagist.org": false 这一行不能省，漏掉就会静默回退到公网源
url 值末尾的斜杠 / 必须保留，少一个就 404
如果用了 Artifactory 或 Nexus，type 必须是 composer，不是 generic 或 remote

Satis 构建后 packages.json 不可访问 = 整个私有源失效

Satis 生成的是静态文件，不提供动态 API。Composer 客户端只认 packages.json 这个入口，它加载失败，后续所有包都不可见——但错误不会报出来，只会默默 fallback 到 packagist.org。

First Principles Decomposer

把任何问题拆解为根本真理，再从原子层面重建解决方案。

下载

用 curl -I https://satis.example.com/packages.json 检查返回是否为 200；若为 403 或 404，Nginx/Apache 配置大概率漏了目录索引或 MIME 类型
确保 Web 服务能直接读取 dist/ 目录下的 ZIP 包，比如 Nginx 需要显式允许 .zip 后缀的下载
别开 autoindex on，否则整个 dist/ 目录结构裸奔，核心包可能被未授权下载

require-all 和 require 的选择直接影响包可见性

satis.json 里用 "require-all": true 最省事，但它会把所有 VCS 仓库里所有 tagged 分支、dev-master 全部拉进来——包括你根本不想对外暴露的实验性分支。

生产环境推荐用精确 require 字段，例如：

"require": {
  "company/payment-module": "1.5.0",
  "company/auth-library": "dev-stable"
}

Git 仓库 URL 必须可匿名克隆（HTTPS）或已配好 SSH key，否则 Satis 构建时会卡在 fetch 阶段，且不报错
如果某私有包依赖另一个私有包，两个都得出现在 repositories 数组里，否则 Satis 解析依赖树时会跳过

团队协作中 composer.lock 的更新必须走私有源

开发人员本地执行 composer update 时，如果没同步更新 composer.json 中的私有源配置，或者忘了加 "packagist.org": false，composer.lock 就会混入来自 packagist.org 的版本——下次 CI 构建时因无法访问公网而失败。

建议把私有源配置写进团队模板 composer.json，并加入 pre-commit hook 校验 "packagist.org": false 是否存在
CI 流程中执行 composer install 前，先跑 composer config --global repo.packagist false，双重保险
私有包的版本号不要依赖 Git commit hash，Satis 只认 tag 或稳定分支名；dev-master 在不同构建时间可能指向不同代码，导致不可重现部署

最关键的细节往往藏在最不起眼的地方：一个斜杠、一行布尔值、一次未验证的 packages.json 可达性——这些不是“配置完就能跑”的边缘情况，而是决定私有仓库到底算不算真正上线的分水岭。