必须将 repositories 配置为项目根目录 composer.json 的顶层数组，每个对象含 type（"vcs"/"path"/"composer"）和对应 url；path 类型需确保包名、路径、version 三者严格一致，否则静默失效。
如何在 composer.json 中正确配置 repositories 字段
Composer 只读取项目根目录下 composer.json 文件顶层的 repositories 数组，其他位置（如嵌套在 config、extra 或子包自己的 composer.json 里）一概忽略。常见错误是把配置写进子目录或依赖包里，结果 composer require 一直报 Could not find package，其实根本没触发路径扫描。
必须确保 repositories 是根级字段，且数组内每个仓库对象包含明确的 type 和 url：
-
type: "vcs"：用于 Git/SVN 仓库，url必须是可 clone 的地址，例如"https://gitlab.example.com/myorg/mylib.git" -
type: "path"：用于本地路径，url必须是相对于项目根目录的合法路径（如"../my-local-package"），且该路径下必须存在有效的composer.json -
type: "composer"：用于私有 Packagist 类型仓库（如 Satis 或 Private Packagist），url是服务地址，例如"https://satis.internal.company" - 切勿手动添加
"packagist": {"type": "composer", "url": "https://packagist.org"}—— 它默认启用；加了反而可能因顺序问题屏蔽私有源
为什么 composer require 不走你配的私有源
Composer 默认信任 Packagist 的元数据缓存。即使已配好 vcs 源，执行 composer require myorg/mylib 时，它仍先查 Packagist，发现无此包才 fallback 到你的源——但如果该包名恰好被别人占用了（哪怕没发布），就会报 Could not find package myorg/mylib。
解决方法只有两个，且都得配合已生效的 repositories 配置：
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
- 加
@dev后缀强制走 VCS 探测：composer require myorg/mylib:@dev - 更稳的方式：先运行
composer clear-cache，再执行composer require myorg/mylib:dev-main（显式指定分支） - 如果包已存在于 Packagist，但你想强制用自己 fork 的版本，必须用完整版本约束，如
"myorg/mylib": "dev-fix-bug as 1.2.3"，并确保 fork 仓库的composer.json中name和version与 require 项严格匹配
path 类型仓库的三处 name 对齐要求
用 "type": "path" 引入本地包，不是加个配置就完事。必须三处 name 字段完全一致：
- 主项目
composer.json的repositories中定义的url所指向目录下的composer.json文件里的name字段（如"acme/utils"） - 主项目
require中写的包名（如"acme/utils": "^1.0"） - 该本地包自身
composer.json中的name字段，必须和前两者一字不差
任一不一致，Composer 会静默跳过该路径，不报错也不安装——这是最隐蔽的失败原因。
私有 Git 仓库认证与 URL 写法
若私有 Git 仓库需要认证，URL 写法直接影响是否能拉取成功：
- HTTPS + Token：用
"https://token:x-oauth-basic@github.com/owner/repo.git"格式，注意 token 要 URL 编码（如含/或+） - 推荐方式：提前在
auth.json中配置，避免密钥硬编码在composer.json或命令行中 - SSH 方式：URL 写成
"git@gitlab.example.com:myorg/mylib.git"，前提是本地 SSH agent 已加载对应私钥且 Git 能正常 clone - 不要在
url中写分支名（如.../repo.git#main），分支由 version 约束控制，否则 Composer 会解析失败
多源配置下，顺序决定 fallback 行为；但真正生效的前提，是包名未在 Packagist 注册，或版本约束明确指向某源——这点最容易被忽略，导致调试时反复怀疑配置本身，其实问题出在包名冲突或约束太宽泛。
