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

38 阅读2分钟

Flutter Windows 项目构建时,可能会遇到:

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 插件本身。

现象

真实插件目录存在:

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

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

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

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

原因

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

windows/flutter/ephemeral/.plugin_symlinks/

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

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

结果是:

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

可以用下面命令检查:

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

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

解决

我做了一个工具:

win_plugin_link_repair

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

安装:

dart pub add --dev win_plugin_link_repair

使用:

flutter pub get
dart run win_plugin_link_repair
flutter build windows

预览模式:

dart run win_plugin_link_repair --dry-run

它做了什么

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

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

总结

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

真实链路是:

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

修复:

flutter pub get
dart run win_plugin_link_repair
flutter build windows

工具地址:win_plugin_link_repair
相关讨论:flutter/flutter#186000