GitLab PAT必须启用read_api和read_repository权限；需在composer.json中声明HTTPS仓库URL；auth.json中username为git、password为完整PAT，域名须完全一致。
GitLab 个人访问令牌（PAT）必须开启哪些权限
Composer 访问私有 GitLab 仓库时，不能用账号密码或 SSH 密钥，必须用 Personal Access Token（PAT），且权限不足会导致 401 Unauthorized 或 403 Forbidden 错误。
创建 PAT 时，至少勾选以下 scope：
-
read_api：读取项目元数据（必需） -
read_repository：克隆代码（必需） -
read_registry（如需拉取私有 GitLab Container Registry 的包，可选）
别选 api 全权限——没必要，也不安全。Token 创建后只显示一次，请立即复制保存。
在 composer.json 中声明 GitLab 私有仓库源
不能只靠全局配置，必须在项目根目录的 composer.json 中显式声明 repositories，否则 Composer 不知道该向哪个 GitLab 实例发起请求。
示例（假设你的 GitLab 地址是 https://gitlab.example.com）：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/your-group/your-private-package.git"
}
],
"require": {
"your-group/your-private-package": "^1.0"
}
}
注意：url 必须是 HTTPS 形式（不是 git@…），且域名要和后续配置的 GitLab 实例完全一致（含端口、协议），否则认证会失败。
用 config.json 配置 HTTP Basic 认证凭据
Composer 对 HTTPS VCS 源使用 HTTP Basic Auth，需把 PAT 当作密码、用户名填 git（GitLab 要求），写入全局或项目级 auth.json。
推荐方式：在项目根目录新建 auth.json（与 composer.json 同级），内容如下：
{
"http-basic": {
"gitlab.example.com": {
"username": "git",
"password": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
}
}
关键点：
-
username固定为git，不是你的 GitLab 账号名 -
password填你生成的完整 PAT（如glpat-abc123...） - 域名（
gitlab.example.com）必须和composer.json中仓库 URL 的 host 完全一致，包括大小写和端口（如gitlab.example.com:8443） - 不要把
auth.json提交到 Git——加进.gitignore
验证是否生效：运行 install 并观察调试输出
执行 composer install -vvv（不是 update），看日志里是否出现类似以下行：
Downloading https://gitlab.example.com/your-group/your-private-package.git Cloning to /path/to/vendor/your-group/your-private-package
如果卡在 Reading composer.json of your-group/your-private-package (dev-main) 后报 401，说明认证失败，常见原因：
- PAT 权限不够（缺
read_repository） -
auth.json域名拼错，或漏了端口 - GitLab 实例启用了 Two-Factor Authentication（2FA）但 PAT 未关联（其实不影响，PAT 本身绕过 2FA）
- GitLab 管理员禁用了 Personal Access Token 的 API 访问（需联系管理员检查
Settings > Network > API access）
私有 GitLab 包最脆弱的一环不是配置多难，而是域名、协议、token scope 这三处细节不匹配——哪怕只差一个字符或一个端口，都会静默失败。
