三分钟读懂 WinFsp：在 Windows 上快速构建你自己的用户模式文件系统

【免费下载链接】winfspWindows File System Proxy - FUSE for Windows项目地址: https://gitcode.com/gh_mirrors/wi/winfsp

你有没有过这样的念头：把云盘挂成本地磁盘直接拖文件、把一个代码仓库变成能双击浏览的目录、或者给自家应用做一个"看不见"的虚拟硬盘？在 Linux 上，FUSE 让这一切变得简单；而在 Windows 上，这个愿望过去几乎只能靠内核编程这种"高难度动作"实现——直到WinFsp（Windows File System Proxy）出现。它作为 Windows 平台的 FUSE 实现，让普通开发者用用户模式程序就能写出功能完整的文件系统，无需触碰内核，这正是它被称为 "FUSE for Windows" 的原因。

它到底是什么：一个比喻让你秒懂

想象一下开车。想让车跑起来，你不必先成为能改装发动机的赛车工程师——你只需要拿到一本驾照，学会踩油门、打方向盘就够了。

WinFsp 扮演的就是"驾照"的角色：Windows 内核里的文件系统接口本来像一台精密复杂的发动机，而 WinFsp 把它包装成了一套普通 C/C++ 程序就能调用的 API。你的程序负责"开车"（业务逻辑：数据存哪、目录怎么组织），剩下的"发动机运转"（与内核交互、处理底层 I/O）全部交给 WinFsp 处理。

一句话总结：WinFsp 是一套"用户模式文件系统开发框架"，由一个内核模式驱动（FSD）和一个用户模式 DLL 组成，让你像写普通程序一样写出一个"Windows 磁盘"。

这套框架在架构上做了清晰的分工：内核驱动位于 src/sys/，负责以文件系统驱动的身份与 Windows 内核打交道；用户模式 DLL 位于 src/dll/，提供开发者友好的接口。当某个应用程序尝试打开文件时，你的文件系统会收到一个Open调用，其余细节都被 WinFsp 悄悄处理掉了。

三步上手：从安装到挂载出第一个磁盘

纸上谈兵不如动手一试。WinFsp 的安装和验证比你想象的快得多，全程大概只需要三分钟。

第一步：安装时务必勾选 "Developer" 选项

安装器里有一个容易被忽略的选项——"Developer"。勾选它，你才能拿到头文件、库文件，以及一个开箱即用的示例文件系统MEMFS（内存文件系统），这是验证环境最好的工具。

第二步：把 MEMFS 挂载成一个盘符

打开命令行，执行下面这行命令，MEMFS 就会以网络驱动器的方式挂载到X:盘：

net use X: \\memfs64\test

看到 "The command completed successfully" 就说明挂载成功了。此时打开资源管理器，你会看到X:盘出现在"此电脑"里，可以像访问普通磁盘一样浏览它：

图：WinFsp 挂载的文件系统在 Windows 资源管理器中和普通磁盘毫无区别

第三步：写入并读取一个文件，验证成功

X: echo "hello world" > hello.txt type hello.txt

如果屏幕上打印出hello world，恭喜你——你的第一个用户模式文件系统已经跑通了！其实它干的事和上面这张命令行截图一模一样：通过net use挂载，然后像操作本地盘一样操作它。

图：命令行里一条 net use 命令，就把一个用户模式文件系统变成了可用盘符

核心机制讲透：异步 IPC 为什么又快又稳

跑通之后，你可能会好奇：既然文件系统逻辑都在用户模式，性能难道不会很差吗？这就要说到 WinFsp 最值得深入的一个设计——用户态与内核态之间的异步通信机制。

当应用程序发起一次文件操作时，真正的流程是这样的：应用发出请求 → 内核把请求交给 WinFsp 的内核驱动 → 驱动通过一套高效机制把请求"传递"给你的用户模式程序 → 你的程序处理后原路返回结果。整个过程涉及多次上下文切换，但 WinFsp 用异步事件队列把这种切换的代价压到了最低。

图：一次文件操作在用户空间（OP[U]、FS[U]）与内核空间（FS[K]）之间的完整流转

这套机制的关键在于事件队列的"信号"设计：队列为空时（Non signaled），没有事件需要处理，系统不会空转；一旦有请求进入（Signaled），驱动立刻唤醒用户模式的文件系统去处理。这种"按需唤醒"的方式避免了无谓的轮询开销，让通信既低延迟又高吞吐。

图：事件队列在空与非空两种状态下的切换，是异步机制高效运转的基础

性能到底如何？项目自带的基准测试给出了答案。下面这张图对比了 NTFS、MEMFS（基于 WinFsp 的内存文件系统）和另一个透传文件系统在各类文件操作上的耗时，柱状越短代表性能越好：

图：在 create、open、overwrite、delete 等操作中，基于 WinFsp 的 MEMFS 明显快于 NTFS

可以看到，MEMFS 在创建（0.34x）、覆盖（0.37x）、删除（0.54x）等操作上都大幅领先 NTFS 基准。一个跑在用户模式的文件系统，性能反而能超过微软原生内核文件系统——这正是异步 IPC 设计价值的直观体现。

除了这套核心机制，WinFsp 还顺带支持了这些特性（这里不展开，知道有就行）：

• 备用数据流（ADS）：Windows 特有的多数据流文件能力
• 任意安全描述符：精细控制文件权限
• 重解析点：支持符号链接、挂载点等高级语义
• 异步 I/O：充分利用多核 CPU
• 多架构支持：Windows 7 到 11，x86 / x64 / ARM64 全兼容
• 多套 API：原生 API、FUSE 2/3 API、.NET API

真实场景演练：WinFsp 能拿来做什么

理论说完了，来看三个最有代表性的使用场景。

场景一：把远程资源变成本地磁盘

这是 WinFsp 最"出圈"的用法。像 SSHFS-Win（通过 SSH 访问远程文件系统）和 rclone（云存储同步工具）都基于它实现。操作链条极其简单：安装 SSHFS-Win → 填上服务器地址 → 远程目录就变成了你的一个盘符。从此在资源管理器里拖拽文件，背后走的却是网络协议，你完全无感知。

场景二：把 Linux 上的 FUSE 文件系统搬到 Windows

如果你手头有一个 Linux 上的 FUSE 文件系统，迁移到 Windows 的成本比想象中低得多。WinFsp 提供了与 FUSE 兼容的 API：fuse对应 FUSE 2.x，fuse3对应 FUSE 3.x，头文件就在 inc/fuse/ 和 inc/fuse3/ 下。示例可以参考 tst/passthrough-fuse/，它把一个简单的透传文件系统用 FUSE 风格重写了一遍——对照着看，你就能明白两种写法的对应关系。

场景三：为自己造一个"业务文件系统"

这是最"硬核"也最自由的方向：把任何数据组织成一个文件系统。想做一个版本控制的虚拟目录？想给数据库套一个文件访问层？原生 API 都能满足。建议从 tst/memfs/ 这个内存文件系统开始读代码，它是理解原生 API 的最佳入口；生产级的透传实现则参考 tst/ntptfs/。

新手避坑指南：5 个常见报错与解决办法

新手阶段最容易遇到下面这些问题，提前知道能省下大量排查时间。

1. 程序报 "Missing WinFsp DLL"

WinFsp 刻意不把 DLL 装进系统目录（这是作者有意为之的设计决策），所以你的程序默认找不到它。解决办法是启用延迟加载，把winfsp-$(PlatformTarget).dll加入 Delay Loaded DLL，然后在wmain开头调用FspLoad(0)动态加载。

2. 在 WinFsp 盘里以管理员身份运行程序失败

Windows 要求承载可执行文件的文件系统名称是 "NTFS"。给 MEMFS 这类文件系统加一个参数指定文件系统标签即可，例如memfs-x64.exe -i -F NTFS -m X:。

3. Windows 7 上驱动签名报错

老系统可能缺少 SHA-2 代码签名支持，确保系统已完全更新即可解决。

4. 网络驱动器无法断开

如果你同时装了 Dokany，它的 Network Provider 可能会干扰 WinFsp 对网络驱动器的管理。到系统设置里调整 Network Provider 的加载顺序，让 WinFsp 排在前面。

5. FUSE 文件系统的权限不对

通过 FUSE 层挂载时，文件所有权可能不符合预期。可以加-o uid=-1让所有文件显示为启动用户所有，必要时再加上gid=-1。

生态与资源盘点：从哪里继续深入

如果你已经跃跃欲试，下面这些资源足够你按图索骥：

• 手把手教程：doc/WinFsp-Tutorial.asciidoc 带你从零写一个 passthrough 文件系统，全程代码级讲解
• API 参考：doc/WinFsp-API-winfsp.h.md 和 doc/WinFsp-API-launch.h.md
• 架构与设计：doc/WinFsp-Design.asciidoc、doc/WinFsp-Service-Architecture.asciidoc
• 性能测试方法：doc/WinFsp-Performance-Testing.asciidoc，附带完整测试数据
• 示例全家桶：原生 API 看 tst/memfs/、tst/passthrough/；FUSE 风格看 tst/passthrough-fuse/ 与 tst/passthrough-fuse3/；.NET 开发者参考 tst/memfs-dotnet/
• 测试套件：tst/winfsp-tests/ 覆盖了文件系统的方方面面，写自己的文件系统时可以直接借用
• 从源码构建：想深入了解或二次开发，可以用git clone https://gitcode.com/gh_mirrors/wi/winfsp拉取完整源码

结语

从"内核编程才敢想"到"三分钟跑通第一个文件系统"，WinFsp 把 Windows 文件系统开发的门槛降到了一个普通开发者完全够得着的高度。它既有拿得出手的性能，又有贴近 FUSE 的友好接口，还有一堆现成示例当"参考答案"——现在，轮到你去创造自己的那块"磁盘"了。🚀

【免费下载链接】winfspWindows File System Proxy - FUSE for Windows项目地址: https://gitcode.com/gh_mirrors/wi/winfsp