各位年轻的 React 巫师们，大家下午好！
欢迎来到今天这场名为“如何让你的 React 状态不仅活在内存里，还能在磁盘上安家落户”的讲座。
我们今天要聊的东西，听起来可能有点反直觉。React 的核心哲学是什么？是“声明式”，是“状态驱动 UI”。React 告诉我们，不要去关心 DOM 怎么变，只要改变数据，视图就会自动变。这就像是我们在大脑里预演一场电影，脑子里有剧本，屏幕上就有画面。
但是，问题来了。这个“大脑”是内存，是易失性的。一旦你刷新页面，或者浏览器崩溃，或者你的老板突然让你关掉电脑去开会，你脑子里那些精妙的 React 状态——那些 useState，那些 useReducer，那些复杂的业务逻辑——就像是被格式化的硬盘一样，瞬间消失得无影无踪。
作为资深开发者，我们痛恨这种“幻觉”。我们想要真实的数据，想要持久化。于是，我们开始寻找通往磁盘的传送门。
今天，我们要探讨的终极武器，就是浏览器原生的 FileSystemWritableFileStream。这玩意儿就像是给了你一把瑞士军刀，让你直接在 React 的世界里插上一根管子，直通操作系统的文件系统。
废话不多说，让我们开始这场技术冒险。
第一章：内存的幻觉与 LocalStorage 的噩梦
在深入正题之前，我们必须先回顾一下历史，也就是我们过去是怎么在浏览器里存数据的。
最常用的招数是什么？localStorage。
还记得 localStorage 吗？那个让你又爱又恨的同步 API。
// 这段代码看起来很美，对吧？
const saveData = (data) => {
localStorage.setItem('myAppData', JSON.stringify(data));
};
const loadData = () => {
return JSON.parse(localStorage.getItem('myAppData'));
};但是，朋友们，localStorage 是一个同步的阻塞者。当你调用 setItem 时，浏览器会暂停渲染线程，去写那个 JSON 文件。如果你的数据量大，或者你的 JSON 序列化逻辑很复杂，整个 UI 就会卡顿，就像你吃了一顿极其油腻的火锅导致消化不良一样。
更糟糕的是，localStorage 是基于字符串的。你存进去的是字符串，取出来的是字符串。你需要不断地 JSON.stringify 和 JSON.parse。这就像是你每次跟女朋友约会，都要先把她翻译成摩斯密码，见面了再翻译回来。效率极低，还容易出错。
然后是 IndexedDB。IndexedDB 是异步的，它是浏览器里的小型数据库。理论上它很好用，可以存二进制数据，可以存大量数据。但是，它的 API 太复杂了，充满了回调地狱，或者现在虽然有了 Promise，但逻辑依然绕得像迷宫。而且，对于简单的键值对存储，它就像是用一辆重型坦克去搬一颗螺丝钉，大材小用，维护成本高得吓人。
所以，我们需要一个新的方案。一个既高性能，又简单，还能直接操作文件系统的方案。
第二章：现代武器 FileSystemWritableFileStream
这就是 FileSystemWritableFileStream 登场的时候了。
这是 Web File System Access API 的一部分。它允许网页直接读写本地文件。想象一下，你不再需要写一个“下载 JSON”的按钮，然后让用户去右键保存。你的网页可以直接在用户的硬盘上创建、修改文件，就像一个桌面应用程序一样。
这个 API 的核心在于 FileSystemFileHandle。它就像是文件在文件系统中的“身份证”。有了这个身份证，我们就能拿到 FileSystemWritableFileStream。
这个流是异步的，基于 Promise。这意味着它不会阻塞主线程，UI 依然可以流畅运行。这简直就是 React 开发者的福音。
第三章：原子性——数据持久化的圣杯
但是，仅仅能写入文件是不够的。我们面临着一个巨大的挑战：原子性。
什么是原子性？在数据库的世界里，原子性意味着一个操作要么全部成功，要么全部失败，不会出现中间状态。在我们的文件系统中，这意味着什么？
假设你的 React 状态是 { user: "Alice", age: 30 }。你想把它保存到文件 data.json 中。
如果你直接打开文件，把内容替换成 {"user": "Alice", "age": 30}，然后写入 50% 的字节，然后程序崩溃了，或者断电了。文件里就会变成 {"user": "Alice", "age": 3。这就像你写情书，写到一半笔没水了，留下了一个半截的句子。这就是非原子操作，它会破坏数据。
我们希望的是，要么文件是完整的旧数据，要么是完整的写入了新数据，绝对不能出现“半个新数据”的情况。
这就是我们要用 FileSystemWritableFileStream 实现的“原子化物理存储”。
第四章：实现方案——临时文件重命名大法
怎么实现原子写入？这里有一个经典的文件系统技巧：先写临时文件，再重命名。
流程是这样的：
- 打开目标文件（或者创建一个新的）。
- 创建一个临时文件（比如
data.json.tmp）。 - 将新数据写入临时文件。
- 检查无误后，将临时文件重命名为目标文件（
rename操作在大多数操作系统上都是原子的）。
如果第 3 步失败了，临时文件被丢弃，目标文件完好无损。如果第 4 步失败了，临时文件还在，我们可以重试。如果第 2 步失败了，那就真的是天灾人祸了。
但是，等等！FileSystemWritableFileStream 本身并没有直接的“重命名”方法。它只有 write()、seek()、truncate() 和 close()。
所以，我们需要一个变通的方法。实际上，在 Web API 中，我们并不需要自己手动创建临时文件。我们可以利用 FileSystemFileHandle 的 getFile() 方法来读取，利用 FileSystemFileHandle 的 createWritable() 方法来写入。
但是，为了实现真正的原子性，我们需要一种更高级的技巧。我们使用 window.showSaveFilePicker 来获取文件句柄。然后，我们使用 createWritable() 来写入数据。
等等，这不对。 createWritable() 是直接在文件句柄上创建流。如果你直接用流写，就不是原子的了。
修正策略：
在 Web API 中，要实现原子的写入，我们不能直接覆盖文件内容。我们必须先读取文件内容（如果文件存在），修改，然后写入。但这太慢了，而且对于大文件来说，读取整个文件再写入整个文件是低效的。
真正的 Web 原子写入技巧：
其实，现代的 Web File System Access API 提供了一个更优雅的解决方案，那就是利用 FileSystemFileHandle 的 getFile() 和 createWritable() 的组合，配合 write() 的参数。
但是，最简单、最稳健的方法，是使用 AbortController 来控制写入流。
不，那还是不够。我们今天要讲的是 FileSystemWritableFileStream。我们要利用它的 seek 和 truncate 方法。
终极方案：Seek 到开头，Truncate 清空，然后 Write 全部新数据。
是的，这听起来像是在破坏文件。但是，如果我们能在 seek 和 truncate 之间加一层保护呢？或者，利用文件系统的特性？
实际上，在 Web 环境中，最安全的原子写入方式是：使用 createWritable() 写入临时数据，然后使用 getFile() 读取旧数据，合并，再写回去？ 不，这太慢了。
让我们回到最基础的概念。在操作系统中，文件写入是原子的吗？不是。所以我们必须模拟。
最佳实践：
- 获取文件句柄。
- 使用
createWritable()创建可写流。 - 使用
seek(0)将指针移到文件开头。 - 使用
truncate(0)将文件长度清零。这一步很关键，它清空了文件。 - 使用
write(newData)写入新的 JSON 字符串。
但是！ 如果在第 4 步和第 5 步之间发生错误，文件就被清空了，数据就丢失了。这绝对不行。
真正的解决方案：使用 write() 的 keepExistingData 选项（如果支持）或者利用临时文件。
实际上，FileSystemWritableFileStream 的 write() 方法有一个参数对象，可以指定 type。但是，标准的 write 方法不支持 keepExistingData。
让我们换一种思路。 既然我们要用 React，我们就要用 React 的方式。
我们不需要在 React 层面实现复杂的原子文件系统逻辑。我们可以封装一个 Hook，它负责处理所有的文件 IO 细节。
第五章：实战演练——编写 useAtomicFileSystem Hook
让我们开始写代码。这是一个自定义 Hook，它接收一个文件名和一个状态值。每当状态变化时，它就会原子性地保存数据。
首先，我们需要一个辅助函数，用于将 JSON 序列化。
const serialize = (data) => {
try {
return JSON.stringify(data, null, 2);
} catch (e) {
console.error("Serialization failed", e);
throw e;
}
};现在，核心的 Hook。
import React, { useEffect, useRef } from 'react';
const useAtomicFileSystem = (filePath, state, options = {}) => {
const {
autoSave = true,
format = 'json',
onError
} = options;
const fileHandleRef = useRef(null);
const isWritingRef = useRef(false);
// 初始化文件句柄
useEffect(() => {
const initFile = async () => {
try {
// 尝试打开现有文件
fileHandleRef.current = await window.showOpenFilePicker({
id: 'react-file-system',
modes: ['readwrite'],
startIn: 'documents',
suggestedName: filePath,
types: [{
description: 'JSON Files',
accept: { 'application/json': ['.json'] },
}],
}).then(handles => handles[0]);
} catch (err) {
// 如果用户取消或文件不存在，尝试创建新文件
if (err.name !== 'AbortError') {
try {
fileHandleRef.current = await window.showSaveFilePicker({
suggestedName: filePath,
types: [{
description: 'JSON Files',
accept: { 'application/json': ['.json'] },
}],
});
} catch (saveErr) {
if (onError) onError(saveErr);
}
}
}
};
initFile();
}, [filePath, onError]);
// 保存状态
const saveState = async (data) => {
if (!fileHandleRef.current) return;
if (isWritingRef.current) return;
isWritingRef.current = true;
try {
const writable = await fileHandleRef.current.createWritable();
// 原子写入策略：
// 1. seek(0) 移动到文件开头
// 2. truncate(0) 清空文件
// 3. write(newData) 写入新数据
// 为了保证原子性，我们需要在一个 try-catch 块中完成这些操作
// 注意：truncate 是原子的吗？
// 在大多数现代文件系统上，truncate 操作是原子的。
// 但是，如果我们在 truncate 之后、write 之前崩溃，文件就空了。
// 这是一个风险。但是，这是 Web 环境下最快速的原子写入方式。
await writable.seek(0);
await writable.truncate(0);
await writable.write(serialize(data));
await writable.close();
} catch (err) {
console.error("File save failed", err);
if (onError) onError(err);
} finally {
isWritingRef.current = false;
}
};
// 监听状态变化
useEffect(() => {
if (autoSave && state !== undefined) {
saveState(state);
}
}, [state, autoSave]);
};第六章：深入解析原子性与性能
上面的代码展示了核心逻辑。但是，我刚才提到的 truncate(0) 策略存在一个致命的理论缺陷。
如果在 truncate(0) 之后，程序崩溃，或者用户关闭了浏览器，那么原来的文件内容就彻底丢失了。这不符合“原子性”的要求。
真正的原子性实现：
我们需要一种机制，确保写入是原子的。在文件系统中，最原子的操作是 rename。
- 创建一个新文件（例如
data.json.tmp）。 - 将数据写入
data.json.tmp。 - 将
data.json.tmp重命名为data.json。
在 Web API 中，FileSystemWritableFileStream 没有直接的 rename 方法。但是，我们可以利用 FileSystemFileHandle 的 move() 方法（在某些浏览器中）或者通过 getFile() 读取，然后 createWritable() 写入，最后删除旧文件（但这不是原子的，因为删除和写入不是原子的）。
等等，Web File System Access API 其实有一个更简单的方案。
我们可以使用 FileSystemFileHandle 的 getFile() 方法获取一个 File 对象，然后使用 FileReader 读取它，修改，然后写入。
不，这太慢了。
让我们重新审视 FileSystemWritableFileStream。
实际上，FileSystemWritableFileStream 的 write() 方法可以接受一个 Blob 或 BufferSource。我们可以创建一个 Blob。
为了实现真正的原子写入，我们需要利用浏览器提供的 FileSystemFileHandle 的 getFile() 方法，然后使用 FileSystemWritableFileStream 的 seek 和 truncate。
但是，为了安全起见，我们需要先读取旧文件，备份它。
终极优化方案：
我们不再试图在 React 层面实现完美的原子性，而是利用 FileSystemWritableFileStream 的特性。truncate(0) 实际上是原子的。为什么？因为如果你在 truncate 之后崩溃，操作系统会回滚 truncate 操作吗？
不会。
所以，我们必须换一种思路。
我们可以使用 createWritable() 的 keepExistingData 选项吗？
FileSystemWritableFileStream 的 write() 方法接受一个对象参数，其中有一个 type 字段。
await writable.write({
data: newData,
type: 'write' // 默认就是 'write'
});没有 keepExistingData。
好吧，让我们承认一个事实：在 Web 环境中，要实现 100% 原子的文件写入，是非常困难的。
但是，我们可以实现“接近原子”的写入，或者“安全”的写入。
安全写入策略：
- 读取旧文件内容（如果存在）。
- 序列化新数据。
- 将新数据写入临时文件（通过
showSaveFilePicker创建一个临时文件名，如data.json.tmp）。 - 读取临时文件内容。
- 将临时文件重命名为目标文件。
但是，showSaveFilePicker 是同步的（阻塞 UI），而且不能在已有文件上打开。
让我们回到最实用的方案：
使用 FileSystemWritableFileStream。我们接受 truncate(0) 的风险，但是我们可以通过以下方式降低风险：
- 使用
AbortController。 - 在
truncate之前，先备份文件。
备份文件策略：
const saveState = async (data) => {
// ... 获取 writable ...
try {
// 1. 读取旧文件
let oldContent = '';
try {
const file = await fileHandleRef.current.getFile();
const text = await file.text();
oldContent = text;
} catch (e) {
// 文件不存在，忽略
}
// 2. 备份旧文件 (创建一个 .bak 文件)
const backupHandle = await window.showSaveFilePicker({
suggestedName: `${filePath}.bak`,
});
const backupWritable = await backupHandle.createWritable();
await backupWritable.write(oldContent);
await backupWritable.close();
// 3. 写入新文件
await writable.seek(0);
await writable.truncate(0);
await writable.write(serialize(data));
await writable.close();
} catch (err) {
// 错误处理
}
};这个策略虽然保证了旧数据的安全，但是性能非常差，因为每次保存都要读取和写入两次文件。
结论：
对于 React 应用来说，FileSystemWritableFileStream 是一个非常强大的工具。它允许我们直接操作文件系统，绕过了 LocalStorage 和 IndexedDB 的限制。
虽然实现完美的原子性比较复杂，但我们可以通过 truncate(0) + write() 的方式来实现快速写入。如果数据的重要性极高，我们可以牺牲性能，采用备份策略。
第七章：React 组件中的完整应用
让我们把所有东西整合到一个 React 组件中。这是一个记事本应用，它保存你的笔记到本地文件。
import React, { useState, useEffect, useRef } from 'react';
const NoteApp = () => {
const [note, setNote] = useState('');
const [filename, setFilename] = useState('notes.json');
// 使用我们自定义的 Hook
useAtomicFileSystem(filename, note);
return (
<div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
<h1>React 原子存储笔记</h1>
<input
value={filename}
onChange={(e) => setFilename(e.target.value)}
placeholder="文件名"
/>
<textarea
value={note}
onChange={(e) => setNote(e.target.value)}
style={{ width: '100%', height: '300px', marginTop: '10px' }}
placeholder="在这里打字，它会自动保存..."
/>
<p>每次按键都会触发文件写入。</p>
</div>
);
};
export default NoteApp;第八章：权限管理与安全
使用 FileSystemWritableFileStream 意味着你的应用需要请求用户权限。用户必须明确允许你的网页访问文件系统。
如果用户拒绝权限，或者用户关闭了文件选择器，你的代码会抛出异常。我们必须妥善处理这些异常。
try {
const handle = await window.showSaveFilePicker();
// ... 写入逻辑 ...
} catch (err) {
if (err.name === 'NotAllowedError') {
console.warn("用户拒绝了文件访问权限");
} else if (err.name === 'AbortError') {
console.warn("用户取消了文件选择");
} else {
console.error("未知错误", err);
}
}第九章：性能优化与防抖
React 的状态更新是非常快的。如果你在每次 useState 的改变时都触发一次文件写入，那么你的应用会卡死。
我们需要防抖（Debounce）。
const debouncedSave = useRef(
debounce((state) => {
saveState(state);
}, 1000)
).current;
useEffect(() => {
debouncedSave(note);
}, [note]);第十章：未来展望
随着 WebAssembly 和 WebGPU 的发展，浏览器对文件系统的访问能力会越来越强。FileSystemWritableFileStream 只是第一步。未来，我们可能会看到更高效的文件存储方案，甚至是直接在浏览器中运行数据库。
结语
React 是前端开发的未来，而 FileSystemWritableFileStream 是连接 Web 与物理世界的桥梁。通过掌握这个 API，我们可以构建出真正持久化的 Web 应用。
不要害怕文件 I/O，不要害怕原子性。拥抱它，利用它，让你的 React 应用从内存的幻觉中醒来，变成真正的现实。
谢谢大家！