Composer 通过配置 path 类型仓库并显式启用 "options": {"symlink": true} 实现软链接，需确保主项目 composer.json 的 repositories 中 url 为相对或绝对路径、本地包 name 与 require 一致、版本匹配，且执行 composer update 触发链接。
Composer 没有 composer link 这种命令，所谓“软链接本地插件目录”，本质是通过 path 类型仓库 + 显式启用 symlink 选项实现的。不配 repositories，只跑 composer require 或 composer install，永远只会去 Packagist 找包，不会碰你硬盘上的文件夹。
怎么写 repositories 才让 path 生效
必须在主项目根目录的 composer.json 顶层 repositories 数组里加配置，不能嵌套、不能放错位置：
-
url必须是相对路径（如"../my-plugin"）或绝对路径（如"/Users/me/my-plugin"），不能带file://前缀，也不能用~/或环境变量 - 目标目录下必须存在合法的
composer.json，且其中name字段（比如"acme/my-plugin"）要和你在require里写的完全一致（包括大小写） - 如果本地包没打 tag，建议
composer.json里留空version或设为"dev-main"，然后require时写"acme/my-plugin": "dev-main"，避免因版本不匹配静默失败
为什么 vendor 里是复制不是软链接
Composer 默认对 path 仓库启用软链接，但前提是：目标路径可写、系统支持 symlink、且没被显式禁用。一旦任一条件不满足，它会静默 fallback 到复制模式——你改代码，vendor 里还是旧副本。
- Linux/macOS 下检查是否生效：
ls -la vendor/acme/my-plugin，输出含->才是软链；否则就是复制 - 强制启用 symlink：在
repositories条目里加"options": {"symlink": true}（注意不是写在本地包的composer.json里） - Windows 用户需以管理员身份运行终端，或开启“开发者模式”，否则
symlink创建失败 - Composer 版本必须 ≥2.2，旧版不支持
symlink选项
执行什么命令才能真正创建软链接
composer install 不一定触发 symlink，尤其是首次安装或缓存未刷新时。真正可靠的方式是：
- 先确保
repositories和本地包composer.json都已就位 - 运行
composer require acme/my-plugin:dev-main --no-update（先注册依赖但不操作 vendor） - 再运行
composer update acme/my-plugin—— 这个命令才会读取repositories并按options决定是 symlink 还是 copy - 改完本地插件代码后，只需
composer dump-autoload刷新类映射，不用重装
常见报错和对应检查点
报错往往不是语法问题，而是路径、权限或版本策略卡住：
-
Could not find package acme/my-plugin：检查repositories.url路径是否存在、拼写是否正确（..层数够不够）、本地包composer.json的name是否和require完全一致 -
Could not scan for classes：本地包composer.json缺少autoload字段，哪怕只是{"autoload": {}}也要有 - 修改后不生效：确认
vendor/acme/my-plugin确实是 symlink（ls -la查看），且 PHP OPcache 没缓存旧的 autoload 映射（临时关掉或执行composer dump-autoload）
最易被忽略的点：软链接只在 composer update 时建立，install 可能复用缓存；而 Windows 权限、Docker 容器内 symlink 支持、以及 Composer 全局 symlinks 配置，都会覆盖局部设置——这些细节不验证，就永远在复制和链接之间反复横跳。
