私有 git 仓库需通过 auth.json 配置认证凭据（如 github pat 或 gitlab token）并置于 composer 全局配置目录，同时在项目 composer.json 的 repositories 中声明 type="vcs" 的 https git url，且包名须与私有仓库内 composer.json 的 name 完全一致。
私有 Git 仓库需要 auth.json 才能拉取
Composer 默认拒绝未经认证的私有仓库访问，直接 composer require 会报 401 Unauthorized 或 403 Forbidden。关键不是改 composer.json，而是让 Composer 知道“你是谁”——这靠 auth.json 文件实现。
它必须放在 Composer 的配置目录下（不是项目根目录），路径取决于系统：
- Linux/macOS：
~/.composer/auth.json - Windows：
%APPDATA%\Composer\auth.json
内容格式严格，不能多字段、不能少引号：
{
"http-basic": {
"github.com": {
"username": "your-github-username",
"password": "your-personal-access-token"
},
"gitlab.example.com": {
"username": "gitlab-user",
"password": "gitlab-private-token"
}
}
}
注意：GitHub 已停用账号密码登录，必须用 Personal Access Token（勾选 repo 权限）；GitLab 同理用 Private Token。
composer.json 中声明私有仓库类型和 URL
只配 auth.json 不够，Composer 还得知道“从哪拉”。私有包不能靠 Packagist 自动发现，必须显式声明仓库源。
在项目根目录的 composer.json 里加 repositories 字段：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/your-org/your-package.git"
}
],
"require": {
"your-org/your-package": "^1.0"
}
}
关键点：
-
type必须是vcs（不是package或composer），否则不走 Git 协议 -
url必须带.git后缀，否则 Composer 可能忽略或报Could not fetch - 包名（
your-org/your-package）要和仓库里composer.json中的name完全一致，包括大小写
遇到 Failed to clone 或 no matching package found 怎么排查
这类错误表面是网络或语法问题，实际多半是认证或元数据错位。
先运行 composer diagnose，它会检查 auth.json 是否可读、格式是否合法；再试 composer clear-cache——旧缓存可能卡住错误凭证。
常见漏点：
- Git 仓库的
composer.json缺少version字段，且没打 Git tag → Composer 无法解析版本约束，报no matching package found - 私有域名用了 HTTPS，但公司内网 Git 服务实际走 HTTP →
url写成http://却没在auth.json里配对应 host - 使用 SSH URL（如
git@gitlab.example.com:org/pkg.git）但没配 SSH key，此时auth.json完全无效，得走 SSH 代理或换 HTTPS + token
CI/CD 环境下怎么安全传入凭证
本地开发可以放 auth.json，但 CI 脚本里硬编码 token 是高危操作。GitHub Actions、GitLab CI 都支持变量注入，但必须避开日志泄露。
推荐做法是运行时生成 auth.json：
echo '{"http-basic": {"gitlab.example.com": {"username": "ci-bot", "password": "'"$GITLAB_TOKEN"'"}}}' > ~/.composer/auth.json
注意点：
- 确保
$GITLAB_TOKEN是 CI 平台标记为 “secret” 的变量，不会被 echo 到日志 - 不要用
composer config命令写入，它会把 token 明文记进composer.json或全局配置，极易泄露 - Docker 构建时，别把
auth.jsonCOPY 进镜像——构建缓存和镜像层都可能暴露凭证
私有包认证最麻烦的从来不是“怎么配”，而是“什么时候配、在哪配、配完要不要删”。尤其跨环境时，auth.json 的生命周期比代码还难管。
