需在 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></your_token>写入，避免手误格式错误
正确结构长这样（注意缩进和引号）：
{
"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"
}
}
}
GitLab 私有源真正的麻烦点不在配置语法，而在于错误信息高度重叠：401、403、404、超时，看起来一样，背后原因完全不同。调试时得一层层确认 token 权限、URL 格式、域名匹配、仓库可见性，缺一不可。 
