Composer中文镜像与私有GitLab仓库的配合使用（高阶教程）-composer-PHP中文网

私有 gitlab 仓库不能走中文镜像，因镜像仅缓存 packagist.org 公开包，对私有包无感知；强行将私有源设为 type: composer 并指向镜像地址会导致 404 或“could not find package”错误。

composer中文镜像与私有gitlab仓库的配合使用（高阶教程）

私有 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 解析依赖树的顺序和源开关设置直接影响成功率。

Git Deployer

将静态站点内容推送至 GitHub Pages 仓库。克隆、复制文件、带时间戳提交并强制推送。用于更新 GitHub Pages 站点和部署。

下载

安全配置方式：

把私有源声明放在 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