GitLab不能直接作为Composer私有仓库，需配置vcs类型源并正确认证；必须在项目根目录放含合法name的composer.json，URL须带.git后缀，auth.json需置于用户主目录且权限600。
不能直接用 Composer 搭建私有 GitLab 包仓库——GitLab 本身不是 Composer 仓库，它只是 Git 托管服务；你要做的是让 Composer 能从你的 GitLab 项目里拉取包，这靠配置 vcs 类型源 + 正确认证实现，不是搭“仓库”。
为什么不能把 GitLab 当作 Packagist 替代品？
GitLab 不提供 Composer 的元数据索引服务（比如包列表、版本映射、依赖解析），它只托管 Git 仓库。Composer 默认只信任 packagist.org，对 GitLab 上的项目一无所知，除非你明确告诉它：“这个 Git URL 是个合法的 PHP 包源，且我有权限访问”。type: "vcs" 就是这个“告知”动作，它触发的是 git clone 流程，而不是远程索引查询。
- 误以为在 GitLab 创建项目就自动变成 Composer 包 → 错，必须在项目根目录放
composer.json，且含合法name字段 - 试图在
repositories里写type: "package"手动定义元数据 → 复杂易错，仅适用于无 Git 访问权限或需固定某次提交的极端场景 - 把 GitLab 网页地址（如
https://gitlab.example.com/group/pkg）当仓库 URL → 必须带.git后缀，否则composer install报No valid composer.json was found
必须配 auth.json，不能只改 composer.json
HTTPS 协议下，GitLab 要求每次 git clone 都带凭证。Composer 不会读 composer.json 里的 token 字段，它只认全局 ~/.composer/auth.json（Linux/macOS）或 %APPDATA%\Composer\auth.json（Windows），且权限必须是 600。
-
auth.json必须放在用户主目录下，不能放项目里，也不能用COMPOSER_AUTH环境变量临时覆盖（GitLab 的 Personal Access Token 不支持 Bearer header 自动注入） - 内容格式严格：
{"http-basic": {"gitlab.example.com": {"username": "gitlab-ci-token", "password": "glpat-xxxxxxxxxxxxxxxxxxxx"}}——username和password全小写，不能写成Username或Token - Token 权限至少为
read_repository；CI 场景推荐用 Deploy Token（更细粒度、不可用于 Web UI）
composer.json 里 repositories 怎么写才生效？
只加 require 行没用，Composer 根本不会去查那个 GitLab 地址。必须在顶层 repositories 数组里声明，并确保 url 可被 git clone 直接执行。
- 正确示例：
{"type": "vcs", "url": "https://gitlab.example.com/myorg/my-private-package.git"}——type必须是vcs，url必须以.git结尾 - 多个私有库并列写，顺序无关：
"repositories": [{...}, {...}]，不能嵌套或包在其他字段里 -
require中的包名（如"myorg/my-private-package"）必须和目标仓库composer.json里的name字段完全一致，大小写敏感 - 版本约束必须显式：私有库通常没打 stable tag，得用
"dev-main"或"1.2.x-dev"，否则受minimum-stability默认值（stable）拦截
SSH 方式比 HTTPS 更稳，但要注意密钥加载
如果团队已统一配好 SSH 密钥，用 git@gitlab.example.com:group/repo.git 可绕过 token 管理，但容易卡在连接环节。
- 确保
~/.ssh/id_rsa存在且权限为600，GitLab 账户已绑定对应公钥 - 首次连接目标主机时，
ssh会交互提示是否确认 fingerprint，CI 环境需提前运行ssh-keyscan gitlab.example.com >> ~/.ssh/known_hosts，否则composer install卡住 - 别漏掉
~/.ssh/config里的 Host 别名配置（如Host gitlab.example.com\n User git），否则git clone可能用错用户名
最常被忽略的是分支名大小写和 composer.json 中 name 字段的精确匹配——差一个字母或斜杠，composer require 就静默失败，连错误提示都不给。先 git clone 手动试一遍 URL 和认证，再让 Composer 上。
