关键是要让 Composer 通过 Personal Access Token 实现 GitLab 私有仓库认证：1. 创建含 read_repository 权限的 Token；2. 用 git config 设置 HTTPS URL 替换；3. composer.json 中直接引用带 .git 后缀的 HTTPS 地址；4. 安装前用 git ls-remote 验证访问权限。
要让 Composer 从私有 GitLab 仓库拉取包，关键不是“添加仓库”，而是让 Composer 能认证并访问该仓库。GitLab 私有项目需要 token（或 SSH）配合，而最常用、最可控的方式是用 Personal Access Token 配合 GitLab 的 API 和 Git 协议（HTTPS）完成认证。
1. 创建 GitLab Personal Access Token
登录 GitLab → 右上角头像 → Settings → Access Tokens → 填写 Token 名称（如 composer-read），勾选 read_repository（必要），可选 api（如果要用 GitLab API 自动发现包信息）。生成后务必复制保存——页面刷新后无法再次查看。
2. 配置 Composer 全局或项目级 Git 认证
Composer 通过 Git 命令克隆仓库，所以需让 Git 知道如何用 token 访问 HTTPS 地址。推荐使用 git config 设置凭证助手，避免明文写在 composer.json 中：
- 运行命令（替换
your-token和gitlab.example.com）：
git config --global url."https://oauth2:your-token@gitlab.example.com".insteadOf "https://gitlab.example.com"
这样，所有对 https://gitlab.example.com 的 HTTPS 请求都会自动带上 token 认证。注意：token 是密码角色，务必设为只读权限，且不要提交到代码库。
3. 在 composer.json 中声明包（无需额外 repository 配置）
只要 Git 能 clone，Composer 就能安装。直接在项目的 composer.json 的 require 中写目标包的完整 HTTPS Git URL（带 .git 后缀）和版本约束：
"require": {
"vendor/my-private-package": "dev-main"
},
"repositories": [
{
"type": "package",
"package": {
"name": "vendor/my-private-package",
"version": "dev-main",
"source": {
"url": "https://gitlab.example.com/vendor/my-private-package.git",
"type": "git",
"reference": "main"
}
}
}
]
⚠️ 注意：type: "package" 方式适合无 composer.json 的仓库，或需强制指定版本/分支；若私有仓库本身已有标准 composer.json，更推荐省略 repositories，直接靠 Git URL + 版本别名（如 "dev-main as 1.0.x-dev"）让 Composer 自动识别 —— 前提是 Git 能成功 clone。
4. 安装前确认与常见问题
- 执行
git ls-remote https://gitlab.example.com/vendor/my-private-package.git测试是否能匿名/带 token 列出引用（不报 401 或 404） - 如果提示 “Could not fetch”，检查 token 权限、URL 是否拼错、是否用了内部域名（CI/CD 中需确保 runner 能解析）
- 避免在
composer.json或auth.json中硬编码 token；auth.json可用于 CI 环境（如COMPOSER_AUTH环境变量注入），但必须严格保护文件权限（chmod 600）
