GitLab私有仓库拉取失败主因是auth.json未配置或Token权限不足；需确保Token含read_api和read_repository权限，auth.json按优先级存于环境变量、项目根目录或COMPOSER_HOME，并严格匹配域名。

Composer 无法拉取 GitLab 私有仓库，90% 是因为没配对 auth.json 或 Token 权限不足，不是 Composer 版本或 Git 配置问题。

GitLab Personal Access Token 必须带哪些 scope

Token 权限不够是静默失败的最常见原因——Composer 不报错，但会 fallback 到 HTTPS 匿名请求，然后被 GitLab 拒绝。

• read_api：必须，用于通过 GitLab API 解析包元数据（如 composer.json 中的 repositories 类型为 vcs 时）
• read_repository：必须，用于克隆私有仓库代码（git clone over HTTPS）
• write_repository：仅当你用 composer update --with-dependencies 或需要推送时才需要，日常安装/更新不需

别开 sudo、api 全选——权限过大反而可能触发 GitLab 安全策略拦截。

auth.json 要放哪儿、怎么写才生效

Composer 查找 auth.json 的顺序是：COMPOSER_AUTH 环境变量 → 当前项目根目录 → COMPOSER_HOME 目录（通常是 ~/.composer/ 或 %APPDATA%\Composer\）。全局配置推荐放 COMPOSER_HOME，避免提交到项目里。

Academic Composer Upload

辅助学术写作，包括查找资料、生成大纲、引用扩写及润色风格，同时确保引用规范。

下载

• Linux/macOS 执行：

  mkdir -p ~/.composer && echo '{"http-basic":{"gitlab.example.com":{"username":"oauth2","password":"your_token_here"}}}' > ~/.composer/auth.json

• Windows PowerShell 执行：

  $env:COMPOSER_HOME="$env:APPDATA\Composer"; mkdir $env:COMPOSER_HOME -Force; '{"http-basic":{"gitlab.example.com":{"username":"oauth2","password":"your_token_here"}}}' | Out-File "$env:COMPOSER_HOME\auth.json" -Encoding UTF8

• username 固定填 oauth2（GitLab 要求），password 填 Token 字符串，不是密码
• 域名必须和 composer.json 里仓库 URL 的 host 完全一致（比如用 git@gitlab.example.com 就不匹配，得用 https://gitlab.example.com）

composer.json 里怎么声明 GitLab 私有包

别用 git@ SSH 地址——那走的是 SSH 认证，和 auth.json 无关；要用 HTTPS 地址，并确保协议、域名、路径和 GitLab 实际仓库地址一致。

• 正确写法（HTTPS + 完整路径）：

  "repositories": [
    {
      "type": "vcs",
      "url": "https://gitlab.example.com/group/project.git"
    }
  ]

• 如果项目在子组里（如 group/subgroup/project），URL 必须写全：https://gitlab.example.com/group/subgroup/project.git
• 不要加 .git 后缀？不对——GitLab 仓库 URL 默认带 .git，漏了会 404；但 Composer 有时能自动补，建议显式写上
• 若用 package 类型手动定义（比如想固定某个分支为 dev-master），注意 dist 的 url 也得是 HTTPS，且指向 archive 下载链接（如 https://gitlab.example.com/group/project/-/archive/master/project-master.zip）

调试时怎么看 Composer 到底卡在哪一步

加 -vvv 参数跑 composer install，重点盯三行：

• 看是否命中你配的 domain：Reading ./composer.json 后有没有 Loading config file /home/user/.composer/auth.json
• 看 HTTP 请求头：Downloading https://gitlab.example.com/api/v4/projects/... 表示走了 API；Cloning https://gitlab.example.com/group/project.git 表示走 git clone
• 关键线索是 Failed to decode response: Failed to open https://gitlab.example.com/api/v4/projects/... ——说明 Token 权限不够或域名不匹配

如果看到 Cloning into '/path/to/cache/...'... 但卡住十几秒后报 fatal: Authentication failed，基本是 auth.json 里的域名和实际 URL host 对不上，或者 Token 已过期。