repositories必须写在主项目composer.json根级数组中，类型为"path"且url指向含合法composer.json的目录；name、version与require严格匹配，否则静默跳过或报错。
repositories 必须写在主项目 composer.json 根级
Composer 只读取项目根目录下 composer.json 文件顶层的 repositories 数组，其他位置（如嵌套在 config、extra 或本地包自己的 composer.json 中）一概忽略。常见错误是把配置写进子目录或依赖包里，结果 composer require 一直报 Could not find package，其实根本没触发路径扫描。
正确写法必须是数组格式，哪怕只配一个 path 源：
"repositories": [
{
"type": "path",
"url": "./packages/my-utils"
}
]
❌ 错误示例："repositories": {"type": "path", "url": "./packages/my-utils"}（对象格式静默失效）
本地包的 composer.json 必须合法且字段对齐
本地包目录下必须存在语法正确的 composer.json，否则 Composer 会跳过该仓库，不报错也不提示。关键字段有三个硬性要求：
-
name字段必须和你在主项目中require时写的完全一致（大小写、斜杠、vendor 名全敏感），例如"acme/utils"；写成"utils"或"Acme/Utils"都会失败 -
version可省略，但require时必须用dev-main这类分支名（不是1.0.0）；若本地包尚未打 tag，建议直接在本地包composer.json里加"version": "dev-main" - 目录必须已运行
git init并至少有一个 commit；否则 Composer 拒绝识别该路径
Windows 下注意：路径不能含中文、空格、盘符大小写混用；url 值必须指向含 composer.json 的目录，不能是文件路径（如 ../my-pkg/composer.json 就错）。
require 时版本号必须匹配分支名，且设 minimum-stability
本地包默认分支名决定你该写 dev-main 还是 dev-master。进本地包目录执行 git branch --show-current 确认，然后在主项目 require 段写死该分支名，例如："acme/utils": "dev-main"。
别写 "* @dev" 或 "^1.0"——这些会绕过 path 源，退回到 Packagist 查找。
还要在主项目 composer.json 中显式设置：
"minimum-stability": "dev", "prefer-stable": false
否则 dev-main 会被稳定性策略过滤掉，导致安装静默失败。
autoload 不生效？先 dump-autoload，再确认 symlink 是否启用
装上了但 Class not found，90% 和 Composer 加载路径无关，而是自动加载映射没更新或符号链接未生效：
- 确认本地包
composer.json中有正确autoload配置，例如："psr-4": {"Acme\Utils\": "src/"}（注意末尾双反斜杠） - 在主项目根目录运行
composer dump-autoload（开发阶段不用加-o） - path 类型仓库默认启用 symlink，但 Windows 下若终端非管理员权限、或 NTFS 禁用符号链接策略，Composer 会 fallback 到 copy 模式——此时改本地包代码不会同步到
vendor/下的副本
Linux/macOS 或 Docker 场景需确保挂载方式支持 symlink（Docker 中常需 --cap-add=SYS_ADMIN）；否则即使路径、name、version 全对，调试也是假热更新。
