GitLab私有包需配置auth.json和repositories才能被Composer识别：auth.json放~/.composer/下并设chmod 600，含gitlab-token；composer.json中repositories须用type:"vcs"及带.git后缀的Git URL。
GitLab 私有仓库怎么让 Composer 认出来
Composer 默认只认 packagist.org，想拉你公司 GitLab 上的 myorg/my-private-package，得先告诉它“这个地址可信、能走 Git 协议、有权限”。关键不是改 composer.json，而是配 auth.json 和加 repositories 声明。
常见错误现象：Could not fetch https://gitlab.example.com/api/v4/projects/xxx, will retry: curl error 22 while downloading，或者直接提示 Package myorg/my-private-package not found——多半是没声明仓库，或认证失败。
- GitLab 实例必须开启 API 访问（默认开），且你的 Personal Access Token 至少带
read_api和read_repository权限 -
auth.json必须放在用户主目录下（~/.composer/auth.json），不能放项目里，也不能用COMPOSER_AUTH环境变量临时覆盖（GitLab 的 token 不支持 bearer header 自动注入） - Token 别硬编码进
composer.json，也别提交到 Git ——auth.json本身应设chmod 600
示例 auth.json：
{
"gitlab-token": {
"gitlab.example.com": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
}
composer.json 里怎么写 repositories 才生效
GitLab 项目不能靠 Packagist 自动索引，必须显式声明为 vcs 类型仓库，并指向 Git URL（不是网页 URL）。路径必须是可 git clone 的地址，比如 https://gitlab.example.com/myorg/my-private-package.git，结尾的 .git 不能省。
容易踩的坑：type: "package" 是错的，那是给手动定义元数据用的；type: "vcs" 才能让 Composer 自动解析 composer.json 并支持版本约束。
- 如果项目用了子组（如
myorg/team-a/my-package），URL 里的路径要严格匹配 GitLab 的 namespace，大小写敏感 - 不要写成
https://gitlab.example.com/myorg/my-private-package（缺.git），否则 Composer 会报No valid composer.json was found - 多个私有仓库要并列写在
repositories数组里，顺序无关，但不能嵌套
示例 composer.json 片段：
{
"repositories": [
{
"type": "vcs",
"url": "https://gitlab.example.com/myorg/my-private-package.git"
}
],
"require": {
"myorg/my-private-package": "^1.2"
}
}
为什么 require 后还是拉不下来？检查这三处
即使配置全对，拉取失败往往卡在协议、域名解析或 token 权限上。Composer 不会明确告诉你哪步断了，得逐层验证。
- 手动执行
git clone https://gitlab.example.com/myorg/my-private-package.git—— 如果失败，说明网络、证书或 token 没生效；成功则 Composer 应该也能拉 - 运行
composer config --global --list | grep -i gitlab，确认没残留旧的gitlab-domains配置（老版本 Composer 用过这个，新版已弃用） - 加
-vvv参数重试：composer require myorg/my-private-package -vvv，重点看日志里是否出现Using GitLab API token for gitlab.example.com，没有就说明auth.json没被读到或域名不匹配
私有包有 dev-main 但 composer install 不识别
GitLab 默认分支名是 main，但 Composer 要求 VCS 包的开发分支必须叫 dev-main（不是 main 或 dev-master）。如果你的仓库只有 main 分支，Composer 会跳过它，除非你显式指定 "dev-main as 1.0.x-dev" 这类别名。
根本解法是让 GitLab 项目启用 composer.json 里的 "minimum-stability": "dev"，并确保 "prefer-stable": true 不会意外过滤掉 dev-main。
- 最稳的做法：在私有包的
composer.json里加"branch-alias": {"main": "1.0.x-dev"}，然后 require 时写"myorg/my-private-package": "dev-main" - 别依赖
dev-master—— GitLab 新建项目默认不用master，强行切分支名反而增加维护成本 - 如果团队用 protected branches，确保
main（或你用的默认分支）没被设为“不允许合并”，否则 Composer 的 fork + clone 流程可能中断
GitLab 的私有包集成，难点不在语法，而在权限链路是否完整：token → auth.json 路径和域名 → vcs URL 格式 → 分支命名约定。漏掉任意一环，Composer 就静默失败，不会报具体原因。
