gitlab-domains 是 Composer 配置项，用于声明自定义 GitLab 域名以支持私有仓库拉取。它必须包含 gitlab.com 和企业内网域名（如 git.mycompany.com），否则 Composer 无法识别私有 GitLab 项目。配置位于 composer.json 的 config 字段中，格式为数组；同时需在 repositories 中添加 VCS 类型的私有包地址。Composer 通过该配置识别 GitLab 实例并使用 Git 协议或 HTTPS 拉取代码，结合 Personal Access Token 或 SSH 密钥进行认证，确保公有和私有部署均可访问。
在使用 Composer 管理 PHP 项目依赖时，如果需要从私有 GitLab 仓库拉取包，config.gitlab-domains 是一个关键配置项。它允许 Composer 正确识别自定义或私有 GitLab 实例的域名，从而顺利克隆和更新代码。
什么是 gitlab-domains 配置？
Composer 默认支持 gitlab.com，但对于企业自建的 GitLab 服务（如 git.company.com），必须通过 gitlab-domains 明确声明这些域名，否则 Composer 无法识别其为 GitLab 项目，导致克隆失败。
该配置位于 composer.json 文件的 config 字段中，用于扩展 Composer 对 GitLab 服务的支持范围。
如何配置 gitlab-domains 字段
打开项目的 composer.json 文件，在 config 节点下添加 gitlab-domains，值为一个包含域名的数组。
gitlab.com，否则公共 GitLab 项目将无法访问。
示例配置：
{
"config": {
"gitlab-domains": ["gitlab.com", "git.mycompany.com", "gitlab.internal.net"]
}
}
上面配置告诉 Composer：以下域名均视为 GitLab 实例：
- gitlab.com（官方）
- git.mycompany.com（企业内网）
- gitlab.internal.net（私有部署）
配合 VCS 配置使用私有仓库
仅配置域名还不够，还需在 repositories 中声明私有包地址，Composer 才能定位到具体项目。
示例：
{
"repositories": [
{
"type": "vcs",
"url": "https://git.mycompany.com/php-utils/package-a.git"
}
],
"require": {
"mycompany/package-a": "^1.0"
},
"config": {
"gitlab-domains": ["gitlab.com", "git.mycompany.com"]
}
}
当执行 composer install 时，Composer 会：
- 识别 URL 属于已配置的 GitLab 域名
- 自动使用 Git 协议或 HTTPS 拉取代码
- 根据项目中的
composer.json解析版本信息
认证方式说明
访问私有 GitLab 仓库通常需要身份验证。Composer 支持以下方式：
-
Personal Access Token：推荐方式，在 GitLab 用户设置中生成 token，并在命令行首次访问时输入用户名为
oauth2，密码为 token 值。 -
SSH 密钥：若使用 SSH 地址（如
git@git.mycompany.com:group/project.git），需确保 SSH 公钥已添加到 GitLab 账户。
Composer 会在本地缓存凭证（通常在 auth.json），避免重复输入。
基本上就这些。正确配置 gitlab-domains 后，Composer 就能无缝接入任意 GitLab 实例，无论是公有还是私有部署。关键是别漏掉默认域名，且确保网络与权限通畅。
