在 composer.json 中添加自定义仓库需在根级配置 repositories 数组，类型包括 vcs、composer 和 path；顺序决定优先级，常见错误是错放位置或拼写错误；仓库仅提供其声明的包，需确保目标包 name 存在且源已启用。
怎么在 composer.json 里加自定义仓库
直接改项目根目录的 composer.json，在顶层加 repositories 字段就行。它是个数组，每个元素描述一个仓库，顺序会影响查找优先级——靠前的会先被检查。
常见错误是把 repositories 塞到 require 里面，或者拼错字段名写成 repository（少个 s），结果完全不生效。
- 私有 Git 仓库：用
{"type": "vcs", "url": "https://git.example.com/my/package.git"} - Packagist 镜像：用
{"type": "composer", "url": "https://packagist.example.com"} - 本地路径（调试用）：用
{"type": "path", "url": "./packages/my-package"}，注意路径是相对于composer.json的
为什么 require 的包没走自定义仓库
Composer 不会自动把所有包都扔进你配的仓库里找，它只查那些「仓库明确声明能提供」的包。比如你加了一个私有仓库，但没在它的 composer.json 里写 name（如 "myorg/foo"），或者没把该仓库的 name 放进 repositories 的 packagist 白名单里，Composer 就当它不存在。
另一个坑是用了 packagist.org 的镜像源却没关掉默认源：{"packagist.org": false} 必须显式写进 repositories 数组里，否则它还是优先走官方源。
- 检查目标包是否真在那个仓库中发布过（比如 Git tag 是否打了符合
version规则的标签） - 运行
composer show myorg/foo看它实际从哪个源解析出来的 - 加
-vvv参数跑composer update，看日志里有没有尝试访问你的仓库 URL
vcs 类型仓库的 tag 和分支怎么识别
Composer 对 Git 仓库的版本识别依赖 tag 名字格式，不是所有 tag 都算有效版本。默认只认 v1.0.0、1.0.0 这类语义化版本 tag；dev- 开头的分支名会被当成开发版（如 dev-main），而 main 分支本身不会自动映射为 dev-main，除非你在 require 里明确写 "myorg/foo": "dev-main"。
如果 tag 名不规范（比如 release-2.1），Composer 就找不到对应版本，报 Could not find package myorg/foo at version ...。
- 推荐统一用
vX.Y.Z格式打 tag，避免空格、下划线或前缀干扰 - 想让某个分支长期可安装，得在该仓库的
composer.json里加"minimum-stability": "dev"和"prefer-stable": true配合使用 -
composer config --list可查当前 stability 设置，避免全局配置覆盖项目级行为
自定义仓库影响 autoload 和 autoloading 吗
不影响。autoload 是包自己 composer.json 里的 autoload 字段决定的，和从哪个仓库拉下来无关。但有个关键例外：如果你用 path 类型仓库，且路径指向的是未打包的开发目录，Composer 默认会启用 autoload-dev 并软链接源码——这时如果目标目录里没有 composer.json 或写错了 autoload，就会导致类找不到。
另一个易忽略点：多个仓库提供同名包不同版本时，Composer 不保证加载顺序，可能引发 class redeclare 错误，尤其在测试环境混用 path 和 vcs 时。
- 用
composer dump-autoload -o强制重生成 autoload 文件，排除缓存干扰 - 检查
vendor/composer/autoload_psr4.php里是否真的注册了你期望的命名空间 - path 类型仓库务必确保目标目录下有合法的
composer.json，哪怕只是空文件也比没有强
最麻烦的其实是仓库间依赖关系嵌套：A 包从自定义源装，它又 require 了 B 包，而 B 包只在另一个私有源里——这时候得把两个源都配进 repositories，且顺序不能错。没人替你推导依赖链，全靠手动补全。
