每次手头要做小工具，我都先习惯给项目起一个短到不能再短的名字。“rea”就是这么来的——Real-time Edit Assistant，一个跑在本地浏览器里的实时编辑助手。听起来不算惊艳，但它解决的问题非常具体：我平时写方案提纲、整理读书摘录、把一段临时日志改写成长文，需要一个打开就写、关了不丢、内容不离开本机的编辑环境。在线文档太重，系统自带记事本又太原始，rea 恰好卡在中间。

rea 的形态比大多数笔记工具更朴素：左边一个编辑区，右边一个预览区，底下一条状态栏告诉你已经自动保存了多少次。没有账号体系，没有云同步，没有协作邀请链接。内容默认存到本地临时区，也可以一键导出成纯文本放到自己的目录。第一版我刻意不做登录、不做注册、不做多端同步，因为这些功能一旦加上，开发精力就会被不断稀释，最核心的“打开即写”反而会变得拖沓。

这个项目适合三类人：一是不想把文档交到别人服务器上的本地优先用户；二是经常需要快速起草、改写、归档文本的写作者；三是想练习前端交互、本地存储、文本解析这一整套链路的新手。如果你只想找一个“打开快速、存储简单、跨天不丢”的写作工具，rea 的思路可以直接拿走用。

1. 先想清楚：rea 到底解决什么问题

1.1 把需求压缩成一句话

做这个项目前，我列过一张需求清单，写了很多条：多标签页、富文本、协同编辑、图片上传、版本历史、标签系统、全文搜索、深色模式、主题切换……看着很全，但每一项都是成本。后来我强迫自己把所有想法压缩成一句话：用户打开页面，开始打字，关掉页面，内容还在。

这句话听起来像废话，但真做起来并不容易。系统记事本打开就写，却不会帮你分门别类；在线文档功能全，却需要登录、需要网络、需要信任第三方。rea 要补的缺口不是功能数量，而是“极低启动成本”和“极低心理负担”。

我最后把第一版范围收敛成五个能力：写入、自动保存、轻量预览、本地归档、简单检索。多标签页砍掉了，因为单页任务流已经够用；富文本砍掉了，因为纯文本可以直接做差异比对和版本对比；协同编辑彻底放弃，因为那个方向会引入服务端、消息推送、权限管理，和“本地优先”直接冲突。砍完需求的那一刻，整个项目的复杂度几乎减半。

1.2 为什么必须是本地优先

我很早就发现，自己写得最顺畅的内容往往不是坐在电脑前构思出来的，而是随手打开一个空白页，边想边写。这种场景对网络的依赖十分敏感：断网时在线文档无法打开，正在输入的段落可能被存进离线缓存，但同步时机不可控；浏览器崩溃或者切换设备，内容又可能卡在某个半同步状态。本地优先能绕开这些问题。

rea 的所有数据都执行本地存储，网络需求为零。我不需要服务器，不需要数据库账号，不需要配置跨域，这也意味着用户数据只存在于自己的设备上。一旦遇到敏感话题的草稿、公司内部的方案、还没到公开时间的公告，本地优先就变成一种安全选择——不是加密级别的安全，而是“不被他人顺手翻看”的从容。这个问题我理解为数据主权，不是技术能力，是产品价值观。

当然，本地优先也带来新的问题：跨设备使用不方便，换电脑等于换环境。我的处理方式是预留一个“明文导出”按钮，把内容落成本地文件；另外留一个“导入”入口，文件夹里已有的文本能被批量读入。这不算云同步，但已经覆盖了我百分之九十的真实用法。

1.3 技术选型：越普通越省心

按我以往的脾气，这种项目肯定想上一套很“现代”的框架，再配一堆构建工具。但这次我刻意做了减法。rea 的主体直接用浏览器原生技术实现，包括 JavaScript、HTML、CSS，以及浏览器提供的本地存储能力。启动方式只有一条命令：静态文件服务，把目录跑起来即可。

有人会问：为什么不直接用桌面应用壳？我比较过几个方案，最终没有选更重的路线，主要原因有三点。第一，写作工具的核心是键盘输入和文字渲染，浏览器已经把这部分优化得很好，套一层壳带来的收益很小；第二，桌面壳会让安装包体积膨胀、跨平台调试成本上升，我这个项目不值得；第三，使用原生 Web 技术可以保持项目零依赖，以后想把内置编辑器嵌入别的页面，或者让预览端口独立运行，都很容易。

这样选型的代价是功能边界受限，比如无法拿到完整的文件系统访问权限。但我的应对方式非常实际：默认不直接操作任意磁盘目录，而是把内容落在浏览器存储区，再通过导出、导入完成和本地文件的交换。这样既保证使用顺畅，又不触碰权限黑洞。一个工具能稳定运行五年，比它一开始能调用多少底层接口重要得多。

2. 核心机制拆解：实时保存、增量渲染、安全预览

2.1 实时保存的防抖与兜底

“实时保存”听上去很简单，无非是每次输入都写一遍。可真这样写，性能问题马上就会冒出来。中文输入法每确认一个词都会触发一次输入事件，一分钟可能触发几十次，每次都把整篇内容序列化、写入存储，内存和磁盘都会变得烦躁。所以我做了两层控制。

第一层是防抖：用户停止输入一段时间后再保存。我实测下来，300 毫秒是一个比较舒服的阈值。低于 200 毫秒，内容长了容易频繁触发全量写入；高于 500 毫秒，又会在紧急退出时增加丢内容的概率。核心代码逻辑大致是：

let timer = null; function scheduleSave() { if (timer) clearTimeout(timer); timer = setTimeout(flushSave, 300); } function flushSave() { const text = editor.value; saveSnapshot(text); statusBar.textContent = `已自动保存 ${++saveCount} 次`; }

第二层兜底是页面退出前的强制保存。只靠在输入时防抖还不够，因为用户可能在防抖计时器还没走到的时候就关掉标签页。我监听beforeunload事件，在页面卸载时立刻同步保存一次。另外，如果内容较大或者存储写入较慢，顺便做一个标记写入，等下次打开时对照标记自动恢复。这两层叠加以后，我连续用了一周都没有再遇到“写了半天内容突然没了”的情况。

2.2 增量渲染：别让大文件拖垮输入

rea 最初版本用的是最原始的办法：每次输入，把整个正文解析一遍，再把整个预览区重新渲染。几千字的时候没感觉，一旦内容涨到几万字，或者一篇文章里带了很多标题和引用块，输入延迟就明显了。那位朋友开了个十万字的小说设定文档，我帮他调试时看到光标已经明显跟不上按键速度。

根因不是单次解析本身慢，而是每次按键都做全量重绘。我引入了一个非常朴素但很有效的手段——分批渲染。

基本思路是：内容变化后不立刻更新预览，先用防抖攒住，比如 800 毫秒后再刷新；刷新时也不重建整个 DOM，而是把长文档按空行切成若干区块，只更新发生变化的区块。为了更稳，还加了一个可视区域控制：预览区只渲染当前可见范围和上下几屏，其他部分用空占位和累计高度撑住滚动位置。

这样改完，十万字文档的输入响应基本回到了流畅区间。滚动时会有极短暂的占位状态，等当前视口触发渲染后立即补上内容。这个方案的缺点是实现细节多一点，但换来的是普通笔记本上也能稳定运行。如果你遇到相似问题，可以考虑先做“切块更新”，而不是一上来就上复杂的虚拟列表。

2.3 预览安全：零信任内容渲染

在 rea 中，用户输入的文本要被解析成带格式的预览内容。这就涉及一个高危点：如果直接把原始输入插入页面，一段包含其他标签的内容就可能突破样式边界，轻则打乱布局，重则带来安全隐患。我是拿“零信任”原则处理这一块的：用户输入的内容一律当作不可信数据，解析结果必须经过白名单过滤。

我的做法是自定义一个极简标记语法，本质上就是非常朴素的标题、列表、引用和代码块。解析过程分为三步：先做转义，把尖括号等特殊字符转成安全实体；再做区块切分，识别哪些段落是标题、列表还是引用；最后按白名单生成对应的 HTML 标签。整个过程中，任何不在白名单里的标签都会被当成普通文本展示。

const allowedTags = ['H2', 'H3', 'P', 'UL', 'OL', 'LI', 'BLOCKQUOTE', 'CODE', 'PRE']; function renderPreview(text) { const escaped = escapeHtml(text); const blocks = splitIntoBlocks(escaped); return blocks .map(block => sanitizeBlock(block, allowedTags)) .join(''); }

这个方案看起来不如通用标记解析器强大，但对一个笔记工具来说足够安全。用户手里拿到的只是一个“带简单排版的编辑器”，而不是一个完整文档处理器，这也让自己少了很多维护负担。如果你只是做内部工具，优先保证内容不被执行，功能上做减法完全值得。

2.4 外部修改怎么同步进来

本地优先意味着用户可能在文件夹里直接编辑文本，也可能从其他工具导出一份文件再放进来。rea 需要感知文件变化，否则就会出现“我在编辑器改了，外面文件却是旧的；外面改了，编辑器还显示旧内容”的错乱。理想情况是监听文件系统事件，但由于我选择了纯浏览器方案，对本地文件的实时监听有限制。

我的妥协办法是定时轮询加校验：每隔一段时间，扫描一次目标文件的大小和修改时间，发现变化时自动重新加载内容；同时把 rea 自己刚写出的修改排除在事件之外，避免循环刷新。轮询间隔我设置为 2 秒，写字时基本感知不到延迟，外部修改后最晚两秒内会反映到界面上。这个方案不精致，但非常稳，不会错漏事件，也不会过度消耗资源。

3. 实操记录：从空白目录到第一个可用版本

3.1 最小目录结构与启动方式

我把 rea 的第一版做成了零依赖、零构建的样子，目录非常朴素：

rea/ ├─ index.html ├─ app.js ├─ style.css ├─ docs/ │ ├─ recent.log │ └─ archive/ └─ assets/ └─ icon.svg

启动方式也只需一条命令。我用的是系统自带的 Python 静态服务，在目录下直接运行python3 -m http.server 8010，然后打开本地地址即可。之所以用8010，是为了避开开发时常见端口被占用的麻烦。如果你电脑上有其他环境，也可以换成任意静态文件服务器，这版没有后端逻辑，纯前端跑通是最大目标。

从目录结构能看出，我没有一开始就设计复杂的插件系统和模块目录。所有脚本放在一个app.js里，逻辑分段靠注释和函数划分。等写到后面，我发现单文件脚本的好处：不会产生循环引用，调试时打开文件就能看全貌，也很容易用浏览器自带的开发者工具逐步执行。如果要面向团队协作，这当然不是理想结构，但个人工具的早期阶段，少引入一层抽象就是少埋一个坑。

3.2 编辑器–保存–预览的闭环代码

第一版的核心可以浓缩成下面这段逻辑：监听输入、调度保存、解析预览、状态上报。我把它按事件流串起来，每条线只有一两个函数。

editor.addEventListener('input', () => { scheduleSave(); schedulePreview(); }); function schedulePreview() { if (previewTimer) clearTimeout(previewTimer); previewTimer = setTimeout(() => { preview.innerHTML = renderPreview(editor.value); }, 200); } async function saveSnapshot(text) { const stamp = { time: Date.now(), content: text }; const list = await readLocalSnapshots(); list.push(stamp); if (list.length > 50) list.shift(); await writeLocalSnapshots(list); updateStatus(); }

让我把这几个函数讲清楚。scheduleSave负责把自动保存聚合成 300 毫秒的节奏；schedulePreview也做了防抖，避免每次输入都立刻触发预览；saveSnapshot则维护一个环形快照列表，只保留最近 50 条，既保证能找回半小时内的误删内容，又不会让存储区无限膨胀。这些参数都是我实测后定的：50 条快照对写作场景足够；快照之间如果相隔太久，恢复价值会降低。

写到这里你会发现，rea 并没有高深逻辑，它就是把“编辑、存储、预览”三件事调度好。这个阶段最大的经验，不是写出精巧代码，而是保持每条任务链路单一。比如预览函数只负责预览，保存函数只负责保存，互不调用。这样后来改预览逻辑时，不会牵连保存逻辑，改动范围一下子小了很多。

3.3 手感调优：我把哪些延迟砍掉了

第一版能跑之后，明显感觉“能用但不够顺”，主要有三个延迟点：预览更新慢、自动保存时页面卡顿、标签页切换后恢复慢。我针对三点分别处理。

预览更新慢主要是因为全量解析。我在上一节已经讲到切块渲染，这里补充一个细节：切块并不按固定字数切，而是按段落切。段落是语义完整的单位，段内变动只更新该段；如果整篇拆成固定 100 字一块，跨块的改动很容易导致两三个块同时刷新，优化效果会打折。

自动保存时页面卡顿是因为本地存储写入大文本时需要序列化。数组里保存了 50 条快照，每次序列化都可能产生几百 KB 甚至上 MB 的字符串。解决方案是把快照分成两条队列：一条只存摘要和位置，一条存完整内容；真正写入完整内容时，采用异步执行，不占用主线程的输入等待。做完这个调整后，连续输入时基本不再出现光标跳动。

标签页切换后恢复慢的问题，来自页面加载时同步读取快照列表。快照多了以后读取也要时间。我的办法是首次只读最近一条快照用于恢复，完整列表延迟到界面渲染完成后再异步读取。这样打开 rea 时几乎瞬间就能看到上次内容，后台再补齐索引。用户感知是“秒开”，技术原理不过是把重活推迟了半秒。

4. 踩坑实录：六个调了一晚上的问题

4.1 最后一段文字总是不见

使用中第一次严重事故是：关掉页面重新打开，最后一百字失踪了。排查了很久才发现，用户按下关闭按钮时，输入事件触发了防抖保存，但由于页面同时开始卸载，异步保存还没完成就被浏览器终止。我的修复方案前面提到过：监听beforeunload，在卸载前同步完成保存，必要时改用同步写接口。这里要提醒一句，同步写会阻塞页面一小会，但写一段文本的时间通常只有几毫秒，完全值得为可靠性牺牲这点性能。

4.2 中文输入法把撤销栈搅乱

第二个问题只出现在中文输入场景。使用拼音或五笔输入法时，选词过程会触发多个连续的输入事件，每次事件都被当成了独立编辑操作，结果按一次撤销可能只撤销了一个拼音字母，而不是一个词。我当时差点怀疑是浏览器的问题，后来意识到必须处理中文输入法的组合态。

解决办法是监听compositionstart和compositionend事件。输入法开始组合文字时，暂停自动保存和预览刷新；组合结束后，再统一触发一次保存与预览。这样既能保证中文输入不被切成碎片，也不会把组合过程里的中间状态写进快照。如果你做任何面向中文用户的在线编辑类工具，这个细节早晚会用到。

4.3 外部文件修改与界面不同步

还有一次，我在文件夹里用另一个工具改完文档，回头发现 rea 预览里还是旧内容。我最初怀疑轮询逻辑坏了，后来看到日志才意识到，轮询扫描的是“文件修改时间”，但另一个工具保存时没有更新修改时间，只有内容变了。这个现象有些罕见，但确实存在。

我调整思路，增加大小和内容摘要的双重校验：如果文件大小变了，直接重载；如果大小没变，再取内容哈希比对，哈希不一致也重载。这样不依赖修改时间，兼容了更多外部编辑器。代价是轮询时会多读一次文件内容，但由于文档通常不大，整体开销可以接受。

4.4 常见问题速查表

我把遇到的典型问题整理成一张表，排查时可以直接对照：

表格里的第一行是我最常遇到的，基本可以成为本地编辑类工具的标准配置：只要目标定位是“不丢内容”，页面前必须设置卸载兜底。后面几行则可以在功能迭代时逐个补齐，不必一开始就全部实现。

5. 后续可以怎么扩展（按性价比排序）

5.1 全文检索：先解决“找得到”

rea 目前只有简单的快照恢复，没有真正意义上的搜索功能。随着文档数量和快照数量增长，“找得到”会变得比“写得多”更重要。我计划优先加入全文检索，而不是做复杂的倒排索引，先做临时方案：关键词切分后按行扫描，结果按匹配行数和时间权重排序。只有一次扫描超过几百毫秒，再优化成增量索引。这个顺序是从真实使用场景来的，毕竟个人笔记的数据量还没到必须上搜索引擎的程度。

5.2 导出与加密备份

本地优先工具最容易被人担心的一个点是数据丢失。硬盘坏了、浏览器存储区被清空，内容可能一夜之间消失。所以我现在把导出和备份当成刚需来设计。默认提供一个“导出全文”按钮，输出时间戳命名的纯文本文件；同时提供一个稍重的压缩导出，把全部快照打包并带上校验值。如果后续要做加密，我倾向于使用成熟的标准算法库，不自己造轮子，因为加密协议非常容易出问题。

5.3 命令面板与插件位

等核心功能稳定后，我会给 rea 加一个命令面板入口，支持通过快捷键唤起，做“跳转到某次快照”“导出全文”“切换预览样式”这类操作。命令面板的本质是把高频操作从菜单层级里解放出来，减少鼠标移动，对纯键盘流用户尤其友好。至于插件位，我的想法是先把核心模块接口沉淀清晰，比如让“解析引擎”和“保存策略”可以被外部覆盖，之后再做开放扩展。

5.4 一个更克制的方向：移动端续写

虽然是本地优先工具，但如果能利用浏览器在手机上打开同一个地址，做“临时补充一句话”也能增加不少价值。移动端的方案不是复刻完整编辑器，而是提供一个极简入口：只能追加文本，不能大段编辑，避免手机键盘和中文输入法把体验拖垮。这样同样的存储结构，保持本地优先，又不至于为了移动端重写一遍交互。

如果让我定一条 rea 的开发原则，最后想说的其实是这个：小工具的边界比功能更重要。我见过太多项目因为不断增加按钮、接入第三方服务、兼容各种格式而变得臃肿，最终连最初的“打开即写”都做不到了。rea 能一直保持简洁，靠的是每次加功能前都先问一句：这个功能会不会让启动变慢，会不会引入新的安全风险，会不会让数据备份更麻烦。这三大约束同时满足，我才会把它放进开发队列。实际操作中，这样砍掉的点子远比保留下来的多，但留下来的每一个都经得起长期使用。