repository 字段必须写在 composer.json 根级，与 require、autoload 平级；类型需显式声明（如 "vcs"），多源用数组；vcs 要确保 URL 可克隆、分支/标签匹配；package 类型需手动补全 name、version、dist 等字段；autoload 生效前提是目标包含有效 composer.json。
repository 字段写在哪？必须是根级配置
它不能放在 require 里，也不能嵌套在某个包的配置下——repository 必须直接写在 composer.json 的最外层，和 require、autoload 平级。放错位置会导致 Composer 完全忽略它，还查不出错，因为语法合法但语义无效。
常见错误现象：composer require vendor/name 报错 “Could not find package”，明明你加了自定义源，却始终拉不到。
- 确认
repository是数组，且位于文件顶层（不是config或extra下） - 类型必须显式声明：比如
"type": "vcs"、"type": "package"、"type": "composer" - 多个源用数组写法，别写成对象（否则只生效第一个）
vcs 类型怎么指向私有 Git 仓库？路径和分支要对得上
vcs 类型适合托管在 Git（GitHub/GitLab/私有 Gitee）的包，Composer 会自动探测 composer.json 并读取版本信息。但它不“猜”分支，也不“推断”标签 —— 你指定哪个分支或 tag，它就只认那个。
典型翻车点：本地开发时用了 dev-main，但仓库默认分支叫 master，或者你 push 了 v1.2.0 tag 却没打 1.2.0（少了个 v），composer require vendor/name:1.2.0 就会失败。
-
"url"值必须是可被 Composer 克隆的地址，比如"https://git.example.com/project.git"，不能是网页 URL - 如果要用私有仓库，确保运行
composer install的机器已配好 SSH key 或能走 HTTPS 凭据 - 想强制走某个分支，可以在
require中写"vendor/name": "dev-feature/login as 1.0.0"，但前提是该分支里composer.json的version字段存在且匹配
type: package 什么时候用？手动补全元数据的硬核方案
当你引用的是 ZIP 包、没有 composer.json 的老项目、或者想锁定某个特定 commit 的纯代码快照时，type: package 是唯一选择。它绕过自动发现，靠你手写完整包信息 —— 灵活，但也容易漏字段。
最容易漏的是 dist 配置里的 reference 和 shasum。不填 shasum，Composer 每次都会重新下载并校验（慢）；不填 reference（如 commit hash），更新时可能拉到意外版本。
-
"name"和"version"必须和require中写的完全一致（包括大小写、横线） -
"dist"至少要有url、type（zip/tar）、reference，强烈建议加上shasum - 如果包本身无
autoload，你得在自己的composer.json里用repositories[].package.autoload补，否则类找不到
使用 composer repository 时 autoload 不生效？检查包内 composer.json 是否真实存在
很多人以为只要 repository 配对了，Composer 就会自动加载包里的类 —— 实际上，只有当目标仓库根目录下真有 composer.json，且里面写了 autoload，才会生效。如果你用的是 type: vcs 但目标分支没提交 composer.json，或者它被 .gitignore 忽略了，那 autoload 就是空的。
验证方法很简单：composer show vendor/name 输出里看 autoload 行是不是空的；或者进 vendor/vendor/name 目录，手动打开 composer.json 看内容。
- 不要依赖“远程有，本地就一定有”——Git Submodule 或 CI 构建时可能跳过某些文件
- 如果包确实没
composer.json，别硬加repository，改用type: package并在其中补全autoload字段 -
composer dump-autoload不会修复这个问题，它只扫描已安装的包
真正麻烦的不是写错字段，而是混合用了 vcs + package + composer 类型源，又没理清优先级 —— Composer 默认按数组顺序查找，但一旦命中某个源，就不会继续往后找。所以顺序不对，可能让你改了半天 vcs，结果实际拉的是前面那个 package 定义。
