如何设置Composer私有仓库源？接入私有源详细指南【实操】

本文共计886个文字，预计阅读时间需要4分钟。

私藏仓库不会自动识别，必须在项目的根目录下的 `composer.json` 文件中明确声明。否则，使用 `composer require vendor/name` 安装依赖时，一定会报错 `Could not find package`。

repositories 字段必须写在项目 composer.json 里

这是最常被忽略的前提——不是改私有包自己的 composer.json，也不是配全局 ~/.composer/config.json，而是你当前项目的根目录 composer.json。

• Composer 查包时只看当前项目 composer.json 的 repositories 数组，顺序从上到下匹配，找到第一个就停
• 如果没加这一项，哪怕 Git 地址能 git clone 成功，composer require 也会直接失败
• 错误示例：只在私有库的 composer.json 里写了 "name": "myorg/utils"，却忘了在业务项目里声明源

vcs 类型必须配对 Git 可克隆地址

用 "type": "vcs" 接入私有 Git 仓库时，url 必须是能被本地 shell 直接 git clone 的地址，且认证已就绪。

• 推荐用 SSH 协议："url": "git@gitlab.example.com:myorg/utils.git"；确认方式：git ls-remote git@gitlab.example.com:myorg/utils.git 能返回 ref 列表
• HTTPS 方式需提前配置凭据，不能把密码塞进 URL（现代 Git 会拒绝），应通过 git config --global url."https://oauth2:TOKEN@...".insteadOf 或 auth.json
• 绝对不要写 "type": "git"——正确类型只有 "vcs"；写错类型会导致静默失败或 Could not find package

包名必须与私有库 composer.json 的 name 完全一致

Composer 不按 Git 地址找包，而是靠 name 字段做精确匹配，大小写、斜杠、vendor 名都必须一字不差。

• 私有库根目录 composer.json 中必须有 "name": "myorg/utils"，且不能是 "MyOrg/Utils" 或 "myorg-utils"
• 你在业务项目中 require 的字符串必须和这个值完全相同，包括连字符、下划线、大小写
• 运行 composer show --all | grep myorg 可验证是否被识别；若无输出，说明 name 不匹配或源未生效

版本依赖必须靠 Git tag，不是 composer.json 里的 version

对于 vcs 类型源，Composer 忽略私有库 composer.json 中的 version 字段，只认 Git tag。

• 必须打符合语义化格式的 tag，如 v1.0.0、1.2.3；v1.0 或 1.0 不会被识别为有效版本
• 没打 tag 时，只能用 dev-main、dev-master 这类分支别名，且需确保 "minimum-stability": "dev" 已设
• 执行 git tag -l 确认 tag 已推送到远端；composer update --lock 后检查 composer.lock 是否写入了该包的 source 和 reference

真正卡住的地方往往不是配置语法，而是 Git 认证没通、tag 没推、name 大小写不一致这三处——它们不会报具体错误，只会统一表现为 Could not find package。