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

微软专家

在Flutter Windows项目构建时，有时会遇到一个令人困惑的CMake错误：

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

复制代码

如果此时你确信插件真实目录是存在的，比如通过PowerShell检查：

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

复制代码

返回值为True，那问题很可能出在Flutter生成的符号链接上。

用同样的方式检查符号链接目录：

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

复制代码

返回值却是False。这表示符号链接虽然存在，但目标路径无法被正常访问，导致CMake认为目录不存在。

原因剖析
--------
Flutter Windows构建过程中，会在 windows/flutter/ephemeral/.plugin_symlinks/ 下创建指向Pub Cache中真实插件目录的符号链接（symlink）。但在某些Windows环境下（特别是启用了严格安全策略或文件系统过滤驱动的系统），创建symlink时目标路径末尾的 \ 会被改写成异常字符。结果符号链接仍然存在，但它的target path被污染，无法被系统正确解析，CMake自然也就无法遍历 <plugin>/windows 子目录。

你可以用以下命令验证：

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

复制代码

如果输出中目标路径末尾的 \ 变成了乱码或不可见字符，基本就能确认是这个问题。

解决方案：改用Windows Junction重建链接
--------------------------------------
这个问题源于Flutter默认使用的符号链接机制在特定环境中不可靠。一个有效的修复方式是放弃symlink，改用Windows的“目录联接”（junction，即 mklink /J）。Junction是Windows原生支持的目录重定向机制，不受此类目标路径污染的影响。

我编写了一个工具 win_plugin_link_repair 来自动完成修复。它做的事情很简单：

1. 读取项目根目录下的 .flutter-plugins-dependencies 文件，解析出所有Windows插件列表。
2. 依次检查 .plugin_symlinks/<plugin> 是否存在且可访问。
3. 如果发现异常链接，先删除它。
4. 用 mklink /J 重新创建与原始目录的junction链接。

安装和使用方式如下：

2. # 添加开发依赖
3. dart pub add --dev win_plugin_link_repair
5. # 重新获取插件并修复
6. flutter pub get
7. dart run win_plugin_link_repair
8. flutter build windows

复制代码

如果你想先看看它会修改哪些链接，可以使用预览模式：

2. dart run win_plugin_link_repair --dry-run

复制代码

技术影响与建议
--------------
这个错误在社区中有不少用户遇到，相关讨论可参见 flutter/flutter#186000。核心教训是：当Flutter Windows构建报“插件目录不存在”时，不要只盯着插件本身是否安装，或者CMake配置是否有误。不妨先检查 .plugin_symlinks 下的链接状态。

该修复工具没有修改Flutter本身的行为，而是在构建前用junction替换了有问题的符号链接。因为Flutter每次执行 flutter pub get 都会重新生成 .plugin_symlinks，所以每次获取插件后都需要运行一次 dart run win_plugin_link_repair。你可以在CI/CD或本地开发流程中将它加入构建前置步骤。

如果你不想引入第三方依赖，也可以手动排查和修复：找到异常的 .plugin_symlinks/<plugin>，用管理员权限的终端运行：

2. rmdir <plugin> & mklink /J <plugin> "C:\Users\<user>\AppData\Local\Pub\Cache\hosted\pub.dev\<plugin>"

复制代码

不过手动操作容易遗漏，还是推荐使用工具自动化处理。

热心网友7

感谢楼主的详尽排查和实用工具！这个问题我之前在升级Flutter版本后也遇到过，当时手动重建symlink折腾了半天，看到你用junction方案替换确实更稳定。那个`fsutil reparsepoint query`的排查思路很清晰，以后遇到类似报错我知道该先查哪了。 另外想请教一下，如果项目里同时有Windows和Linux双平台的插件配置，这个工具会不会误伤Linux的链接？还是说它只针对Windows构建目录下的`.plugin_symlinks`？