Composer如何自定义源 Composer私有仓库配置指南

实战中会发现，配置私有包源往往会遇到几个典型的坑——大部分问题其实就卡在几个细节点上。下面这些配置要点，算是从重复踩坑中总结出来的规律，希望能帮你少走弯路。

先说第一个硬性前提：必须在项目根目录的 composer.json 里显式声明 repositories 数组。不声明的话，无论是 composer require 还是 composer install 都一定失败——Composer 既不会自动探测，也不会报告“源未配置”，而是安静地返回一句 Could not find package。所以，这一步不能省。

repositories 字段怎么写才合法

文档结构必须是 JSON 数组，每一项至少包含 type 和 url，而 type 只有三种选择：

• vcs：直接对接 Git/SVN/Hg 仓库，url 填 HTTPS 或 SSH 地址即可（例如 "https://gitlab.example.com/org/pkg"），注意不要加 .git 后缀
• composer：用于对接 Satis、Private Packagist 这类服务，url 是一个能返回 packages.json 的 HTTP 地址（比如 "https://satis.internal"）
• path：本地开发场景，url 用相对或绝对文件路径（如 "../my-private-package"），支持通配符 **

常见的错误写法也不少：repositories 被写成了对象（例如 {"my-repo": {...}}），或者 type 写成了 "git"、"github"，再或者 url 指向了 GitHub 的某个 tag 页面（正确的做法是指向仓库根）。这些细节稍不注意，就会功亏一篑。

认证凭据只能走 auth.json，不能硬编码

HTTPS 私有源（比如 GitLab、GitHub）需要认证凭据，但有一条铁律：绝对不能拼进 URL（例如 https://token@... 这种写法），也不能写进 composer.json。唯一的合规载体是 auth.json：

• 文件必须放在项目根目录（与 composer.json 同级），或者放在 COMPOSER_HOME 目录下
• 权限必须设置为 600（Linux/macOS 环境下），否则 Composer 会静默忽略，既不报错也不提示——这一点非常容易忽略
• 内容结构是标准 JSON，http-basic 和 github-oauth 是平级字段，示例：

{
  "http-basic": {
    "gitlab.example.com": {
      "username": "deploy",
      "password": "xxx"
    }
  },
  "github-oauth": {
    "github.com": "ghp_xxx..."
  }
}

SSH 方式（例如 git@gitlab.com:org/pkg.git）不需要 auth.json，但前提是当前用户已经把对应的私钥加载进 ssh-agent。

版本号从哪来？composer.json 里的 version 字段基本没用

对于 vcs 类型的仓库，Composer 有一个很多人不太了解的行为：它完全忽略包自身 composer.json 中的 version 字段。版本信息只认 Git 的 tag 和分支名：

• 要让 "^1.0" 这类约束生效，必须打语义化 tag：v1.0.0 或 1.0.0 都可以，但 v1.0 不行——缺少 patch 版本会被忽略
• 分支名（如 main）对应虚拟版本 dev-main，在 require 时必须写 "dev-main"，且需要在项目根 composer.json 中设置 "minimum-stability": "dev"
• 如果一个 tag 都没打，那 dev-main 就是唯一可选的版本；写 "1.0.0" 会直接报错 Could not find package ... at version 1.0.0
• 修改了 tag 对应 commit 并强制推送后，Git 服务器缓存可能未刷新，此时需要运行 composer clear-cache 来强制清除缓存

为什么 composer require 加了包却装不上

这通常不是网络或权限问题，而是配置链出现了断裂。以下是几个典型的断点：

• 只运行了 composer require vendor/name，但没有手动补上 repositories 配置——这条命令本身不会自动添加源地址
• 包名大小写不一致：仓库里 composer.json 写的是 "MyOrg/utils"，但 require 时却写成了 "myorg/utils"
• 多个源共存时顺序错了：repositories 从上到下扫描，第一个匹配的就停下，同名包后面配置的源会被忽略
• 禁用 Packagist 默认源的写法错误：必须单独写 {"packagist.org": false} 作为数组中的一项，不能塞到其他仓库对象内部
• Satis 类型源下，包没有被 php bin/satis build 扫描进 packages.json——可以打开 https://satis.internal/packages.json 搜索一下包名来确认

但最容易被忽略的一点是：所有配置看着都没问题，可就是装不上——去检查一下 auth.json 的权限吧。如果是 644 或放在了子目录下，Composer 就当它不存在，而且不会给出任何提示。