Mac基于Node.js的镜像FUSE文件系统无法打开Word、PDF等文件

核心代码逻辑Bug #

• 文件读取偏移传参错误
  Node.js fs.read 方法的第5个参数为文件读取起始位置，现有代码在该位置传入了null，未匹配FUSE请求携带的实际读取偏移（即代码中用于切片的position变量）。该写法会导致fs.read顺着文件描述符的当前指针位置向后读取，和FUSE层要求的读取位置完全错位。
  普通文本文件大多是一次顺序读完全部内容，错位的影响不明显；但Word、PDF、Pages这类文件本质是带随机索引的压缩包结构，应用打开时会多次跳转不同文件偏移读取结构元数据，一旦偏移错位，读出的字节流完全混乱，就会触发“文件内容损坏”的报错。
• 缓冲区拷贝逻辑错误
  代码中将FUSE传入的写入缓冲区buf直接作为fs.read的目标缓冲区，设置写入偏移为0，fs.read已经将从磁盘读到的内容直接写入到buf的0起始位置。但回调中额外执行的buffer.slice(position, position + bytesRead).copy(buf)操作，本质是从全局文件偏移位置（如请求读取文件10240字节位置的内容时，position值为10240）对仅数KB长度的缓冲区做切片，切出的内容为空或越界垃圾值，直接覆盖了之前正确读入的有效字节。

其他容易触发同类问题的配置问题 #

• 错误码映射不匹配：当前代码无论遇到什么读取错误（磁盘IO异常、权限不足等），都统一返回ENOENT，会让上层系统把各类IO错误判定为“文件不存在”，触发异常读取分支。
• 缺失必要FUSE回调：如果未实现release、fsync、flush回调，macOS系统层的文件缓存会和镜像目录的实际内容脱节，应用写入后的文件内容未同步刷盘时，就会读出截断的坏数据。
• 属性同步不一致：如果getattr回调返回的文件大小、修改时间和镜像目录的实际文件属性对不上，macOS VFS层会优先使用本地缓存的旧内容，绕过自定义的read回调逻辑。

修复后参考代码 #

修正后的read回调实现

// position 为FUSE read回调原生传入的文件读取偏移量
const read = (path, fd, position, buf, len, cb) => {
  fs.read(fd, buf, 0, len, position, (err, bytesRead) => {
    if (err) {
      // 按错误类型映射对应FUSE错误码，不统一返回ENOENT
      const fuseErr = err.code === 'ENOENT' ? Fuse.ENOENT : Fuse.EIO;
      return cb(fuseErr);
    }
    // fs.read已将读入内容写入buf的正确位置，无需额外拷贝
    return cb(bytesRead);
  });
}

调试验证技巧：挂载时临时关闭内核缓存（对应fuse-native的配置项为kernel_cache: false），将挂载路径下的测试文件用dd if=/挂载路径/测试文件 of=本地dump文件导出，和镜像目录下的原文件做MD5比对，若值不一致则说明读取逻辑仍存在偏移错位问题。

内容的提问来源于stack exchange，提问作者Hardik Shah