需在 composer.json 的 repositories 字段添加 type 为 vcs 的配置，指向 GitLab 项目 HTTPS 或 SSH 地址，并通过 auth.json 配置 Personal Access Token（username 为 oauth2，password 为 glpat-xxx），同时确保私有包 composer.json 中的 name 与引用名一致。

怎么在 composer.json 里声明 GitLab 私有仓库

Composer 默认只认 Packagist，要拉取 GitLab 上的私有包，必须显式告诉它“这个仓库在哪、怎么认证、用什么协议”。核心是往 composer.json 的 repositories 字段里加一条类型为 vcs 的配置，指向你的 GitLab 项目 HTTPS 或 SSH 地址。

常见错误是直接写 https://gitlab.example.com/group/pkg.git 却没配认证，结果 composer install 卡在 “Could not fetch https://gitlab.example.com/group/pkg.git” 或报 401/403。HTTPS 方式必须配 auth.json；SSH 方式则依赖本地 ~/.ssh/id_rsa 和 GitLab 账户已绑定公钥。

• HTTPS 示例（推荐用于 CI/CD）：

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

• SSH 示例（适合开发者本地）：

  "url": "git@gitlab.example.com:group/my-package.git"

• 务必确认该 URL 能在命令行用 git clone 成功拉下代码，否则 Composer 一定失败

auth.json 怎么配才能让 Composer 认 GitLab

GitLab 不支持 Composer 原生的 HTTP Basic Auth（即用户名密码直传），必须用 Personal Access Token（PAT）。这个 token 要有 read_api 和 read_repository 权限，不能用密码或 deploy token（后者不支持 API 调用）。

auth.json 必须放在用户主目录（~/.composer/auth.json）或项目根目录（./auth.json），且权限需设为 600，否则 Composer 会忽略它并报错 “Authentication required”。

• 正确内容示例：

  {
    "http-basic": {
      "gitlab.example.com": {
        "username": "oauth2",
        "password": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }

• username 固定填 oauth2 —— 这是 GitLab 的约定，不是你的账号名
• password 填你生成的 PAT，不是密码，也不是 token 名
• 如果 GitLab 启用了 2FA，PAT 是唯一可行方式；用密码会始终 401

为什么 composer require 拉不到私有包，却显示 “Package not found”

这不是网络或认证问题，而是 Composer 根本没去 GitLab 查——它只查 Packagist 和你 repositories 里明确列出的仓库。如果你的私有包没在 repositories 中声明，或者声明了但包名（vendor/name）和 GitLab 项目路径不一致，就会报这个错。

word-chinese-automation

中文 Word 文档自动化校对工具。当用户需要对中文文本或 Word 文档进行标点符号检查、语法检查、错别字检查时使用此 skill。触发词：语法检查、错别字、标点符号、校对、检查文档。

下载

关键点：GitLab 仓库的 composer.json 里必须有正确的 name 字段，比如 "name": "mycompany/utils"；而你在主项目中运行 composer require mycompany/utils，这个 mycompany/utils 必须和 GitLab 项目 URL 的路径（group/project）能对应上，否则 Composer 找不到源头。

• 检查私有包的 composer.json 是否含 "name"，且格式为 vendor/package
• 确保 repositories 的 url 指向的是该包的 Git 仓库地址，不是 GitLab 页面 URL
• 运行 composer show -p 看是否列出了你的私有包名；没列出说明 repositories 配置未生效或包名不匹配

CI/CD 中如何安全注入 GitLab Token

把 PAT 写死在 auth.json 里提交到 Git 是严重安全风险。CI 环境（如 GitLab CI）应通过环境变量注入，并在 job 开始时动态生成 auth.json。

GitLab CI 的 .gitlab-ci.yml 中，用 before_script 创建临时 auth.json，注意路径必须和 Composer 查找路径一致（通常为 $HOME/.composer/auth.json），且设置权限。

• 示例脚本：

  before_script:
    - mkdir -p $HOME/.composer
    - echo '{"http-basic": {"gitlab.example.com": {"username": "oauth2", "password": "'$GITLAB_TOKEN'"}}}' > $HOME/.composer/auth.json
    - chmod 600 $HOME/.composer/auth.json

• $GITLAB_TOKEN 是 GitLab CI 设置的 masked 变量，不能明文泄露
• 不要用 COMPOSER_AUTH 环境变量——它只支持 Base64 编码的 JSON，容易出错且不直观
• 本地开发建议用 git config --global credential.helper store 配合 HTTPS + PAT，避免每次输 token

私有仓库对接最常卡在认证链路断掉，而不是配置本身。重点盯住三处：GitLab PAT 权限是否开全、auth.json 路径和权限是否正确、私有包的 name 和 repositories.url 是否能逻辑对应。漏掉任一环，Composer 都只会安静地报一个模糊的“not found”。