composer怎么设置私有Gitlab源_composer怎么拉取公司项目【报告】

需在 composer.json 的 repositories 中声明 type 为 vcs 的 GitLab 仓库 URL，并在 auth.json 的 gitlab-token 下配置匹配域名的 token；require 时用 dev-前缀或 v-tag 指定分支/标签；必要时禁用 packagist.org。

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

Composer 默认只认 packagist.org，要拉公司 GitLab 上的私有包，得先告诉它“这个地址是合法源”。关键不是改全局配置，而是把仓库信息写进项目自己的 composer.json 里。

常见错误是直接往 ~/.composer/auth.json 塞 token 却不声明仓库类型，结果报 Could not fetch https://gitlab.example.com/api/v4/projects/xxx 或直接跳过该源。

• 必须用 "type": "vcs" 声明 GitLab 是版本控制系统源，不是普通 dist 源
• "url" 填项目 HTTPS 地址（如 https://gitlab.example.com/group/project.git），不是 Web 页面 URL
• 如果项目启用了双因素认证或 token 权限不足，会卡在 clone 阶段，此时要确认 token 至少有 read_repository 权限

示例片段：

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

auth.json 怎么配 GitLab token 才有效

GitLab 不走 HTTP Basic Auth，也不读 .netrc，只认 auth.json 里的 gitlab-token 字段。填错位置、权限不够、token 过期，都会导致 401 Unauthorized 或 403 Forbidden。

别把 token 塞进 http-basic 下——那是给 SVN 或老版私有 Packagist 用的，对 GitLab 完全无效。

• token 必须放在 auth.json 的 "gitlab-token" 键下，值为字符串（不是对象）
• 域名必须和 composer.json 里仓库 URL 的 host 完全一致（含端口、协议），比如 gitlab.example.com:8443 和 gitlab.example.com 被视为两个不同域
• 推荐用 composer config --global gitlab-token.gitlab.example.com <your_token> 写入，避免手误格式错误

正确结构长这样（注意缩进和引号）：

ChatDOC

ChatDOC是一款基于chatgpt的文件阅读助手，可以快速从pdf中提取、定位和总结信息

下载

{
    "gitlab-token": {
        "gitlab.example.com": "glpat-xxxxxxxxxxxxxxxxxxxx"
    }
}

require 时怎么指定 GitLab 分支或 tag

私有包没发到 Packagist，就不能用 "vendor/name": "^1.0" 这种模糊写法。Composer 会去 Packagist 查，查不到就报 Could not find package vendor/name。

必须显式指明来源：用完整 Git URL + dev- 前缀或 dev- + 分支名，或者用 v 前缀加 tag 名。

• 引用主分支："company/internal-sdk": "dev-main"（注意不是 main，必须带 dev-）
• 引用带 v 的 tag："company/internal-sdk": "v2.1.0"（GitLab tag 名是 v2.1.0）
• 引用不带 v 的 tag："company/internal-sdk": "2.1.0.0"（Composer 会自动转成 2.1.0.0，但要求 tag 名本身不含 v）
• 切记不要在 require 里写 Git URL —— Composer 不支持这种写法，会解析失败

为什么 composer install 时还是走 public packagist

即使配了私有源，Composer 默认仍会查 Packagist.org，除非你明确禁用或限定范围。结果就是：私有包没命中的时候，它默默跳过，然后报错说“找不到”，而不是告诉你“我根本没去你配的 GitLab 查”。

这不是网络问题，是策略问题。Composer 的仓库查找顺序是链式的，只要前面一个源返回 404（比如 Packagist 没这包），它才继续往后找；但如果私有源本身因认证失败返回 401，它不会 fallback，而是直接中断。

• 加 --verbose 看实际请求地址，确认 Composer 是否真发起了对 GitLab API 的调用
• 用 composer config --list | grep repositories 检查当前生效的源列表，避免被项目级、用户级、全局级配置覆盖
• 最稳妥的做法是设 "packagist.org": false 关掉默认源，强制所有包都走你配的私有源（适合纯内网环境）

关掉默认源的写法：

{
    "repositories": {
        "packagist.org": false,
        "gitlab": {
            "type": "vcs",
            "url": "https://gitlab.example.com/group/project.git"
        }
    }
}