必须禁用默认 Packagist 源，否则 Composer 会优先从 packagist.org 查包并停止搜索，导致私有仓库被跳过；需执行 composer config -g packagist false 或在 composer.json 中设 {"packagist.org": false}，并确保 repositories 为数组、补上镜像源（如阿里云）、CI 中用环境变量安全控制。
必须禁用默认 Packagist 源，否则 Composer 会优先从 packagist.org 查包，私有仓库即使配置正确也大概率被跳过——这不是“备选”，而是“竞争失败”。
为什么 composer config -g packagist false 是必要操作
Composer 默认行为是：先查 packagist.org，命中即停，不继续扫描 repositories 数组里的其他源。哪怕你已把 GitLab 私有仓库写进 repositories，只要 packagist.org 上没有同名包（或版本不匹配），它也不会 fallback 到你的私有源——它直接报 Could not find package。
禁用全局默认源后，Composer 才会老老实实按 repositories 数组顺序逐个查找，你的私有仓库才有机会被真正“看见”。
-
composer config -g packagist false影响所有项目，适合开发机统一管控 - 若只想关掉当前项目，默认源，应在
composer.json的repositories里显式加一条：{"packagist.org": false} - 注意：禁用后，所有公开包（如
monolog/monolog）也必须通过镜像源或自定义 composer type 仓库提供，否则composer install会失败
repositories 必须是数组，不是对象
很多人用 composer config repositories.my-gitlab vcs https://... 命令生成配置，结果发现私有包还是拉不到——根本原因是该命令默认写成对象格式（"repositories": {"my-gitlab": {...}}），而 Composer 只认索引数组（"repositories": [{...}, {...}]）。
PHP 解析 JSON 对象时键名无序，Composer 实际只取最后一个仓库项，前面全丢弃。静默失效，毫无提示。
- 手动编辑
composer.json时，务必确认repositories是方括号[]包裹的数组 - 用命令行添加时，推荐先清空再重建：
composer config --unset repositories && composer config repositories.[0] vcs https://gitlab.example.com/group/pkg.git - 检查是否生效：
composer config repositories输出应为 JSON 数组，而非键值对对象
禁用 packagist 后，如何保留常用公开包
直接 packagist false 会导致 symfony/console 这类基础包无法安装。你需要显式补一个国内镜像源替代：
- 加阿里云镜像：
composer config repositories.packagist composer https://mirrors.aliyun.com/composer/ - 确保这条配置排在私有仓库之前（顺序决定优先级），例如：
[{"type":"composer","url":"https://mirrors.aliyun.com/composer/"},{"type":"vcs","url":"https://gitlab.example.com/group/my-pkg.git"}] - 镜像源的
type必须是composer，不能写vcs或漏掉 - 如果用的是私有 Packagist 服务（如 Satis），URL 必须是其 API 地址（如
https://packages.mycompany.com），不是网页首页
CI 环境下禁用 packagist 的安全写法
在 GitLab CI 或 GitHub Actions 中，不能依赖本地 auth.json 或全局 config，需用环境变量动态控制：
- 设环境变量：
COMPOSER_DISABLE_PACKAGIST=1（等价于全局packagist false） - 同时用
COMPOSER_REPO_PACKAGIST_URL=https://mirrors.aliyun.com/composer/补镜像 - 私有仓库用
COMPOSER_REPO_MY_PRIVATE_REPO_URL=https://glpat-xxx@gitlab.example.com/group/pkg.git，但更推荐走auth.json注入（避免 token 泄露） - CI 脚本中执行前先验证：
composer config --global --list | grep -i packagist，确认已关闭
最关键的细节：禁用 packagist 不是“开关一开就完事”，它改变了整个包发现链路；你得同步补上镜像源、校验 repositories 结构、并在 CI 中隔离凭证——少一步，composer install 就卡在 Could not find package。
