“failed to create symbolic link”错误源于php symlink()调用失败，非权限或开发者模式问题；需同时满足config.use-symlinks=true、composer_home为英文路径、--prefer-source重装，并清除vendor和composer.lock后执行。
报错“无法创建软链接”时，composer install 仍可执行，但默认会降级为复制（copy）模式——这不是失败，而是 Composer 的容错行为。真正需要干预的，是当你明确依赖 symlink 语义（比如 vendor/bin 脚本需直接执行、或 CI/CD 要求路径稳定）时，才必须修复软链创建条件。
为什么 composer install 报 “Failed to create symbolic link”
这个错误和权限无关，也不是 Windows 开发者模式没开。它只说明 PHP 的 symlink() 系统调用在当前上下文失败了，常见原因有：
- 项目路径含中文字符（如
/home/张三/project），PHP 在某些 locale 下对 UTF-8 路径处理异常 - 项目放在 WSL2 的
/mnt/c/下（drvfs 文件系统），不支持 Unix symlink，is_link()返回 false 导致 Composer 主动跳过 - 目标目录（如
vendor/bin）已存在且是普通文件或目录，不是空的，Composer 不会覆盖重试 - PHP 进程运行用户对目标父目录无写权限（少见，但
vendor/若被设为只读就会触发）
怎么让 composer install 强制走 symlink 模式
关键不是改 PHP 配置，而是告诉 Composer：“就算环境不理想，也请尽力建链接”。需同时满足三项：
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 项目根目录下
composer.json中配置："config": {"use-symlinks": true, "bin-compat": "full"} -
COMPOSER_HOME环境变量必须指向纯英文路径（如/home/user/composer），避免中文路径污染全局缓存 - 运行命令时加
--prefer-source（强制从源码安装，触发 symlink 创建逻辑）；若已有vendor/，先删掉再跑
注意："use-symlinks": true 只影响 vendor/bin 和包内 bin 字段声明的脚本，不影响 vendor/autoload.php 或包代码本身。
群晖 NAS 或宝塔面板下特别要注意什么
这些环境常因挂载策略导致 symlink 失效，但错误表现不同：
- 群晖 SSH 下用
root执行ln -sf报Operation not permitted？别切 root，改用 DSM 用户（如admin）登录后操作，/usr/local/bin对普通用户是可写的 - 宝塔面板中 PHP 命令行不可用，或禁用了
proc_open，会导致 Composer 启动失败，根本走不到 symlink 阶段——务必进「PHP 管理」删掉禁用函数，并用ln -sf /www/server/php/80/bin/php /usr/local/bin/php补全 PATH - 所有平台下，
vendor/目录若残留旧文件（尤其是vendor/bin已是普通目录），composer install不会自动清理重试，必须手动rm -rf vendor
最易被忽略的一点：即使你把所有配置都设对了，composer.lock 里如果记录的是上次 copy 安装的结果，Composer 就不会尝试重建 symlink——它只还原 lock 文件描述的状态。所以“删 vendor + --prefer-source”不是可选步骤，而是必要前提。
