Windows (Beta 版本) 使用说明

从 JuiceFS 企业版 5.2 开始，JuiceFS 支持在 Windows 上运行。请注意，当前 Windows 客户端处于 Beta 阶段，请详细阅读以下说明。

运行时依赖

由于 Windows 不支持 FUSE，因此如果要在 Windows 上运行 JuiceFS，需要借助一个开源项目 WinFsp 对 FUSE 的实现。你需要在运行 JuiceFS 前，前往 WinFsp 的 GitHub 仓库下载最新版本并安装。

挂载方式

与 Linux 版本相同，JuiceFS 在 Windows 上也支持前台与后台两种挂载方式。对于后台挂载，JuiceFS 会依赖于 WinFsp 所提供的 Launcher 服务，在此模式下，文件系统将由 SYSTEM 用户进行挂载，如果你希望你的挂载能被同一台机器下的所有用户可见，请选择后台挂载。需要注意的是，后台挂载需要管理员权限执行。

JuiceFS Windows 版本默认使用后台挂载。

备注

如果你选择了前台挂载，则挂载的文件系统只对当前用户可见，这意味着如果你是以 Administrator 身份运行的挂载命令（例如提权的 Terminal 或者 PowerShell），则其它用户是无法访问该挂载的。

挂载类型

JuiceFS 在 Windows 支持将文件系统挂载成两种不同的类型：

1. 挂载为网络文件系统：在这种模式下，JuiceFS 会注册为一个网络文件系统，操作系统在进行 I/O 操作时，对于网络文件系统，会进行一些请求的优化以提高性能，这是 JuiceFS 默认的挂载类型。
2. 挂载为本地设备：在这种模式下，JuiceFS 会注册为一个本地的设备。如果你需要将一个文件系统挂载到非盘符，或者希望将挂载后的盘符进行共享，那么你可以选择使用该挂载类型（挂载时带上参数 --mount-as-local ）。

权限差异

Windows 与 Linux 2 个操作系统有本质不同的权限模型。Windows 使用 ACL（访问控制列表）来管理文件和目录的权限，Linux 使用的则是 POSIX 的权限模型。而在 JuiceFS 的后端中，相关数据是以 POSIX 的模型进行存储的。这意味着在转换过程中，可能会出现一些具体行为上的差异。

例如 Windows 新建文件时，文件的权限可能会根据创建时的 Security Descriptor 与父目录决定，如果你希望新创建的文件都有一个固定的权限，可以在挂载时使用 --create-perm=xxx 参数。（例如 --create-perm=0755）

UID 与 GID

在 Windows 上，用户 ID 以及所在的组，都是以 SID 的形式表示，这是一个字符串，类似于 S-1-5-32-544 这样的格式。在使用时，JuiceFS 会将 Windows 的 SID 通过一定的规则转化成 UID 与 GID，也会尝试将 POSIX 的 UID 与 GID 转化为 Windows SID。

通常来说，对于没有加入域的普通用户，这个转换的过程与用户名没有关系，只与对应用户 SID 值的最后部分有关。

值得一提的是，在 5.3 版本后，JuiceFS.exe 默认新增了一个挂载参数 admin-as-root，该值默认为 true。开启后，会自动将 Windows 内置的 Administrator 用户映射为 Linux 上的 root 用户 (UID=0)，如果你的写入操作是以 Administrator 身份进行的，那么你将拥有对文件系统的完全控制权限。如果你希望关闭该功能，可以在挂载时使用 --admin-as-root=false 参数。

此外，我们还提供了另一个 --as-root 挂载参数，指定此参数时，会将挂载点的所有操作，都以 root 用户身份进行。同时，为了处理系统的权限，我们还会将所有挂载点下的文件拥有者，都在 Windows 下映射为 Authenticated Users 组（S-1-5-11）。

挂载失败排查

如果你在挂载时遇到问题，可以尝试以下方法进行排查：

• 使用 -f --debug --fuse-access-log D:\\fuse.log 参数进行挂载，这样可以在前台与对应的日志文件获取更详细的输出信息。
• 在后台挂载时，使用 --log 参数指定日志文件路径。
• 找到 WinFsp 的安装目录，通常位于 C:\Program Files (x86)\WinFsp\bin，执行下面的 diag.bat 脚本检查各项输出是否正常。
• 尝试执行 net use X: \\memfs64\share 以挂载一个 WinFsp 的内存文件系统以测试 WinFsp 的系统服务是否正常运行。（该方法需要在安装 WinFsp 时勾选了开发组件）
• 如果问题依旧，请附上上方的相关日志，向我们的支持团队寻求帮助。

自动挂载

目前 JuiceFS 在 Windows 上不支持自动挂载功能。如果你需要在系统启动时自动挂载文件系统，可以考虑使用 Windows 的任务计划程序或者 winsw 等工具来实现。

备注

请注意，JuiceFS 默认在后台挂载时，会借助系统命令 net use 命令。而 net use 命令中，有一个 /persistent 参数可以配置系统级别的自动挂载。如果你遇到与此的相关问题，可以尝试修改此值后进行挂载。

已知问题

Close-Open 一致性

由于 WinFsp 对于 FUSE 的实现方式不同（WinFsp 在处理 CloseHandle 请求时并不会像 Linux FUSE 一般阻塞等待），因此 JuiceFS 在 当前 WinFsp 的最新版本（2025）中，并不能像 Linux 系统一样 保证 Close-Open 的一致性。

此问题已经在 WinFsp 的最新开发主线上进行了修复，如果你需要关于此问题涉及的一致性保证，请联系我们以获取我们发布的 WinFsp 安装包。

非 Onwer 身份的覆盖写

由于 WinFsp 对于 group 与 others 写权限的处理不同（WinFsp 的权限处理参考了 Windows SFU 的实现），在转换 POSIX group 与 others 的写权限时，转换结果中的 Windows ACL 并没有包含 WRITE_EA，这会导致非 Owner 用户在操作对应文件时，即时设置的权限为 0666，也无法进行覆盖写入。

此问题我们正在解决中。

特殊的文件属性

Windows 上一些特殊的属性，例如只读、隐藏等属性，JuiceFS 目前并不支持。

大小写问题

在 Windows 上，默认情况下，文件系统是大小写不敏感的。虽然 JuiceFS 在元数据中保存的数据是大小写敏感的，但在 Windows 版本中，JuiceFS 会在各项操作中忽略大小写差异。如果你的文件系统，恰好在同一个目录下，有着大小写不同的文件名（例如 a.txt 与 A.TXT），那么在使用中，可能会遇到一些未知问题。

同时，在已知的 Windows 内核对文件的处理中，也可能会出现文件名全大写化的问题，例如在文件浏览器新建一个文件 a.txt 后，可能会变成 A.TXT。出于性能的考虑，JuiceFS 默认不会向对应的查询接口返回大小写精确的文件名，如果希望在此特定情况下获取精确的文件名，可以在挂载时使用 --report-case 参数。

挂载后在我的电脑中没有自动刷新

受限于 Windows 文件系统的挂载检测机制，部分用户可能会在挂载成功后，发现我的电脑中显示新挂载的文件系统。你可以尝试手动刷新，或者直接输入对应的挂载盘符以检测是否能访问。

暂不支持的特性或者功能

• 不支持创建软链接