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

相关讨论:flutter/flutter#186000

相关推荐
李小白杂货铺5 小时前
Windows 桌面 GUI 原型快速开发技术选型指南(Mac 开发 + Windows 交付场景)
windows·原型·gui·原型开发·技术选型·快速开发·技术路线
承渊政道9 小时前
magic-resume简历工具教程:Windows部署、在线编辑与远程访问
windows·远程访问·在线编辑·简历制作·工具教程·magic-resume
观察员1 天前
告别频繁锁屏:5行 PowerShell 脚本实现 Windows 自动防休眠
windows·命令行
Funlang1 天前
在 Windows 95 上写前端
前端·javascript·windows
一切皆有可能!!1 天前
【SoduWork测评】本机跑源码,找到并修了7个Bug
windows·开源·bug·ai编程·soduwork
xx z1 天前
打开游戏提示 d3dx9_43.dll 缺失怎么办(DirectX 修复步骤)
windows·游戏·工具·软件
如夏倾城1 天前
五大远程桌面协议:RDP、SSH、VNC/RFB、Citrix ICA/HDX 与 VMware Blast Extreme
运维·windows·网络协议·安全·自动化·ssh·远程工作
恋猫de小郭1 天前
Jetpack Compose 1.13 发布,憋了这么久终有交代了
android·前端·flutter
好的佩奇2 天前
蓝牙之设备角色与连接
android·flutter·蓝牙
Vex2une2 天前
JDK 8 下载安装与环境变量配置完整指南(Windows新手图文教程)
java·windows·环境配置·环境变量·jdk8·jdk下载安装·java入门教程