私有GitLab仓库必须配置为vcs类型源并用Deploy Token认证，不可用dist源；URL须以.git结尾，Token应通过COMPOSER_AUTH环境变量注入，避免硬编码。
私有GitLab仓库必须配置为VCS类型源，不能用dist
很多开发者初次配置私有GitLab仓库时，会直接遇到一个典型的“拦路虎”：运行composer install时，控制台突然报错Could not fetch https://gitlab.example.com/api/v4/projects/xxx/repository/archive.zip?sha=...。这背后是什么原因？
其实，Composer默认会把GitLab仓库当作dist源来处理，也就是试图去下载预打包的zip或tar压缩包。但问题在于，绝大多数私有项目压根就没有启用GitLab的Package Registry，自然也就没有发布过dist包。当Composer尝试通过API去匿名访问时，吃闭门羹就成了必然结果。
正确的解决思路很明确：必须显式地告诉Composer，这个源是vcs类型的，让它走git clone的流程。只有这样，后续的Deploy Token认证机制才能生效。配置起来也很简单：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/group/project.git"
}
]
}
这里有个细节必须注意：url字段的结尾必须是.git。如果少了这个后缀，Composer很可能无法正确识别这是一个Git仓库，从而导致配置失效。
Deploy Token需拼在Git URL里，且仅限HTTPS协议
明确了源类型，接下来就是认证。GitLab的Deploy Token本质上是一组HTTP Basic Auth凭证，这就决定了它只能用于HTTPS协议的克隆操作，SSH方式是不支持的。
最直接的方法，就是把Token信息直接嵌入到composer.json的仓库URL中：
{
"repositories": [
{
"type": "vcs",
"url": "https://deploy-token-123:abc456def789@gitlab.example.com/group/project.git"
}
]
}
- 这里的
deploy-token-123是Token用户名，abc456def789是Token值，中间用冒号连接。你不需要手动进行Base64编码——Composer会原样传递给Git，由Git自己来处理Basic Auth认证。 - 务必确认Token拥有
read_repository权限。read_package_registry权限与此无关，那是给CI流程拉取Composer包用的。 - 然而，直接把Token明文写进
composer.json并提交到版本库，是一个绝对要避免的安全风险。密钥一旦泄露，后果不堪设想。更优雅、更安全的做法是通过环境变量注入，我们接下来就谈这个。
用COMPOSER_AUTH环境变量避免明文泄露
如何既保证认证，又避免密钥硬编码？答案就是COMPOSER_AUTH环境变量。这可以说是Composer官方推荐的最佳实践。
export COMPOSER_AUTH='{"http-basic":{"gitlab.example.com":{"username":"deploy-token-123","password":"abc456def789"}}}'
composer install
这个JSON结构清晰地告诉Composer：当访问gitlab.example.com这个域名下的任何HTTPS Git地址时，请自动带上配置好的Basic Auth头。这种方式不仅更安全，还具备良好的扩展性，能轻松支持多个不同GitLab实例共存的情况。
- 在CI/CD环境（比如GitLab CI）中，直接在
.gitlab-ci.yml文件的variables部分设置即可。 - 对于本地开发环境，虽然可以写入
~/.composer/auth.json文件，但请务必注意文件权限必须设置为600，否则Composer出于安全考虑会拒绝读取。 - 另外提一点，即使GitLab管理员为账户启用了双因素认证（2FA），Deploy Token依然可以正常使用——因为它走的是独立的API认证流程，与用户的个人登录流程无关。
常见失败原因：Git子模块、subtree或自定义install-path干扰
即使上面每一步都做对了，有时认证还是会莫名其妙地失败。这时候，就需要排查一些“隐藏关卡”了。当你的项目结构比较复杂，比如包含了Git子模块，或者在composer.json里配置了"type": "project"加上自定义的"install-path"时，Composer的行为可能会变得有些“调皮”。
它有可能绕过你精心设置的COMPOSER_AUTH，转而回退到系统级的Git凭据管理器（例如git-credential-manager）去获取凭证，从而导致认证失败。
如何验证？运行composer install -vvv命令，开启最高级别的详细日志。仔细观察输出中是否出现了Cloning [url] via git clone的字样，以及后面是否跟着Failed to clone ... could not read Username这类错误信息。
- 临时解决方案：可以执行
git config --global credential.helper ''来临时禁用全局的Git凭据助手，强制Git使用你提供的认证信息。 - 根本解决方案：确保所有私有的Composer依赖都在
repositories里明确定义为vcs类型源，并且避免使用Git子模块来管理Composer依赖。 - 如果项目确实离不开Git子模块，可以考虑换一种思路：改用
post-install-cmd脚本，在Composer安装完成后，手动执行git submodule update --init，并提前通过git config命令配置好包含Deploy Token的远程仓库地址。
最后需要特别提醒的是：Deploy Token并非一把“万能钥匙”。它的能力范围仅限于git clone操作。对于后续的git pull、git submodule更新或者git archive等命令，它并没有自动的“透传”能力。这个局限性，在实际部署中常常被忽略，值得大家警惕。
