Composer默认不走symlink是为保障构建可重现性，而非开发便利性；默认copy行为确保install在任何环境下产出一致vendor目录，改本地代码无反应即因未启用symlink。
path仓库为什么默认不走symlink？
因为 Composer 优先保障构建可重现性，不是开发便利性。默认复制（copy）行为能确保 composer install 在任何机器上产出完全一致的 vendor/ 目录——哪怕目标机不支持符号链接、没权限、或运行在容器里。
这导致一个常见陷阱：你改了本地包代码，但主项目里完全没反应。根本原因不是路径写错了，而是 vendor/vendor-name/package-name 是个普通文件夹，不是指向源码的链接。
要启用实时同步，必须满足三个条件：
- 本地包自己的
composer.json根级包含"options": {"symlink": true}（不是主项目的repositories配置里） - 执行的是
composer update vendor-name/package-name，不是install - 系统支持 symlink：Linux/macOS 普通用户即可；Windows 需管理员权限或开启“开发者模式”；Docker 容器需加
--cap-add=SYS_ADMIN
require失败90%是因为name或路径不匹配
Composer 对 name 和 url 的匹配是严格字面量比对，不忽略大小写、不兼容下划线、不自动补 /，也不解析 ~ 或 ./。
典型错误现象：Could not find package vendor/name，但 ls ../my-pkg 确实存在，composer show --all 也看不到该包。
检查清单：
-
url必须指向含合法composer.json的目录，且是相对于主项目composer.json的路径，例如"../my-pkg"✅，"../my-pkg/"❌（末尾斜杠会静默失效） - 本地包
composer.json中的"name"字段必须和require里的字符串逐字相同，"acme/utils"≠"Acme/utils"≠"acme_utils" - 路径不能含中文或空格（某些 PHP 版本解析失败），推荐用
realpath转成绝对路径后配置
改了autoload映射为什么类还是找不到？
path 仓库让包“存在”，但不会自动触发自动加载器重建。即使你新增了 PSR-4 命名空间、改了 src/ 路径，或者加了新类，composer dump-autoload 不手动跑一次，new MyClass() 就会报 Class not found。
注意两点：
-
composer dump-autoload -o（优化模式）只在生产环境用；开发时用composer dump-autoload即可，它更快、支持动态重载 - IDE 断点可能失效，如果 IDE 映射的路径和真实磁盘路径不一致（比如用 WSL 或 Docker），Xdebug 会跳过断点——务必在 IDE 中校准源码根路径
为什么不能只靠package类型替代path？
"type": "package" 是静态描述，适合引用已打包但未发布的小型工具，但它不跟踪文件变更，也不支持 autoload 自动发现。
一旦你用 package 类型定义了一个本地目录，每次改源码都得手动 composer update 才能重新读取内容，且 autoload 部分不会自动更新——你得自己维护 files 或 psr-4 映射，极易出错。
而 path 类型本质是“活的包源”：
- 只要启用
symlink，改源码即刻生效，无需任何命令 - 自动读取本地包的
composer.json中全部配置：autoload、scripts、extra、require-dev - 支持
composer test（如果本地包定义了 scripts）、支持composer require --dev添加开发依赖
真正容易被忽略的是：symlink 生效与否，永远取决于本地包自己的 composer.json 是否声明了 options，而不是你往主项目里塞了多少配置。
