Composer path仓库配置不生效的三大原因是：type未设为"path"、url非绝对路径（禁用~和./且末尾不能有/）、目标目录无合法composer.json；须用realpath转绝对路径、显式配置symlink选项、避免require-dev被--no-dev忽略。
path仓库配置不生效，大概率是这三个地方错了
Composer对path类型仓库极其严格：缺一不可的三个条件是——type必须为"path"、url必须是**绝对路径**（不能含~、不能用./、末尾不能带/）、目标路径下必须存在合法的composer.json。任意一项不满足，Composer就静默跳过，连warning都不抛。
常见错误现象包括：composer install报Could not find package vendor/name，但ls /your/path/to/pkg明明存在；执行composer config repositories输出里压根看不到你刚加的条目；路径含空格或中文时，命令看似成功，实际写入配置被截断。
- 用
realpath转成绝对路径：composer config repositories.mypkg path "$(realpath ./local-pkg)" - 路径末尾一定不能加
/：/home/user/pkg✅，/home/user/pkg/❌ - 验证是否写入成功：
cat ~/.composer/config.json | grep -A2 mypkg，确认输出含"type": "path"和"url": "/abs/path/to/pkg"
要让本地修改实时生效，必须显式启用 symlink 模式
默认情况下，Composer会把path仓库内容复制进vendor目录，改源码不会触发重装——这不是bug，是设计行为。想让它像软链一样实时同步，必须在添加仓库时就带上options字段，且"symlink": true只对type: "path"有效，vcs或package类型不支持。
- 必须一次性写全JSON：
composer config repositories.mypkg '{"type":"path","url":"/abs/path/to/pkg","options":{"symlink":true}}' -
options无法后续补加，composer config命令不支持对已有仓库追加字段 - 启用后，
vendor/vendor/name会是到源路径的符号链接，不是副本；配合Docker卷挂载或IDE跳转非常顺滑
require-dev 里的 path 包容易被忽略，尤其在 CI 或部署时
如果path仓库包只出现在require-dev里，而你执行的是composer install --no-dev，它会被完全忽略——配置还在，但Composer根本不读取、不解析、也不报错。
更隐蔽的问题是版本约束冲突：path包的composer.json里写了"version": "dev-main"，但主项目require-dev写的是"vendor/name": "^1.0"，Composer会拒绝匹配（dev-main不满足^1.0）。
- 开发阶段建议统一用
dev-main或dev-develop作为version值，并在主项目中对应写"vendor/name": "dev-main" - CI流程中若用
--no-dev，确保path包不在require-dev里，否则它根本不会被安装 - 生产环境严禁使用
path仓库，上线前务必切换回Git或私有Packagist源
多项目共享本地包，关键在独立 composer.json 和路径组织
要让多个项目共用一个本地包，这个包本身必须是独立的Composer包：它得有自己的composer.json，定义name、autoload、version等字段，不能只是个普通PHP文件夹。
典型目录结构是：/workspace/my-lib/（含composer.json）和/workspace/my-app/（主项目），然后在my-app/composer.json的repositories里配{"type":"path","url":"/workspace/my-lib"}，再require它。
- 所有依赖它的项目都通过各自
composer.json的repositories去声明，而不是靠全局配置 - 不推荐把
path仓库写进~/.composer/config.json，因为不同项目可能依赖同一包的不同分支或状态 - 团队协作时，建议在项目根目录放
.env.example或README说明本地依赖路径，避免每人自己猜
path仓库本身很简单，但它的生效逻辑藏在细节里：绝对路径、symlink开关、require位置、包自身合规性——漏掉任何一个，它就安静地失效了。别指望Composer报错提醒你，它只会默默跳过。
