需在composer.json的repositories中配置type为"path"且options.symlink设为true，路径须为相对路径、不跨出项目根，且本地包需有合法name和version。
composer.json 里怎么配 path 类型仓库才能让 symlink 生效
Composer 默认不会为本地扩展创建软连接，必须显式声明仓库类型为 path，并启用 symlink 选项。否则即使路径正确，composer install 也会复制文件而非链接。
- 在项目根目录的
composer.json中添加repositories配置，类型必须是path -
options下的symlink必须设为true（注意不是字符串"true"） - 路径值支持相对路径（相对于
composer.json），但不能以../开头跨出项目根——Composer 会拒绝加载 - 如果扩展包的
composer.json缺少name或version，path仓库会静默失败，建议先composer validate检查
{
"repositories": [
{
"type": "path",
"url": "./local-packages/my-extension",
"options": {
"symlink": true
}
}
],
"require": {
"vendor/my-extension": "*"
}
}
运行 composer require 后没生成软连接？检查这几点
常见现象是 vendor/vendor/name 目录存在，但里面是完整副本，不是指向源码的 symlink。根本原因通常是缓存或权限干扰，而非配置写错。
- 执行前先删掉
vendor/vendor/name和composer.lock，避免 Composer 复用旧记录 - 确保目标路径（如
./local-packages/my-extension）有读取权限，且不包含空格或中文——某些系统下symlink会静默退化为 copy - Windows 用户需确认启用了开发者模式或以管理员身份运行终端，否则
mklink调用会被拒绝 - Mac/Linux 下若看到
Warning: symlink(): Operation not permitted，大概率是目标文件系统挂载时禁用了follow_symlinks（比如某些 NFS 或 Docker volume）
symlink 模式下修改本地扩展代码，为什么 composer dump-autoload 不生效
因为 symlink 本身只是文件系统层面的指针，Composer 的 autoloader 不感知源码变更；它只认 vendor/ 下的结构。一旦你改了本地扩展里的类名或命名空间，就必须重新生成 autoload 映射。
- 每次修改本地扩展的
src/或psr-4映射后，都要在项目根目录运行composer dump-autoload - 如果扩展用了
classmap，还得加-o参数：composer dump-autoload -o，否则新类不会被扫描到 - 别依赖 IDE 自动重载——有些 IDE 缓存了 vendor 下的 symlink 目标路径，改了源码却仍提示 “class not found”，重启索引才解决
CI 环境或部署脚本里要不要保留 symlink 配置
不要。CI 构建和线上部署必须用确定、可重现的方式安装依赖，symlink 依赖本地路径存在，一旦路径缺失或权限不对，整个流程就卡住。
- 上线前应移除
repositories中的path条目，或用COMPOSER_HOME切换配置文件隔离开发/生产环境 - CI 脚本中可临时覆盖：
composer install --no-dev --optimize-autoloader，它会自动忽略path类型仓库 - 如果团队多人协作，建议把
path配置写进composer.json.dist，再通过composer config --file composer.json extra.enable-local-dev true动态启用，避免误提交
软连接看着方便，但它的脆弱性藏在路径、权限、文件系统特性这些底层细节里——哪天发现 symlink 变成了 copy，八成是其中一个环节没对齐。
