repositories字段写错会导致composer完全忽略私有git仓库，只查packagist.org；常见错误包括url缺.git后缀、漏写"type":"vcs"、嵌套位置错误、json语法缺失逗号等。
composer.json里repositories字段写错就完全失效
不写对repositories，Composer 根本不会去你的 Git 仓库查包——它只认 packagist.org 和你明确定义的源。常见错误包括：
• 把 URL 写成网页地址（如 https://gitlab.example.com/group/repo），缺 .git 后缀
• 漏掉 "type": "vcs"，写成 "git"、"package" 或留空
• repositories 嵌套在 config 或 scripts 下，而不是 composer.json 最外层数组
• 多个仓库之间漏逗号，导致 JSON 解析失败，composer install 直接报错
auth.json位置和字段名必须严格匹配域名
90% 的认证失败不是 Token 无效，而是 auth.json 没放对位置、权限不对，或字段名写错——Composer 会静默忽略，不报错也不提示。
• Linux/macOS 路径必须是：~/.composer/auth.json（不是项目根目录）
• Windows 路径必须是：%APPDATA%\Composer\auth.json
• 权限必须设为 600：chmod 600 ~/.composer/auth.json
• 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
适用于以下场景：（1）用户提供 GitHub 仓库 URL 或本地仓库路径，并请求将其转换为其他格式；（2）用户请求导出 GitHub 仓库……
require包名和私有库composer.json里的name必须一字不差
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 安装分两阶段：先查元数据（packages.json），再克隆代码。两者权限要求不同。
• 元数据阶段需要 read_api（用于访问 /api/v4/projects/xxx）
• 克隆阶段需要 read_repository（用于 git clone）
• HTTPS 方式带 token 的旧写法（如 https://token:x-oauth-basic@...）在 Composer 1.10+ 已弃用，凭证必须走 auth.json
• 验证是否真正可达：新开终端执行 git ls-remote -h https://gitlab.example.com/group/repo.git，能列出分支才算通
• 若内网 GitLab 用 HTTP 协议，需在 composer.json 的 config 段加 "secure-http": false，否则直接拒绝连接
