必须显式声明repositories且包名、URL、type严格匹配，否则Composer完全忽略该源；常见错误包括字段名拼错、type值非法、路径与type不匹配、包名大小写或格式不符，以及未显式启用packagist.org导致公共包也无法安装。
必须在 composer.json 的 repositories 字段里显式声明，且包名、URL、type 三者严格匹配，否则 Composer 根本不“看见”那个仓库。
为什么 require 写对了却 still not found
Composer 不会自动扫描任意 Git URL 或本地路径——它只查你明文列在 repositories 数组里的地址。常见错因：
-
repositories拼错成repository（少 s）、repos或sources，JSON 解析失败，整块被忽略 - 写了
"type": "git"，但合法值只有"vcs"、"path"、"composer"，写错直接跳过 - 本地路径用了相对路径如
"../my-package"，但type是"vcs"——vcs不支持相对路径，必须用"file:///absolute/path"或换type: "path" - Git 仓库 URL 少了
.git后缀（尤其自建 GitLab/Gitee），https://gitlab.example.com/group/pkg会失败，必须写https://gitlab.example.com/group/pkg.git
type: "vcs" 和 type: "path" 怎么选
二者行为完全不同，不能混用：
Workflow Decomposer
下载
工作流任务拆解与模型编排技能。使用场景：(1) 收到复杂工作任务需要拆解为可执行步骤，(2) 需要为不同步骤选择最合适的模型，(3) 需要跟踪工作流进度和模型使用情况，(4) 长时间任务卡住需要问题诊断和解决方案。
-
type: "vcs"：适用于远程或本地 Git/SVN 仓库，Composer 会执行git clone或git ls-remote获取元数据；URL 必须是可clone的地址，如"file:///home/user/mylib"或"https://github.com/vendor/pkg.git" -
type: "path"：仅用于项目同机的本地目录，Composer 直接硬链接或复制文件；URL 是相对于当前composer.json的路径，如"../my-private-lib"，且不能带file:// - 同一个包若同时出现在两种源里，
path优先级高于vcs，但不会自动 fallback —— 选一个，别并存
包名不一致导致 404 的硬性规则
Composer 匹配依赖时，**完全忽略 URL，只比对 require 中的包名和目标仓库根目录下 composer.json 的 name 字段**：
- 如果仓库
composer.json写的是"name": "acme/utils"，require里就必须是"acme/utils": "dev-main"，写成"acme/utils-dev"或"Acme/Utils"都失败 - 分支名要对应：用
dev-main对应main分支，dev-develop对应develop分支；tag 直接写真实名，如"1.2.0" - 若仓库没打任何 tag，又没设
"minimum-stability": "dev"，dev-main会被拒绝——此时要么加"prefer-stable": false，要么改用composer require vendor/name --stability=dev
repositories 声明后连 monolog 都装不上？
只要 repositories 数组存在（哪怕为空），Composer 就默认关闭 Packagist 自动注入。结果是私有包找不到，公共包也全挂：
- 修复必须显式补上官方源：
{"packagist.org": false}作为数组第一项，再加一条{"type": "composer", "url": "https://mirrors.aliyun.com/composer/"} - 私有仓库单独加一条，如
{"type": "vcs", "url": "https://gitlab.internal.company.com/group/pkg"} - 改完立刻运行
composer clear-cache，否则旧缓存仍用“无 packagist”的配置 - 验证是否生效：运行
composer config repositories，输出里不应再出现https://repo.packagist.org
最容易被忽略的是：修改 repositories 后不删缓存，也不验证 composer diagnose 输出的 Repo 行是否已更新——缓存残留会让所有配置形同虚设。
