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 路径解析逻辑。
