Composer如何配置私有仓库源_Composer私有仓库添加配置指南【详解】

先说几个核心判断。私有仓库这事儿，必须在项目根目录的 composer.json 里显式地声明给Composer看，不然它就当没看见。你可以在内网搭一个Git仓库，也可以在GitHub上开一个私有库，但Composer不会自动去扫描这些地方——它连试都不会试一下。

所以，composer require 失败的时候，别急着怀疑认证配置，先回头看看 repositories 字段有没有写，写对了没有。

repositories 字段必须是数组，且 type 不能写错

不少人在这里栽过跟头：把 repositories 写成了对象（比如 {"my-vcs": {...}}），或者漏掉了 type 字段。Composer只认JSON数组，每个仓库项必须包含 type 和 url，缺一不可。

• type 只能是 vcs（对应Git/SVN/Hg）、composer（比如Satis这类服务）或者 path（本地开发时用），写 git 或 github 都不行
• url 要指向Git仓库的根目录——也就是那个包含 composer.json 的地址，不是某个分支页或tag页
• 如果同时配置了多个源，顺序决定优先级：Composer会从上往下扫描，匹配到第一个就停，后面的同名包会被忽略
• 想禁用默认的Packagist源，必须单独加一项 {"packagist.org": false}，不能塞进其他仓库对象里

认证凭据只能放 auth.json，且权限必须是 600

auth.json 才是唯一合法的载体。硬编码到 composer.json 里，或者直接塞进URL（比如 https://token:xxx@...），Composer会拒绝执行，而且还有泄露风险。这个文件必须放在项目根目录（与 composer.json 同级），或者全局路径下，权限严格设为 600。

• HTTP Basic认证（比如私有GitLab）用 http-basic 字段，域名填 gitlab.example.com，不是完整URL
• GitHub私有库推荐用 github-oauth + Personal Access Token，scope至少包含 read:packages
• SSH方式（git@gitlab.com:org/repo.git）不依赖 auth.json，但前提是部署机已经加载了对应密钥到 ssh-agent
• CI环境的话，建议用 COMPOSER_AUTH 环境变量注入JSON格式的凭据，省得挂载文件出问题

vcs 类型下，版本号实际来自 Git tag，不是 composer.json 的 version 字段

这一点特别值得注意：Composer在解析vcs包时，完全忽略 composer.json 里的 version 字段。它只认Git的tag和分支名。也就是说，你写在 composer.json 里的版本号，对Composer来说就是个摆设。

• 想用 "^1.0" 这种约束，就必须打 v1.0.0 或 1.0.0 这样的语义化tag；v1.0 或 1.0 这种格式不被识别
• 分支名比如 main，对应的是虚拟版本 dev-main，require时得写 "dev-main"，而且需要 "minimum-stability": "dev"
• 如果仓库里一个tag都没打，那 dev-main 就是唯一可用选项；写 "1.0.0" 会直接报错：Could not find package ... at version 1.0.0
• 别用 package 类型去硬编码单个包——维护成本太高，而且无法跟随Git仓库更新

require 中的包名必须和私有仓库 composer.json 的 name 字段完全一致

最后一个容易踩的坑：大小写敏感，多一个空格、少一个下划线，都不行。这是最容易被忽略的匹配点，但一旦出错，Composer只会静默跳过，没有任何报错提示。

• 假设私有仓库的 composer.json 里写的是 "name": "myorg/utils"，那 require 里必须写 "myorg/utils"，不能写成 "MyOrg/utils" 或 "myorg-utils"
• 如果用 path 类型做本地联调，url 指向的目录里也必须有一个合法的 composer.json，且 name 仍然要匹配
• 包名冲突时，靠 repositories 的顺序来控制：把私有源放在 packagist.org 前面，才能确保拉到你自己的版本
• 执行完 composer require 后，去 vendor/ 目录下检查一下，看看有没有生成对应的目录。没生成的话，说明根本没匹配上源，而不是认证问题

真正卡住的地方，往往不是“怎么配”，而是“配了但没生效”——比如 repositories 放错了位置、auth.json 权限不对、或者包名大小写差了一位。这些地方没有报错提示，只会静默跳过。动手前先确认这三点：数组格式对不对、auth.json 在不在项目根目录且 ls -l 看过权限、私有包的 name 和 require 里写的是否一字不差。