GitLab私有包无法安装需三步解决：①在composer.json中声明type为vcs并配置完整.git结尾的HTTPS或Git协议URL；②用composer config --global配置具备read_api和read_repository权限的Personal Access Token；③安装时加--stability=dev参数或打符合SemVer的tag。
GitLab 私有包无法安装：先确认 composer.json 里写了什么
Composer 默认不信任 GitLab 这类自建源，直接写 "vendor/package": "dev-main" 肯定报错：Could not find package vendor/package at any version。根本原因是 Composer 根本没去 GitLab 查——它连仓库地址都不知道。
必须显式声明 GitLab 仓库类型和地址，且需匹配项目实际托管位置：
-
"type": "vcs"是必须的，告诉 Composer 这是个版本控制系统源，不是 Packagist -
"url"必须是 Git 协议或 HTTPS 可克隆的地址，比如"https://gitlab.example.com/group/project.git"（注意末尾.git） - 如果 GitLab 启用了子组（subgroup），URL 路径要完整，比如
https://gitlab.example.com/group/subgroup/project.git - 不要把整个 GitLab 实例根域名当仓库地址（如
https://gitlab.example.com），那会 404
认证失败：Token 权限不够或配置位置错了
私有仓库需要认证，但 Composer 不走浏览器登录态，得靠 Personal Access Token 或 Deploy Token。常见错误是 token 权限太低，或者塞错了地方。
Token 至少要带 read_api 和 read_repository 权限；如果是 Deploy Token，确保它绑定了对应项目且未过期。
- 用
composer config --global gitlab-token.gitlab.example.com <your_token></your_token>写入全局配置（推荐） - 别手抖写成
gitlab-token.gitlab.example.com/（结尾斜杠会导致匹配失败） - 如果公司用自签名证书，还要加
"secure-http": false到composer.json的config段，否则 HTTPS 请求直接拒绝 - 执行
composer diagnose能快速验证 token 是否生效（看 “GitLab: OK” 行）
composer require 报 no matching package found：检查分支名和稳定性约束
即使仓库和认证都对了，也可能卡在“找不到包”。这不是网络问题，而是 Composer 对分支/标签的解析规则比你想的严格。
- 默认只认
stable版本，而 GitLab 上的main或develop分支属于dev稳定性，必须显式加-stability=dev参数 - 正确命令是：
composer require vendor/package:dev-main --stability=dev - 如果想让所有 dev 分支都允许，可在
composer.json的minimum-stability设为dev，但不建议——容易污染依赖树 - 更稳妥的做法是给 GitLab 项目打一个符合 SemVer 的 tag（如
v1.0.0），然后 require"vendor/package": "^1.0"，不用动稳定性设置
CI/CD 中自动拉取失败：别漏掉 auth.json 的部署
本地能装不代表 CI 环境也能装。GitLab CI、Jenkins 这些环境没有交互式 token 输入流程，必须预置凭证。
- 不能依赖
composer config --global（CI 容器每次新建，配置不保留） - 应在 CI 流程中生成
auth.json文件，内容形如：{"gitlab-token": {"gitlab.example.com": "xxx"}} - 把这个文件放到项目根目录或
COMPOSER_HOME下，Composer 会自动读取 - 注意权限：CI 中
auth.json文件不能被 commit，要用 CI 变量注入或安全挂载
