Composer私有仓库必须放在repositories数组最前面，因为其匹配机制是线性短路：从上到下逐个请求，首个返回200+合法JSON的源即被锁定，后续源彻底跳过；若私有源靠后且镜像先返回404，Composer会切至packagist.org导致私有包找不到。
Composer私有仓库为什么必须放在repositories数组最前面？
因为Composer对repositories数组是**线性短路匹配**：从上到下逐个发起HTTP请求，只要某个源返回200 OK且响应体含合法JSON（哪怕不含你要的包），就立刻锁定该源，后续所有源彻底不查。这不是fallback，是硬性跳过。
常见错误现象是：私有包myorg/utils明明已发布到内部GitLab仓库，但composer require myorg/utils却报错“Package not found”，原因往往是阿里云镜像排在了私有源前面——它对myorg/utils返回404，Composer就切回packagist.org，而官方源当然没有这个包。
- 私有
type: "composer"源（如Nexus、Satis）必须置于repositories数组首位 -
type: "vcs"源（如"url": "https://gitlab.example.com/myorg/utils"）不参与全局元数据匹配，只在显式composer require时触发，所以它顺序无关紧要 - 验证当前生效顺序：运行
composer config repositories，输出应以你的私有源开头
禁用packagist.org不是可选项，而是强制动作
默认情况下，Composer会把https://packagist.org当作隐式兜底源。哪怕你把私有源写在第一位，只要它对某个包返回404（比如新包刚推上去、镜像同步延迟），Composer就立刻切回官方源——你根本意识不到私有源被绕过了。
唯一可靠禁用方式是：在repositories数组**末尾**添加一个独立对象{"packagist.org": false}。注意：
– 键名必须精确为packagist.org（不是packagist或packagist.com）
– 它必须是数组里的一个单独元素，不能嵌套在其他对象里
– 不能写成{"type": "composer", "url": "https://packagist.org/"}这种形式
- 执行
composer config repositories后，输出中不应出现https://repo.packagist.org，且应明确看到"packagist.org": false - 修改后必须删掉
composer.lock和vendor/目录，再运行composer install，否则旧锁文件仍会拉取官方源的包 - 项目级
composer.json中的repositories会完全屏蔽全局配置（~/.composer/config.json），别指望全局设置能覆盖项目私有源
私有仓库返回什么，才真正算“被识别”？
Composer只认两类响应：
-
200 + 可解析JSON：即使JSON里
packages为空，也算“命中”，后续源全跳过 - 404：唯一触发下一个源的响应码；DNS失败、502、500、超时（默认30秒）一律报错退出，不会继续试下一个
这意味着：如果你的私有仓库Nginx配置错误，导致对/packages.json返回502，Composer不会尝试阿里云镜像，而是直接中断并报错Could not fetch packages.json。你得先确保私有源本身能稳定返回200或404，而不是靠堆砌多个源来“提高可用性”。
生产环境加第二个镜像源，只在一种场景有用：第一个镜像明确返回404，且你确认该包确实在第二个镜像里（比如新包刚发布，私有源同步慢于阿里云）。
为什么vendor目录不能改，连带影响私有包加载？
vendor/是Composer硬编码路径，不是配置项。哪怕你在composer.json里写"config": {"vendor-dir": "libs"}，也只在vendor/目录不存在时生效；一旦已有vendor/，这个配置就被彻底无视。
更关键的是，所有生态工具都绑定vendor/：
- IDE、PHPStan、Psalm默认扫描
vendor/autoload.php生成符号索引 -
vendor/bin/下的命令（如phpunit）内部写死了相对路径 - 私有包的自动加载映射（
autoload_psr4.php）也基于vendor/下的真实路径生成
改了vendor路径，90%的工具链立刻断裂，错误信息往往不提示“路径不对”，而是报Class not found或Command not found——这是最容易被忽略的底层耦合点。
