私有 GitLab 仓库不能走中文镜像，因镜像仅缓存 packagist.org 公开包，对私有包无感知；强行将私有源设为 type: composer 并指向镜像地址会导致 404 或“Could not find package”错误。
私有 GitLab 仓库不能走中文镜像，强行配置会失败
Composer 中文镜像（如阿里云 https://mirrors.aliyun.com/composer/）只缓存 packagist.org 公开包的元数据和 ZIP 包，对 GitLab 上的 internal/auth-sdk 这类私有包完全无感知。你一旦在 repositories 里把私有源写成 "type": "composer" 并指向镜像地址，Composer 就会尝试从镜像拉取不存在的 packages.json，结果必然是 404 或 Could not find package。
常见错误操作：
- 把
"url": "https://gitlab.example.com"改成"url": "https://mirrors.aliyun.com/composer/"，还设"type": "composer" - 全局禁用官方源：
"packagist.org": false—— 这只会切断 fallback，不加速私有源，也不解决认证 - 误以为加了镜像后
composer require internal/auth-sdk就能自动走 CDN，实际仍卡在Cloning into ...
GitLab 私有包必须用 vcs 类型 + auth.json 认证
让 Composer 正确识别并拉取 GitLab 私有仓库，两个动作缺一不可：声明为 vcs 类型仓库，并在 auth.json 中注入 gitlab-token。二者不共用同一套配置机制，不能互相替代。
关键实操点：
-
composer.json的repositories必须是数组，每项"type": "vcs"，"url"指向带.git后缀的 HTTPS 地址（如https://gitlab.example.com/myorg/pkg.git），不是网页 URL -
auth.json必须放在用户主目录：~/.composer/auth.json（Linux/macOS）或%APPDATA%\Composer\auth.json（Windows），内容格式为：{ "gitlab-token": { "gitlab.example.com": "glpat-xxxxxxxx" } } - Token 权限必须同时勾选
read_api（查项目元数据）和read_repository（克隆代码），缺一不可 - 不要用
http-basic配私有 GitLab 源——它只对type: composer源生效，对vcs无效
混合源场景下，顺序和开关控制决定解析是否出错
当项目同时 require monolog/monolog（公共包）和 myorg/internal-sdk（私有包）时，Composer 解析依赖树的顺序和源开关设置直接影响成功率。
安全配置方式：
- 把私有源声明放在
repositories数组最前面，但不要删掉或禁用packagist.org——保留默认源作为 fallback，避免因私有源临时不可用导致整个 install 失败 - 禁用默认源应使用顶层
"packagist": false（注意没有.org），而非"packagist.org": false；后者只影响默认源，不阻止其他type: composer源干扰解析 - 如果私有源是 Satis 构建的，确保其
satis.json明确列出了所有允许发布的包名；未声明的包即使存在 Git 仓库，也不会出现在packages.json中，Composer 就找不到 - 不要在
repositories里混用type: vcs和type: composer指向同一域名——容易触发元数据冲突，导致Resolving dependencies卡死
部署时镜像与私有源配置必须“打包交付”，不能依赖全局设置
私有化交付失败，70% 是因为镜像配置没随制品一起部署：客户现场以 www 用户运行脚本，而你用 sudo composer config -g 写进了 /root/.composer/config.json，进程根本读不到；更隐蔽的是，CI 构建机、Docker 容器、宝塔后台用户各不相同，全局配置无法复用。
可靠做法：
- 把镜像配置直接写进项目根目录的
composer.json：composer config repo.packagist composer https://mirrors.aliyun.com/composer/（注意末尾斜杠不能少） - 执行该命令前，确认
repositories字段已是对象{}而非数组[]，否则会覆盖已有私有源 - 改完立刻删掉
vendor/和composer.lock，否则旧 lock 文件里的哈希仍指向原源，校验失败 - 内网离线环境验证镜像可用性：运行
curl -I https://mirrors.aliyun.com/composer/packages.json，响应头必须含Content-Type: application/json，否则 Composer 会静默跳过该 URL
真正难处理的不是怎么配，而是如何让配置在任意用户、任意环境、任意构建上下文中都保持一致——这要求你放弃“教客户自己配”的思路，把配置当作代码的一部分，和业务逻辑同生命周期管理。
