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 这三处细节不匹配——哪怕只差一个字符或一个端口，都会静默失败。