答案是路径写错导致Composer无法识别本地包：常见错误包括repositories未置于根composer.json、漏写{"packagist.org": false}、path仓库url用绝对路径或file://前缀、目录无合法composer.json、name/version与require不严格匹配。
composer.json 中 repositories 路径写错导致包找不到
自定义路径最常见错误是把 VCS 仓库（如 Git）或 path 仓库的 URL 写成本地绝对路径，而没加 file:// 前缀。Composer 会把它当普通 HTTP 地址去请求，结果直接报 Could not parse version constraint 或 Package not found。
正确写法必须显式声明协议：
- 本地 Git 仓库：
"type": "vcs", "url": "file:///home/user/my-package"（Linux/macOS）或"url": "file://C:/projects/my-package"（Windows） - 本地目录仓库（path 类型）：
"type": "path", "url": "./packages/my-package"—— 这里用相对路径，且不加file://，否则会失败 - 若用
file://指向一个不含composer.json的目录，Composer 会静默跳过，不报错但也不加载包
path 类型仓库未启用 symlink 导致 vendor 中无实际文件
path 类型默认启用符号链接（symlink），但 Windows 命令行未以管理员身份运行、或系统禁用了开发者模式时，composer install 会退化为复制（copy）模式，且不提示。结果是 vendor/my/package 目录存在，但里面没有 PHP 文件，只有空结构或 composer.json，运行时抛 Class not found。
验证方式很简单：
- 执行
ls -la vendor/my/package（Linux/macOS）或dir /a:l vendormypackage（Windows），看是否为真实链接 - 检查
composer.json根配置里有没有"config": { "preferred-install": { "my/package": "source" } }—— 这会强制走源码安装，绕过 symlink 判断 - 临时加
--no-dev再试一次，排除 dev 依赖干扰
repositories 顺序影响解析结果
Composer 合并所有 repositories 时按数组顺序从上到下遍历，遇到第一个匹配的包就停止搜索。如果你在顶部配了一个私有 Packagist 镜像，但底下又跟了一个 path 仓库，而你想用的包恰好也在镜像里（但版本旧），Composer 就永远读不到你本地最新的 path 包。
排查要点：
- 运行
composer config --list | grep repositories确认当前生效的仓库列表和顺序 - 把
path或vcs仓库移到repositories数组最前面 - 加
-vvv参数观察日志：如果看到Skipped package my/package (available from private repo)，说明被上面的仓库截胡了 - 不要依赖
packagist.org默认开启 —— 一旦你在repositories里写了任何非空数组，Composer 就会关闭默认源，除非显式加上{"packagist.org": false}或完整声明{"type": "composer", "url": "https://repo.packagist.org"}
Windows 下路径分隔符与大小写陷阱
Windows 用户容易忽略两点：一是反斜杠 在 JSON 字符串里需双写为 \，否则解析失败；二是 Composer 对路径大小写敏感，哪怕 Windows 文件系统不敏感，PSR-4 自动加载器仍会严格比对命名空间中的大小写。
典型症状：
-
composer diagnose报Invalid repository configuration，但看不出哪一行错 —— 很可能是"url": "C:projectsmy-package"里的单个p被当成转义字符 - 类文件在
app/Services/MyService.php，命名空间写成AppServicesmyservice，class_exists('AppServicesMyService')返回false - 执行
composer dump-autoload -o后，vendor/composer/autoload_psr4.php里映射的键是小写，但代码里引用的是大写类名
真正卡住的地方往往不是配置语法，而是路径语义和加载器行为之间的隐式耦合 —— 一个反斜杠、一个大小写、一行仓库顺序，都可能让整个依赖链静默失效。动手前先 composer diagnose 和 -vvv 日志，比反复改 composer.json 更省时间。
