有效写法是：repositories必须为顶层数组，每项显式声明"type": "vcs"，url须为可git clone地址（如https://gitlab.example.com/acme/utils.git），且与auth.json中域名key、包名name严格一致。
composer.json 里 repositories 怎么写才有效
不写对 repositories，Composer 根本不会去你的 GitLab 查包——它只认 packagist.org 和你明确定义的源。常见错误是把 URL 写成网页地址、漏掉 "type": "vcs"、或 URL 缺 .git 后缀。
-
type必须是"vcs"，不是"git"、"package"或留空；写错就静默忽略 -
url必须是可直接git clone的地址：
SSH 格式如git@gitlab.example.com:acme/utils.git，HTTPS 格式如https://gitlab.example.com/acme/utils.git - 不能写成
https://gitlab.example.com/acme/utils（缺.git），否则报No valid composer.json was found -
repositories必须在composer.json最外层，不能嵌套在config或scripts下
auth.json 放哪、怎么写才被读取
90% 的认证失败不是 Token 无效，而是 auth.json 没放对位置、权限不对，或字段名写错——Composer 会静默跳过，不报错也不提示。
- 路径只能是：
Linux/macOS：~/.composer/auth.json（不是项目根目录）
Windows：%APPDATA%\Composer\auth.json - 权限必须是
600：运行chmod 600 ~/.composer/auth.json，否则 Composer 直接忽略 - GitLab 必须用
http-basic字段，结构为：{"http-basic": {"gitlab.example.com": {"username": "oauth2", "password": "glpat-xxx"}}} - 域名 key 必须和
repositories.url中的 host 完全一致（不含协议、路径、端口），例如gitlab.example.com:8080和gitlab.example.com是两个独立 key
require 包名为什么总报 “Could not find package”
Composer 不按 Git 路径匹配，只严格比对私有库 composer.json 里的 name 字段。差一个字符，就找不到。
- 假设私有库根目录
composer.json里写的是{"name": "acme/utils"}，那主项目require就必须写"acme/utils": "dev-main" - 不能写成
"Acme/utils"、"acme-utils"、"acme/utils-dev"，也不能省略 vendor 段 - 分支必须加
dev-前缀："dev-main"可行，"main"或"*"会被当成模糊约束，去 Packagist 查，查不到就失败 - 如果私有库没打任何 tag，唯一可用版本就是
dev-main（或dev-master，取决于默认分支名）
HTTPS 连 GitLab 时 Token 权限和字段容易踩坑
GitLab 的 Personal Access Token 不是“开了 API 就能用”，Composer 安装分两步走，缺一不可。
- Token 必须同时勾选
read_api和read_repository：
只开read_api→ 报403 Forbidden on /api/v4/projects/
只开read_repository→ 报Failed to download git clone --mirror -
username字段填oauth2（GitLab 约定，不是你的账号名），password填完整 PAT（glpat-xxx），不能是 token 名或密码 - Deploy Token、CI_JOB_TOKEN、OAuth App Token 全部不支持 API 调用，第一步就卡死
- 该 Token 所属用户还必须对目标项目有
Reporter及以上权限
name 和 require 必须逐字符一致、Token 权限必须双开——任一环节差一点，Composer 都不报错，只是安静地跳过。
