<p>结论：不是配个 URL 就能拉代码，必须同时满足三件事——composer.json 顶层 repositories 写对、auth.json 在正确路径填对域名和 glpat- Token、require 的包名和私有库 composer.json 中的 name 字段逐字符一致。</p>
直接说结论：不是配个 URL 就能拉代码，必须同时满足三件事——composer.json 顶层 repositories 写对、auth.json 在正确路径填对域名和 glpat- Token、require 的包名和私有库 composer.json 中的 name 字段逐字符一致。漏一个，composer install 就静默跳过，不报错也不提示。
repositories 必须是顶层字段且 type 为 vcs
Composer 只读你当前项目根目录下 composer.json 最外层的 repositories 数组，嵌套在 config、scripts 或任何其他位置都无效。
-
type必须写"vcs"—— 写成"git"、"package"、"gitlab"或留空，Composer 都当它不存在 -
url必须是可直接git clone的地址，结尾带.git（例如https://gitlab.example.com/team/utils.git）；缺后缀会触发No valid composer.json was found - 如果 GitLab 部署在子路径（如
/gitlab），URL 里也得带上（https://gitlab.example.com/gitlab/team/utils.git），否则 API 请求失败 - 别用网页地址（如
https://gitlab.example.com/team/utils）——它不是 Git 地址，Composer 解析不了
auth.json 路径、字段、域名必须严丝合缝
认证信息必须存在 ~/.composer/auth.json（Linux/macOS）或 %APPDATA%\Composer\auth.json（Windows），且内容格式不能错。
- 字段名必须是
http-basic（GitLab 不认gitlab-oauth或gitlab-token） -
username必须是"oauth2"（不是"git"、"root"或留空） -
password必须是完整 Token，以glpat-开头（如"glpat-AbCdEfGhIjKlMnOpQrSt"） - 域名必须精确匹配——
"gitlab.example.com"和"https://gitlab.example.com"是两个不同域名，后者会失效 - 验证是否生效：
composer install -vvv日志中应出现Authorization: Bearer glpat-；若没看到，说明认证没走通
require 的包名必须和私有库 composer.json 中 name 逐字符一致
Composer 不做大小写转换、不自动补斜杠、不忽略空格——错一个字符就等于没这个包。
- 私有库自己的
composer.json里写的是"name": "myorg/utils"，你就得在 require 中写"myorg/utils": "dev-main" - 写成
"MyOrg/Utils"、"myorg-utils"、"myorg/utils "（末尾空格）都会失败 - 分支名也要严格对应：
"dev-main"只匹配叫main的分支；不确定时先跑composer show myorg/utils --all看实际有哪些版本可用 - 私有库根目录下必须有合法
composer.json，且其中name字段存在、格式正确（两段式，不含协议或路径）
HTTPS vs SSH：CI 环境别碰 SSH
本地开发用 SSH 更省心（ssh-add -l 能列出密钥、公钥已加到 GitLab 即可），但 CI/CD 流水线几乎都禁用 SSH agent，推荐统一走 HTTPS + Token。
- SSH 方式需确保执行
composer install的用户能读取~/.ssh/id_rsa，且ssh -T git@gitlab.example.com成功 - HTTPS 方式在 CI 中只需把
glpat-Token 注入环境变量，再通过auth.json注入即可，无需管理密钥生命周期 - 别在
url里拼接凭据（如https://oauth2:glpat-xxx@gitlab.example.com/...）——不安全，且 Composer 1.10+ 已弃用 - 如果 GitLab 启用了自签名证书，CI 中还需额外配置
composer config -g secure-http false（仅限内网可信环境）
最常被忽略的点是：repositories 加了之后，Composer 默认关闭 packagist.org 源。如果你没显式加回 {"type": "composer", "url": "https://packagist.org", "packagist": false}，那 composer require monolog/monolog 这类公共包也会找不到——不是权限问题，是源被关了。
