需在composer.json的repositories数组中按优先级顺序配置多个源，type为composer或git，禁用默认packagist需显式设{"packagist.org": false}；私有包未命中主因是包名未被源声明支持或packages.json缺失对应条目。
composer.json 里怎么加多个仓库源
Composer 默认只认 packagist.org，要加私有源或镜像源，必须手动改 composer.json 的 repositories 字段。它是个数组，顺序很重要——Composer 会从上到下查包，找到第一个匹配的就停，后面的同名包直接跳过。
常见错误是把镜像源（比如阿里云）放在最后，结果还是走 slow 的官方源；或者两个源都配了 packagist 类型，导致冲突报错 Cannot use package packagist as it is used as a repository。
- 用
composer.json根级repositories数组，每个对象至少含type和url - 优先用
composer类型（支持完整 Composer 协议），别用package类型手工写包定义（维护成本高） - 如果同时用 packagist 镜像 + 私有 GitLab 源，镜像必须设为
{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"}，再额外加一个git类型源指向你的https://gitlab.example.com/api/v4/groups/my-group/-/composer - 不要在
repositories里重复声明packagist.org，默认已存在；想禁用它，得显式加{"packagist.org": false}
为什么 require 时没走私有源
最常踩的坑：包名没对上。Composer 查源不是按“有没有这个域名”，而是严格比对 vendor/name 是否被某个源声明支持。私有源如果没在 packages 字段里列出具体包，或没配 composer.json 的 provider-includes，Composer 就当它不存在。
典型现象：composer require myorg/my-private-package 报错 Could not find package myorg/my-private-package，但 curl -I https://your-private-repo/packages.json 能返回 200。
- 确认私有源的
packages.json里真有"myorg/my-private-package"条目（不是只在某个子路径下） - 私有源如果是基于 Satis 或 Private Packagist，检查是否开启了
providers索引生成；自建 Nginx + static files 的话，确保packages.json是顶层文件，且包含完整providers块 - 运行
composer config repositories看当前生效的源列表，注意有没有被config.json全局配置覆盖 - 临时加
-vvv跑composer require，看日志里实际请求了哪个 URL，定位卡在哪一步
全局配置 vs 项目配置的优先级
项目根目录的 composer.json 里的 repositories 永远优先于全局 ~/.composer/config.json。但很多人误以为配一次全局就一劳永逸，结果新项目里啥都没写，死活拉不到私有包。
另一个陷阱是 CI 环境：Docker 构建时没挂载全局配置，或用了干净的 --no-cache，导致私有源完全不可见。
- 团队协作项目，
repositories必须写进项目composer.json，别依赖开发者本地全局配置 - 全局配置只适合个人开发机上的镜像加速（如阿里云、腾讯云），且建议用
composer config -g repos.packagist composer https://mirrors.tencent.com/composer/这种命令式写法，避免手写 JSON 出错 - CI 中若需私有源，要么在
composer.json里明确定义，要么用composer config --global在构建步骤里动态写入（注意权限和缓存问题）
require-dev 依赖不走私有源？
不会。Composer 对 require 和 require-dev 一视同仁，都走同一套 repositories 查找逻辑。真正影响源选择的是包名匹配，不是它在哪个字段里。
但有个隐藏条件：如果私有源只提供稳定版（"minimum-stability": "stable"），而你在 require-dev 里写了 "myorg/tool": "dev-main"，那即使源存在，也会因稳定性约束被跳过，报错提示找不到该版本。
- 检查私有源返回的
packages.json是否真包含你要的分支或版本（比如"dev-main"对应的dist或source字段） - 临时放宽限制试一下：
composer require --dev myorg/tool:dev-main --stability-flags myorg/tool=dev - 私有源服务端（如 Satis）配置里确认
output-dir和archive设置正确，否则dev-分支可能根本没生成索引
多源配置真正的复杂点不在语法，而在包可见性链路：从你写的 composer.json → Composer 解析出源顺序 → 每个源返回的 packages.json 内容是否完整 → 包名与版本是否真被收录 → 网络策略是否放行对应域名。漏掉其中任意一环，都会表现为“源明明配了，就是不生效”。
