Composer如何配置GitLab私有源_Composer GitLab仓库接入说明【详解】-composer-PHP中文网

必须同时满足：repositories 显式声明为 vcs 类型、url 以 .git 结尾、认证信息正确注入；缺一则报“could not fetch”或“could not find package”，因 composer 仅查询 packagist.org 和 repositories 中合法声明的源，且包名、分支/标签、权限等须严格匹配。

composer如何配置gitlab私有源_composer gitlab仓库接入说明【详解】

Composer 要拉到 GitLab 私有仓库的包，必须同时满足三个硬性条件：repositories 显式声明为 vcs 类型、URL 以 .git 结尾、认证信息正确注入。缺一不可，否则会卡在 Could not fetch 或 Permission denied。

为什么加了 repositories 还是报 “Could not find package”

这不是网络问题，而是 Composer 根本没去你的 GitLab 查——它只查 packagist.org 和你 repositories 里明确列出的源。常见原因包括：

repositories 声明顺序错误：私有源必须放在 packagist.org 之前，否则被跳过（可加 "packagist.org": false 彻底禁用）
包名不一致：require 中写的 "myorg/internal-sdk" 必须和 GitLab 项目根目录 composer.json 里的 "name" 字段完全一致（大小写、斜杠、vendor 名都敏感）
URL 不合法：漏掉 .git 后缀（GitLab 15+ 强制校验）、用了 Web 页面 URL（如 https://gitlab.example.com/group/project）而非克隆地址
分支/标签没显式指定："myorg/internal-sdk": "^1.0" 会去 Packagist 查，必须写成 "myorg/internal-sdk": "dev-main" 或 "v2.1.0"

HTTPS 方式怎么配 Token 才不 401

GitLab 不接受 HTTP Basic Auth 的用户名密码组合，只认 Personal Access Token（PAT）或 Deploy Token，并且必须通过特定方式传递：

Git Factory

为每个编码任务配置并管理独立的 Git worktree，支持并行分支和清晰的 PR 工作流，避免合并冲突。

下载

Token 必须有 read_repository 权限（read_package_registry 没用）
不能塞进 auth.json 的 http-basic 下——那是给 SVN 或旧版私有 Packagist 用的

正确位置是 auth.json 的 gitlab-token 键下，结构为：

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

更安全的做法是用环境变量：COMPOSER_AUTH='{"http-basic":{"gitlab.example.com":{"username":"deploy-token-123","password":"abc456def789"}}}'（Deploy Token 场景）
本地调试时可用 composer config --global gitlab-token.gitlab.example.com <token></token>，自动处理格式和权限

SSH 方式为什么 clone 失败

SSH 不走 auth.json，完全依赖系统 SSH 配置，失败通常是因为链路断在中间某环：

GitLab 项目没添加 Deploy Key（或用户 SSH Key），且未勾选 Write access allowed（只读可不勾）
本地 ssh-agent 没加载对应私钥：ssh-add -l 看是否列出，没列就 ssh-add ~/.ssh/id_rsa
测试连通性必须用 ssh -T git@gitlab.example.com，返回 Welcome to GitLab 才算通
composer.json 中 url 必须是标准 SSH 格式："git@gitlab.example.com:group/project.git"，不能混用 HTTPS 域名
CI 环境中注意 CI_SERVER_URL 解析出的域名是否和 Deploy Key 绑定的 host 完全一致（比如带端口或子域）

为什么 composer install 总是走 API 下载 zip 而不是 clone

因为没声明 "type": "vcs"，Composer 默认把所有 HTTPS URL 当作 dist 源处理，试图调 GitLab API 下载 /archive.zip——而私有库默认关闭该 API 匿名访问。

必须显式写 "type": "vcs"，强制走 git clone 流程，后续才能注入 Token 或走 SSH
Deploy Token 只支持 HTTPS 协议，不能用于 SSH；若要用，得拼进 URL："https://deploy-token-123:abc456def789@gitlab.example.com/group/project.git"
但硬编码 Token 到 composer.json 是高危操作，CI 中应通过 secret 注入 auth.json 或用 COMPOSER_AUTH
确认 ~/.composer/auth.json 权限是 600，否则 Composer 直接忽略该文件