File System Access API 的 write、seek 和 truncate 有什么区别

在浏览器里做一个“只改文件中间几段内容”的编辑器时，FileSystemWritableFileStream 最容易被混淆的不是权限，而是三个动作的边界：write() 负责写入数据，seek() 负责移动当前字节游标，truncate() 负责改变文件总长度。它们可以组合，但不能互相替代。

一句话判断：想改当前位置用 write()，想改位置用 seek()，想改文件大小用 truncate()。写完还要 close()，因为浏览器通常先写临时文件，关闭流时才把结果提交到目标文件。

适合：实现浏览器端文本编辑、二进制补丁、日志尾部裁剪的前端开发者。

先把三个动作放回同一个游标模型

可以把可写流想成“文件内容 + 一个字节游标”。普通的 write(data) 从当前游标开始写入，写入完成后游标向后移动；它改变的是内容，不是“从文件末尾追加”的固定动作。

seek(position) 把游标移动到从文件开头计算的字节位置。它本身不写入任何内容。truncate(size) 则把文件调整为指定字节数：缩短时丢弃后面的内容，扩大时用零字节补齐；如果原游标超过新的大小，游标会被压回新的文件末尾。

同一件事也可以写成 write({ type: "seek", position }) 或 write({ type: "truncate", size })。这两种命令形式适合把操作放进统一队列；直接调用 stream.seek() 和 stream.truncate() 则更直观。

用 write 的数据形式覆盖当前区域

下面的例子先写入一段初始文本，再把游标移动到第 7 个字节的位置覆盖一小段内容。示例中的英文字符都占一个字节，因此偏移容易观察；中文文本应先按 UTF-8 编码后的字节长度计算，不能直接把 JavaScript 字符串长度当成文件偏移。

async function patchFile(fileHandle) {
  // 创建可写流；真实文件通常在 close 时才完成替换提交
  const stream = await fileHandle.createWritable();
  try {
    // 先建立一个可观察的初始内容
    await stream.write("status=ready;owner=web;");

    // seek 只移动字节游标，不会自动产生任何字符
    await stream.seek(7);
    // write 从当前位置覆盖同样长度的内容，后面的字节仍然保留
    await stream.write("paused");

    // 正常关闭才能把临时文件的结果提交到目标文件
    await stream.close();
  } catch (error) {
    // 失败时主动放弃临时写入，避免把半成品继续留在打开的流中
    await stream.abort();
    throw error;
  }
}

这里的关键是：覆盖写不会因为新字符串更短就自动缩短原文件。比如原文件有 23 个字节，游标在 7，写入 6 个字节后，文件大小仍至少由原来的尾部决定。需要裁掉尾部时，必须显式调用 truncate()。

用 seek 定位，用 truncate 调整尾部

truncate(size) 的参数是最终字节数，而不是“从当前位置删除多少字节”。这也是它与 seek() 最容易混淆的地方：先 seek 到某个位置，不代表文件就会从该位置截断；截断动作仍由 truncate(size) 的绝对大小决定。

async function rewriteTail(fileHandle, replacement) {
  const stream = await fileHandle.createWritable();
  try {
    // 用一个固定前缀示范“局部替换后裁掉尾部”
    await stream.write("header|old-body|unused-tail");

    // 把游标放到 header| 之后，覆盖正文区域
    await stream.seek(7);
    await stream.write(replacement);

    // size 是最终文件大小；这里会删除 replacement 后残留的旧尾部
    await stream.truncate(7 + replacement.length);
    await stream.close();
  } catch (error) {
    // 任何定位、写入或截断失败都放弃本次临时结果
    await stream.abort();
    throw error;
  }
}

这个片段只适合 ASCII 替换文本，因为 replacement.length 在这里恰好等于字节数。若内容可能包含中文或 emoji，应先用 TextEncoder 编码，再用编码结果的 byteLength 计算最终大小。

组合时记住三个边界

第一，偏移按字节计算。文本编辑器如果直接使用字符串下标，遇到多字节 UTF-8 字符就可能从字符中间覆盖，生成不可读内容。

第二，写入不是自动追加。想追加可以先读取当前文件大小，再 seek(fileSize)；不要把普通 write() 理解成永远写在末尾。

第三，完成路径要关闭，失败路径要放弃。调用 close() 才进入提交边界；异常时使用 abort()，并把错误交给上层处理。若浏览器环境不支持这组能力，还要根据兼容性表提供下载新文件或服务端保存等降级方案。

相关问题

write({type:"seek"}) 和 stream.seek() 有区别吗？它们都移动字节游标，前者适合统一走 write() 命令入口，后者表达更直接。

truncate(size) 变大时会发生什么？文件会扩展到指定字节数，新增区域以 0x00 填充；如果只想覆盖内容，不要为了“预留空间”随意扩大文件。

为什么写完立即读取目标文件看不到变化？可写流可能仍在临时文件中，先确认是否已经成功执行 close()，再重新取得文件内容。