Composer 接入 GitLab 私有仓库需同时满足三条件：composer.json 顶层 repositories 配置正确（type=vcs、URL 含 .git）、auth.json 路径权限及字段严格匹配（~/.composer/auth.json、http-basic、域名精确、username=oauth2、password=glpat-xxx）、require 包名与私有库 composer.json 中 name 字段逐字符一致。
Composer 接入企业 GitLab 私有仓库，不是“配一个 URL 就行”，而是必须同时满足三件事：在 composer.json 顶层写对 repositories、用 auth.json 在正确路径塞进匹配域名的 Token、require 的包名和私有库 composer.json 中的 name 字段逐字符一致。漏掉任一环，composer install 都不会报错提示“你少配了”，而是静默跳过或卡在 Could not find package。
repositories 必须是顶层字段且 type 为 vcs
Composer 不会扫描你的浏览器历史或 GitLab 页面链接，它只认你明明白白写在 composer.json 最外层的 repositories 数组。嵌套在 config、scripts 或其他任意位置，等于没写。
-
type必须是"vcs"—— 写成"package"、"git"、"path"或直接省略，Composer 都当它不存在 -
url必须是可直接git clone的地址，结尾带.git（如"https://gitlab.example.com:8443/team/utils.git"），缺后缀会触发No valid composer.json was found - 如果 GitLab 启用了子路径（比如部署在
/gitlab下），URL 中也得带上，否则 API 请求失败；写成网页地址（如https://gitlab.example.com/team/utils）也无效 - HTTPS 和 SSH 都支持，但 CI 环境通常禁用 SSH，推荐统一用 HTTPS + Token
auth.json 路径、字段名、域名必须严丝合缝
填错任意一项，composer update -v 日志里就看不到 Authorization: Bearer glpat- 请求头，composer config --global --list | grep gitlab 也查不到对应配置，表现就是反复弹密码框或直接 401。
- Linux/macOS 路径只能是
~/.composer/auth.json（不是~/.config/composer/auth.json），权限必须设为600：chmod 600 ~/.composer/auth.json - Windows 路径是
%APPDATA%\Composer\auth.json - 字段名必须是
http-basic（不是gitlab-token、token或access_token）——这是 GitLab 官方文档和 Composer 2.9+ 实际验证有效的唯一结构 - 域名 key 必须和
repositories.url的 host 完全一致：比如 URL 是https://gitlab.example.com:8443/team/pkg.git，key 就得是"gitlab.example.com:8443"；多一个斜杠、少一个端口、带协议（https://）都不行 -
username填"oauth2"（GitLab 约定值，不是你的账号名），password填完整的 PAT（"glpat-xxxxxxxxxxxxxxxxxxxx"），不能是 token 名或密码
require 包名必须与私有库 name 字段完全一致
Composer 不按 Git 路径、URL 或文件夹名匹配，只严格比对私有库根目录下 composer.json 中的 name 字段。差一个字母、大小写、斜杠方向，都会失败。
- 假设私有库
composer.json里写的是{"name": "acme/utils"}，主项目require就必须是"acme/utils": "dev-main" - 不能写成
"Acme/utils"、"acme-utils"、"acme/utils-dev"，也不能省略 vendor 段 - 分支必须用
dev-前缀（如dev-main、dev-develop）；写"main"或"*"会被当成模糊约束，去 Packagist 查，查不到就报错 - Tag 版本（如
v1.0.0）可直接用，但composer.json里的version字段对 VCS 仓库完全无效，Composer 只认 Git 的 tag 和分支名
Token 权限和网络访问常被忽略的硬性条件
即使 auth.json 格式全对、路径权限也没问题，Token 缺权限或用户无项目访问权，依然会在不同阶段失败：要么卡在 API 查询，要么卡在 git clone --mirror。
- Personal Access Token 必须同时勾选
read_api和read_repository—— 只开read_api会报403 Forbidden on /api/v4/projects/；只开read_repository会报Failed to download - 该 Token 所属用户，对目标 GitLab 项目必须有
Reporter及以上权限（Guest不够） - CI 场景更推荐用 Deploy Token（权限更细、不可用于 Web UI），但注意 Deploy Token 不支持 API 调用，第一步就卡死，所以不适用于需要元数据查询的场景
- 执行
composer update --lock后，务必检查composer.lock是否真写入了该包的source信息（含type、url、reference），避免缓存误导
