Flutter Windows 构建失败：.plugin_symlinks 符号链接异常的排查与修复

Flutter Windows 项目构建时，可能会遇到：

text 复制代码

CMake Error at flutter/generated_plugins.cmake:
add_subdirectory given source
"flutter/ephemeral/.plugin_symlinks/<plugin>/windows"
which is not an existing directory.

如果插件真实目录存在，但 .plugin_symlinks 下的插件链接不可访问，问题不在 Flutter 插件本身。

现象

真实插件目录存在：

powershell 复制代码

Test-Path C:\Users\<user>\AppData\Local\Pub\Cache\hosted\pub.dev\<plugin>\windows\CMakeLists.txt
# True

Flutter 生成的插件链接不可访问：

powershell 复制代码

Test-Path windows\flutter\ephemeral\.plugin_symlinks\<plugin>\windows\CMakeLists.txt
# False

CMake 因此认为插件目录不存在。

原因

Flutter Windows 构建会在这里生成插件链接：

text 复制代码

windows/flutter/ephemeral/.plugin_symlinks/

这些链接指向 Pub Cache 中的真实插件目录。

在某些 Windows 环境中，安全策略或文件系统过滤驱动会影响符号链接创建：目标路径末尾的 \ 会被改写成异常字符。

结果是：

text 复制代码

符号链接存在
但 target path 被污染
所以链接无法被遍历
CMake 无法进入 <plugin>/windows

可以用下面命令检查：

cmd 复制代码

fsutil reparsepoint query windows\flutter\ephemeral\.plugin_symlinks\<plugin>

如果看到目标路径末尾的 \ 变成异常字符，基本就能确认。

解决

我做了一个工具：

win_plugin_link_repair

它会读取 .flutter-plugins-dependencies，找到 Windows 插件，然后把 .plugin_symlinks 下的异常链接重建为 Windows junction。

安装：

bash 复制代码

dart pub add --dev win_plugin_link_repair

使用：

bash 复制代码

flutter pub get
dart run win_plugin_link_repair
flutter build windows

预览模式：

bash 复制代码

dart run win_plugin_link_repair --dry-run

它做了什么

text 复制代码

读取 .flutter-plugins-dependencies
找到 plugins.windows
删除异常的 .plugin_symlinks/<plugin>
用 mklink /J 重建链接

工具不会继续使用 Flutter 生成的 symlink，而是改用 Windows junction（mklink /J）重建插件目录链接。这个问题出在 symlink 创建阶段，换成 junction 后可以避开目标路径被改写的问题。

总结

这个错误不一定是插件缺失，也不一定是 CMake 问题。

真实链路是：

text 复制代码

Flutter 创建插件 symlink
→ 系统安全策略/驱动污染 symlink target 末尾的 \
→ .plugin_symlinks/<plugin> 无法遍历
→ CMake 报插件目录不存在

修复：

bash 复制代码

flutter pub get
dart run win_plugin_link_repair
flutter build windows

工具地址：win_plugin_link_repair