<p>Composer 要识别 GitLab 私有仓库，必须在 composer.json 中显式配置 type: "vcs" 仓库，HTTPS 方式需带 oauth2:TOKEN 前缀且 URL 含 .git 后缀，SSH 方式需配置密钥；私有包依赖须在 repositories 中声明且置于 packagist 之前，包名与仓库内 name 字段严格一致，分支需用 dev- 前缀；凭证失效、协议不匹配或证书问题会导致 401 或克隆失败。</p>
Gitlab 私有仓库怎么让 Composer 认出来
Composer 默认不信任私有 Gitlab 仓库，直接写 git@gitlab.example.com:group/project.git 或 HTTPS 地址会报 Could not fetch https://gitlab.example.com/group/project.git 或 Failed to clone git@gitlab.example.com:group/project.git。根本原因是认证缺失 + 协议未显式声明。
必须在 composer.json 里显式注册仓库类型和地址，并确保凭证可用：
- 用
"type": "vcs"声明这是个版本控制系统仓库（不是包仓库） - HTTPS 地址要带完整域名和路径，不能省略
.git后缀（Gitlab 15+ 强制要求） - SSH 方式需提前配置好本地 SSH key 并添加到 Gitlab 账户，且
composer.json中必须用git@gitlab...格式，不能混用 HTTPS - 如果 Gitlab 开启了双因素认证（2FA），HTTPS 方式必须用 Personal Access Token 替代密码，且 Token 需勾选
read_repository权限
composer.json 里怎么写私有包依赖
不能只靠 require 写包名就完事——Composer 不知道去哪找这个包。必须同时配 repositories，且顺序有影响：私有仓库要放在官方 packagist 之前，否则会被跳过。
示例（HTTPS + Token）：
{
"repositories": [
{
"type": "vcs",
"url": "https://oauth2:YOUR_TOKEN@gitlab.example.com/group/internal-package.git"
}
],
"require": {
"group/internal-package": "dev-main"
}
}
注意点：
-
url中的oauth2:是 Gitlab 的固定前缀，后面紧跟 Token，不能加空格 - 包名
group/internal-package必须和仓库里composer.json中的"name"完全一致（包括大小写） - 分支名如
dev-main、dev-develop不能写成main—— Composer 默认只识别dev-前缀的开发分支 - 如果私有包本身也依赖其他私有包，所有上游仓库都得列在
repositories里，不能漏
为什么 composer install 时卡住或报 401
最常见原因是凭证失效或协议不匹配。不是网络问题，是认证链断了。
排查优先级：
- 运行
composer config -g github-oauth.gitlab.example.com看是否已全局配置 Token（Composer 会优先读这里） - 检查 Gitlab Token 是否过期，或权限是否被回收（尤其是
read_repository） - 执行
git ls-remote https://oauth2:TOKEN@gitlab.example.com/group/pkg.git手动测试能否拉取 refs —— 这步通了，Composer 才可能通 - 如果用 SSH，确认
ssh -T git@gitlab.example.com能成功返回欢迎信息；若失败，别指望 Composer 能走通 - Gitlab 自托管实例若用了自签名证书，需在
php.ini中设置openssl.cafile，否则 HTTPS 克隆必然 401 或 SSL handshake failed
私有包更新慢、经常重拉整个仓库
Composer 默认对 vcs 类型仓库使用 git clone，而不是 git fetch，导致每次 composer update 都可能重新克隆，尤其大仓库时明显卡顿。
优化方式有限但有效：
- 在项目根目录运行
composer config --global cache-vcs true（Composer 2.2+ 默认开启，老版本需手动开） - 确保私有仓库的
composer.json中定义了明确的"version"或稳定分支（如1.0.0），避免总指向dev-main这类“永远不稳定”的引用 - 不要在
repositories里反复添加同一仓库多个 URL（比如又写 HTTPS 又写 SSH），Composer 会去重但增加解析开销 - 如果内部有镜像或缓存代理（如 Gitlab CI 的
cache），优先考虑把常用私有包打成 tarball 发布到私有 Satis/SatisPress 服务，彻底绕开 vcs 拉取瓶颈
真正麻烦的从来不是配置语法，而是 Gitlab 实例的网络策略、Token 权限粒度、以及私有包自身是否规范声明了 name/version —— 这三处任一出问题，Composer 都只会冷冷抛个 401 或 “could not find package”。
