必须在项目composer.json的repositories顶层数组中配置type为"path"的仓库，url用相对路径，本地包需含合法composer.json且name、version与require严格匹配，否则静默失效。
必须在项目 composer.json 的 repositories 数组中声明 type: "path"，且本地包的 name、路径、版本三者严格对齐；其他方式（如直接写进 require、手动 symlink、只改 autoload）都会静默失效或导致 CI 构建失败。
怎么配 repositories 才算生效
配置不是“加一行就行”，而是有硬性结构要求：
-
repositories必须是顶层数组，和require同级，不能嵌套在config或其他字段里 -
type字段值必须是"path"，写成"package"或漏掉会完全不识别 -
url必须是相对于当前composer.json的路径，例如"../my-utils"或"./packages/legacy-lib"；带file://、绝对路径（/home/xxx或C:/xxx）在多数环境（尤其是 CI）下静默失败 - 哪怕只配一个仓库，也要写成数组形式：
[{ "type": "path", "url": "../my-utils" }]
composer.json 里 name 和 version 怎么写才不报错
本地包自己的 composer.json 缺一不可，且格式敏感：
-
name必须是vendor/name格式（如"acme/utils"），不能和 Packagist 上已有包重名，也不能写成"utils"或"my-utils" -
version可以写具体值（"1.0.0"），也可用开发别名（"dev-main"）；若没写version，Composer 会 fallback 到目录名规则：目录叫my-utils-dev，就必须用dev-dev；叫my-utils-main，就得用dev-main - 必须有
autoload配置（哪怕空），否则类加载失败；推荐补上真实映射，比如"psr-4": {"Acme\Utils\": "src/"} - 该目录必须是 Git 仓库（哪怕只有一次空提交）：运行
git init && git add . && git commit -m "init"，否则 Composer 拒绝加载
Windows 下 symlink 失效？换种方式绕过
Windows 默认不支持符号链接，或需管理员权限 / 开发者模式开启，Docker 环境也常因此断点不触发、代码不更新：
- 不依赖
vendor/链接，改用主项目autoload直接注入路径：在主项目composer.json的autoload段追加命名空间映射，例如"MyApp\": "../my-app/src/" - 确保本地包根目录有合法
composer.json，且含"autoload"块（哪怕为空） - 执行
composer dump-autoload生效，无需require，也不进vendor - 注意：这种方式下
composer update不会影响该路径，更新靠手动同步；也无法使用该包的require-dev或脚本
最易被忽略的是 Git 初始化和 name 格式——两者任一缺失，Composer 都不会报错，而是直接跳过该仓库，让你反复调试却找不到原因。
