Composer自定义私有源配置最佳实践-composer-PHP中文网

私有包必须置于repositories数组首位，否则因线性匹配机制导致“找不到包”；需用索引数组、url规范、显式禁用packagist.org并兜底配置。

composer自定义私有源配置最佳实践

repositories数组顺序错，私有包直接找不到

Composer 查找包时严格按 repositories 数组顺序遍历，一旦前面的源返回“包不存在”，就不再往后查。私有包如 myorg/internal-sdk 若被放在第二位，而第一位是阿里云镜像，结果就是报 Could not find package myorg/internal-sdk，连认证环节都进不去。

必须把私有源放在数组最前面：

{"type": "vcs", "url": "https://gitlab.internal/myorg/internal-sdk.git"}（Git 仓库）
{"type": "composer", "url": "https://repo.internal/"}（Satis 或 Artifactory 类服务，注意结尾必须带 /）
再补一条 {"packagist": true} 作为兜底元数据查询（不是下载源）

写成对象形式（如 "repositories": { "internal": { ... } }）会被 Composer 静默忽略其余键，只读第一个。

packagist.org 没显式关掉，私有 require 还是去公网查

只要项目级 composer.json 里写了 repositories 数组，Composer 就默认关闭隐式 packagist.org 源——但这个“关闭”不彻底：它只是不自动加进数组，不代表不会尝试访问。实际行为是先查你声明的源，失败后仍会 fallback 到 packagist.org，导致超时或误报。

正确做法是显式禁用并手动加回（带标记）：

在 repositories 里加一项：{"type": "composer", "url": "https://packagist.org", "packagist": false}
不能删掉整条，也不能只写 "packagist": false 在顶层（那会切断所有 composer 类型源）
全局执行 composer config -g packagist false 影响所有项目，CI 环境容易出错，不推荐

验证是否生效：运行 composer show myorg/internal-sdk --verbose，看输出里 dist.url 是否指向你的私有地址，而不是 packagist.org。

First Principles Decomposer

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

下载

vcs 类型 URL 写错，clone 静默失败

"type": "vcs" 的 URL 必须满足三个硬性条件，缺一不可：

必须是能直接 git clone 的地址，例如 https://gitlab.internal/myorg/sdk.git（结尾 .git 不可省）
不能是网页地址（如 GitHub 的 tag 页面 https://github.com/myorg/sdk/releases/tag/v1.2.3），Composer 不解析 HTML
不能拼接 token（如 https://token:x-oauth-basic@github.com/...），凭据必须走 auth.json

验证方式很简单：在项目目录外，手动执行 git clone https://gitlab.internal/myorg/sdk.git。成功后，确认该仓库 main 分支根目录下有合法 composer.json，且其中 "name" 字段为两段式（如 "myorg/sdk"），不能是单段 "sdk"。

HTTP 类型私有源 URL 少斜杠，404 包元数据

当使用 Satis、Artifactory 或自建 Composer 服务时，"type": "composer" 的 url 必须以 / 结尾。否则 Composer 会错误拼接为 https://repo.internal/packages.json（少斜杠 → 多出 packages.json），而不是正确的 https://repo.internal//packages.json（多一个斜杠也行，但少一个必 404）。

同时要注意：

Web 服务（Nginx/Apache）需返回 Content-Type: application/json，否则 Composer 解析失败
auth.json 中的 http-basic 映射，对 IP 地址（如 https://192.168.1.100）无效，必须用域名
凭据绝不能硬编码进 composer.json，应通过 composer config http-basic.repo.internal username password 写入 auth.json，并确保该文件已加入 .gitignore