Composer怎么配置Gitlab私有库 链接内部Gitlab仓库【教程】

gitlab私有库既可用ssh也可用httpS，取决于认证方式和网络环境：SSH需配置密钥且机器可直连，https需配合个人访问令牌（PAT）并通过auth.json安全注入，并注意URL格式、证书信任及仓库可见性设置。

gitlab私有库必须用SSH还是HTTPS？

取决于你的认证方式和网络环境。如果 Gitlab 服务器已配置 SSH 密钥且 composer 所在机器能直连（比如 CI/CD 服务器或开发机已配好 ~/.ssh/id_rsa），优先用 SSH；否则 HTTPS 更稳妥，尤其内网 Gitlab 开了 LDAP 或 OAuth 登录时，得配合个人访问令牌（PAT）用。

常见错误：直接写 https://gitlab.example.com/group/repo.git 却没配认证，Composer 报错 Could not fetch https://gitlab.example.com/group/repo.git, enter your gitlab.example.com credentials... —— 这说明它卡在 HTTP Basic Auth 环节，不是权限问题，是凭据没传过去。

• SSH 地址格式必须是 git@gitlab.example.com:group/repo.git（注意冒号，不是斜杠）
• HTTPS 地址必须带 .git 后缀，且后续要配 auth.json 或 config.json 注入 Token
• 内网 Gitlab 若用了自签名证书，需在 composer config --global cafile /path/to/cert.pem 指定证书，否则 HTTPS 克隆会失败

怎么让 Composer 读取 Gitlab 的个人访问令牌（PAT）？

不能把 token 写进 composer.json，也不能明文塞 URL 里（如 https://token:x-oauth-basic@gitlab.example.com/group/repo.git），因为会被提交到版本库，极其危险。正确做法是用 Composer 的 auth.json 文件集中管理凭证。

在项目根目录或全局配置路径（COMPOSER_HOME，通常是 ~/.composer/auth.json）放一个 auth.json：

{     "http-basic": {         "gitlab.example.com": {             "username": "your-gitlab-username",             "password": "your-personal-access-token"         }     } }

其中 password 字段填的是你在 Gitlab 后台生成的 PAT（Settings → Access Tokens，勾选 read_repository 即可，不需要 api 权限）。

• 确保 auth.json 权限为 600（chmod 600 auth.json），防止其他用户读取
• 如果 Gitlab 实例启用了双因素认证（2FA），PAT 是唯一可行方式，HTTP Basic 用户密码会失效
• CI 环境中（如 GitLab CI），建议用 CI_JOB_TOKEN 替代 PAT，并在 .gitlab-ci.yml 中动态写入 auth.json

composer.json 里怎么声明 Gitlab 私有包？

不要只靠 repositories 加地址就完事。私有包必须满足 Packagist 协议规范，否则 composer require 会报 Could not find package xxx at any version。

两种可靠写法：

• 如果私有库本身有 composer.json 且含合法 name（如 "name": "myorg/my-package"），直接在主项目的 composer.json 里加 repositories 和 require：

{     "repositories": [         {             "type": "vcs",             "url": "https://gitlab.example.com/myorg/my-package.git"         }     ],     "require": {         "myorg/my-package": "^1.0"     } }

• 如果私有库没有维护 composer.json 或 name 不规范，就得用 package 类型手动定义元数据（适合一次性引入内部工具库）：

{     "repositories": [         {             "type": "package",             "package": {                 "name": "myorg/internal-utils",                 "version": "dev-main",                 "source": {                     "url": "https://gitlab.example.com/myorg/internal-utils.git",                     "type": "git",                     "reference": "main"                 },                 "autoload": { "psr-4": { "MyOrg\": "src/" } }             }         }     ],     "require": {         "myorg/internal-utils": "dev-main"     } }

注意：reference 必须是真实存在的分支名、tag 或 commit hash，不能写 master（Gitlab 默认分支可能是 main）。

为什么 composer update 总是跳过私有库或提示“no matching package found”？

最常被忽略的是 Composer 的包发现机制：它默认只查 Packagist.org，不会自动扫描你配置的私有仓库，除非该包的 name 在 repositories 中被明确声明过，且版本约束能匹配到实际 tag 或分支。

排查顺序：

• 运行 composer config repositories 确认仓库地址已生效，且 URL 能被当前机器 curl -I 或 git ls-remote 访问
• 执行 git ls-remote https://gitlab.example.com/group/repo.git（或 SSH 对应命令），看是否返回 refs 列表；若超时或 403，说明网络或认证有问题
• 检查私有库的 Gitlab 项目设置：Visibility Level 必须是 Internal 或 private，但 Private 要求用户有明确成员权限（不是仅靠 token 就行）
• 如果用了 dev-xxx 这类开发版约束，确保 minimum-stability 设为 dev，否则 Composer 直接忽略

内网环境还容易踩一个坑：Gitlab 实例启用了相对 URL 根路径（如 /gitlab），但 Composer 构造 API 请求时仍按根域名拼地址，导致 404。此时只能改用 SSH 方式，绕过 HTTP 路径解析逻辑。