为何Node.js fs模块无法读写网络可见共享文件夹？

问题场景 #

在Windows 11环境下扩展Node.js应用，已搭建网络可见的共享文件夹，通过Windows原生文本编辑器等工具，主机及网络内任意电脑都能正常编辑文件并实时同步。但执行fs.writeFileSync("//DESKTOP-COOLNAME/folder/test.txt", "Hello, World!", "utf8")时，主机本地（或使用本地绝对路径）运行正常，远程工作站却抛出如下错误：

node:fs:2342
    return binding.writeFileUtf8(
                   ^

Error: UNKNOWN: unknown error, open '//DESKTOP-COOLNAME/folder/test.txt'
    at Object.writeFileSync (node:fs:2342:20)
    at file:///C:/Users/me/some_folder/some_file.js:3:4
    at ModuleJob.run (node:internal/modules/esm/module_job:222:25)
    at async ModuleLoader.import (node:internal/modules/esm/loader:323:24)
    at async loadESM (node:internal/process/esm_loader:28:7)
    at async handleMainPromise (node:internal/process/run_main:113:12) {
  errno: -4094,
  code: 'UNKNOWN',
  syscall: 'open',
  path: '\\\\DESKTOP-COOLNAME\\folder\\test.txt'
}

Node.js v20.12.0

解决方法 #

• 改用映射网络驱动器路径
  Windows下Node.js的fs模块对UNC路径（//主机名/共享名）的权限处理存在兼容性问题，建议先把网络共享映射为本地驱动器（比如映射成Z盘），再用本地路径替代UNC路径，示例代码：

  fs.writeFileSync("Z:/folder/test.txt", "Hello, World!", "utf8");
  

• 检查Node.js进程的权限
  远程工作站上运行Node.js的进程可能没有足够权限访问共享：

  • 确认运行Node.js的用户账号，在共享主机的文件夹属性「共享-高级共享-权限」中配置了读写权限
  • 如果用VS Code等IDE运行脚本，尝试以管理员身份启动IDE，规避权限不足的问题

• 使用转义后的完整UNC路径
  Windows的UNC路径标准是双反斜杠，在JavaScript字符串里需要转义，试试用\\\\DESKTOP-COOLNAME\\folder\\test.txt作为路径参数：

  fs.writeFileSync("\\\\DESKTOP-COOLNAME\\folder\\test.txt", "Hello, World!", "utf8");
  

• 验证SMB协议版本兼容性
  检查共享主机和远程工作站的SMB协议版本是否匹配：

  1. 打开「控制面板-程序-启用或关闭Windows功能」
  2. 确保双方都启用了SMB 1.0/CIFS文件共享支持或更高版本（推荐用SMB 3.0）

内容的提问来源于stack exchange，提问作者Axel Carré