作为一名长期与 Markdown 打交道的开发者你是否曾因网络波动而丢失过未保存的文档是否在多个设备间同步笔记时为版本冲突和云端延迟而烦恼如果你追求一种更可靠、更私密、更快速的写作体验那么“Local-first”本地优先理念下的桌面 Markdown 编辑器或许正是你寻找的答案。本文将深入探讨这一理念并以一个具体的项目——Writer.computer为例为你完整拆解如何从零开始构建一个属于自己的、真正以本地为核心的桌面 Markdown 编辑器。无论你是前端新手想了解现代桌面应用开发还是资深开发者希望探索离线优先架构这篇文章都将提供从概念到实战的完整路径。1. 背景与核心概念为什么需要 Local-first 编辑器在深入代码之前我们必须先理解驱动这个项目的核心理念。这决定了我们为何要选择特定的技术栈和架构而不仅仅是“做一个编辑器”。1.1 什么是 Local-first SoftwareLocal-first software是一种软件设计范式其核心原则是数据的所有权和首要副本始终存储在用户的本地设备上。这与我们熟知的“云端优先”或“纯本地”应用有本质区别。云端优先 (Cloud-first): 如 Google Docs、Notion。数据主要存储在远程服务器本地只是一个“视图”或缓存。没有网络功能严重受限。纯本地 (Local-only): 如传统的记事本、早期版本的 Word。数据完全在本地缺乏协作和跨设备同步能力。本地优先 (Local-first): 结合了两者优点。数据首先在本地创建、编辑和保存保证极致的响应速度和离线可用性。然后通过一种对等同步的机制在后台与其他设备或可选的服务器同步数据实现协作和多端一致。Local-first 的七大理想特性由 Ink Switch 研究实验室提出包括即时响应、离线优先、多设备同步、用户数据所有权、长期可用性、隐私安全、协作支持。Writer.computer 这类编辑器正是这一理念在文本编辑领域的具体实践。1.2 Markdown 编辑器的现状与痛点Markdown 因其简洁和高效已成为程序员、写作者、知识管理者的首选格式。市面上的编辑器众多如 Typora、VS Code、Obsidian 等它们各有侧重Typora: 优秀的所见即所得体验但同步依赖第三方网盘。VS Code: 功能强大通过插件可实现 Markdown 预览但本质是代码编辑器。Obsidian: 基于本地纯文本文件插件生态丰富双链笔记强大其“本地优先”特性非常突出。然而许多在线或混合型编辑器仍存在痛点网络依赖性强、数据隐私存疑、同步冲突复杂、历史版本管理不便。一个真正的 Local-first 桌面 Markdown 编辑器旨在从根本上解决这些问题提供一个快速、私密、可靠、用户完全掌控的写作环境。1.3 Writer.computer 项目定位根据项目标题和相关信息Writer.computer可以被理解为一个践行 Local-first 理念的桌面端 Markdown 编辑器项目。它很可能具备以下特征桌面应用使用 Electron、Tauri 或类似框架构建提供原生应用体验。Markdown 核心支持实时预览、语法高亮、常用快捷键。Local-first 架构文件默认保存在本地文件系统编辑操作无延迟。可选同步可能集成对等同步如 WebRTC或通过用户自建服务器同步而非强制绑定中心化云服务。数据格式开放使用.md等纯文本格式避免锁死在专有格式中。接下来我们将从零开始构建一个具备这些核心特性的简易版桌面 Markdown 编辑器。2. 环境准备与版本说明我们将选择现代且高效的技术栈来构建这个应用。前端框架: React 18 TypeScript - 用于构建用户界面类型安全。桌面框架: Tauri - 一个比 Electron 更轻量、更安全的构建桌面应用的工具链。它使用 Rust 构建核心前端使用 Web 技术。我们选择它是因为其更小的打包体积和更好的性能。UI 组件库: 为了快速搭建我们使用shadcn/ui配合 Tailwind CSS它提供美观且可访问的组件。Markdown 渲染:react-markdown配合remark-gfm(支持 GitHub Flavored Markdown) 和rehype-highlight(代码高亮)。编辑器组件: 我们将使用uiw/react-md-editor这是一个功能丰富的 React Markdown 编辑器组件支持自定义工具栏和预览。本地文件操作: Tauri 提供了强大的原生文件系统 API (tauri-apps/api/fs)。开发环境:Node.js (推荐 LTS 版本如 18.x 或 20.x)Rust 工具链 (Tauri 依赖)pnpm (包管理器更快更节省磁盘)IDE: VS Code 或 WebStorm版本说明以下示例代码基于 Tauri 2.0 稳定版、React 18 和 TypeScript 5.x。请注意依赖库版本更新较快具体版本号请以创建项目时的最新稳定版为准核心配置思路不变。3. 核心架构与原理拆解在动手编码前理解应用如何组织是至关重要的。3.1 应用架构图概念层级[用户界面层 (React)] | | (状态更新事件触发) v [业务逻辑层 (React Hooks / Context)] | [后端核心层 (Tauri/Rust)] |--- 处理编辑器状态、UI交互 ---| |--- 文件“读取”请求 -----------| --- 操作系统文件系统 |--- 文件“保存”请求 -----------| |--- 文件内容/状态 ------------| |--- 操作结果/错误 ------------|前端 (React): 负责渲染编辑器界面、预览面板、文件树并处理用户的所有交互事件。状态管理: 使用 React Context 或 Zustand 等轻量库管理全局状态如当前打开的文件路径、文件内容、编辑模式、主题等。通信桥梁 (Tauri): Tauri 在 Rust 后端和 Web 前端之间建立了一个安全、类型化的通信通道。前端通过调用invoke函数来请求后端执行特权操作如读写文件。后端 (Rust): 通过 Tauri 的命令#[tauri::command]暴露安全的 API 给前端执行所有文件 IO 操作。这是安全性的关键网页前端无法直接访问文件系统。3.2 Local-first 数据流打开文件: 用户点击“打开” - 前端调用 Tauri 命令 - Rust 读取本地.md文件 - 返回内容给前端 - 前端更新编辑器状态。编辑内容: 用户在编辑器内输入 - 前端状态实时更新内存中-自动保存或手动保存时将最新内容通过 Tauri 命令写回原文件。保存策略: 实现“自动保存”和“手动保存”双机制。自动保存可以设置防抖例如每2秒或内容停止变化后1秒将内容同步到本地。这确保了即使应用崩溃数据损失也极小。同步考量进阶: 真正的 Local-first 同步是复杂的。一个简化思路是每次本地文件保存后生成一个哈希值如 SHA-256并通过一个可选的后台进程将变更同步到用户指定的其他位置如另一台设备的监听文件夹、或用户自己的 WebDAV 服务器。冲突解决可以采用“最后写入获胜”或更复杂的操作转换OT算法。本文主要聚焦于本地优先的单机核心体验。4. 完整实战构建 Writer.computer 基础版让我们开始一步步搭建项目。4.1 创建项目并初始化结构首先使用 Tauri 的官方模板创建项目。打开终端执行以下命令# 使用 pnpm 和 Tauri 官方模板创建项目 pnpm create tauri-applatest writer-computer # 根据提示进行选择 # ✔ Project name · writer-computer # ✔ Choose which language to use for your frontend · TypeScript / JavaScript - (pnpm, yarn, npm, bun) # ✔ Choose your package manager · pnpm # ✔ Choose your UI template · React - (https://react.dev/) # ✔ Choose your UI flavor · TypeScript # ✔ Where to store the frontend source code? · src # ✔ Where to store the assets? · public # ✔ Where to store the Tauri source code? · src-tauri # ✔ What is the app identifier? · com.writer.computer # ✔ Window title · Writer Computer # 进入项目目录 cd writer-computer # 安装前端依赖Tauri 创建时可能已安装这里确保 UI 库和编辑器组件 pnpm add uiw/react-md-editor react-markdown remark-gfm rehype-highlight pnpm add -D types/react-markdown # 安装 shadcn/ui (按照其官方文档初始化这里以手动添加按钮组件为例) pnpm add tailwindcss postcss autoprefixer pnpm dlx shadcnlatest init # 初始化 Tailwind按提示选择 pnpm dlx tailwindcss init -p # 添加一个按钮组件 pnpm dlx shadcnlatest add button4.2 配置 Tailwind CSS 与基础布局更新tailwind.config.js以包含必要的文件路径// tailwind.config.js /** type {import(tailwindcss).Config} */ export default { content: [ ./index.html, ./src/**/*.{js,ts,jsx,tsx}, ], theme: { extend: {}, }, plugins: [], }修改src/App.css或src/index.css为 Tailwind 指令/* src/index.css */ tailwind base; tailwind components; tailwind utilities;创建应用的基础布局组件src/components/Layout.tsx// src/components/Layout.tsx import React from react; import { Button } from /components/ui/button; import { FileText, Save, FolderOpen } from lucide-react; interface LayoutProps { children: React.ReactNode; onSave?: () void; onOpen?: () void; fileName?: string; } const Layout: React.FCLayoutProps ({ children, onSave, onOpen, fileName }) { return ( div classNameflex flex-col h-screen bg-background text-foreground {/* 顶部标题栏 */} header classNameborder-b px-4 py-2 flex items-center justify-between div classNameflex items-center gap-2 FileText classNameh-5 w-5 / h1 classNamefont-semiboldWriter Computer/h1 {fileName span classNametext-sm text-muted-foreground ml-4- {fileName}/span} /div div classNameflex items-center gap-2 Button variantoutline sizesm onClick{onOpen} FolderOpen classNamemr-2 h-4 w-4 / 打开 /Button Button sizesm onClick{onSave} Save classNamemr-2 h-4 w-4 / 保存 /Button /div /header {/* 主内容区 */} main classNameflex-1 overflow-hidden {children} /main {/* 底部状态栏 */} footer classNameborder-t px-4 py-1 text-xs text-muted-foreground flex justify-between spanLocal-First Markdown Editor/span spanReady/span /footer /div ); }; export default Layout;4.3 实现 Tauri 后端命令文件读写这是实现 Local-first 的核心所有文件操作通过后端完成。编辑src-tauri/src/main.rs文件// src-tauri/src/main.rs #![cfg_attr(not(debug_assertions), windows_subsystem windows)] use tauri::Manager; use std::fs; use std::path::PathBuf; // 学习这是一个 Tauri 命令暴露给前端调用。 // #[tauri::command] 宏将其标记为一个可调用端点。 // invoke(‘read_file’, { path: ‘...’ }) 会触发此函数。 #[tauri::command] fn read_file(path: String) - ResultString, String { // 注意这里进行了简单的错误处理将 IO 错误转换为字符串错误信息返回给前端。 fs::read_to_string(path).map_err(|e| e.to_string()) } #[tauri::command] fn write_file(path: String, contents: String) - Result(), String { // 重要在实际项目中这里应该增加更多安全检查例如路径合法性校验、防止目录遍历攻击。 fs::write(path, contents).map_err(|e| e.to_string()) } #[tauri::command] async fn open_file_dialog(window: tauri::Window) - ResultOptionString, String { // 使用 Tauri 的对话框 API 打开文件选择器 let file_path tauri::api::dialog::FileDialogBuilder::new() .add_filter(Markdown, [md, markdown]) .add_filter(Text, [txt]) .add_filter(All Files, [*]) .pick_file() .await .map(|path_buf| path_buf.to_string_lossy().into_owned()); Ok(file_path) } fn main() { tauri::Builder::default() // 在这里注册我们定义的命令这样前端才能调用到。 .invoke_handler(tauri::generate_handler![read_file, write_file, open_file_dialog]) .run(tauri::generate_context!()) .expect(error while running tauri application); }4.4 构建前端编辑器页面这是应用的主体。修改src/App.tsx// src/App.tsx import React, { useState, useEffect, useCallback } from react; import Layout from ./components/Layout; import MDEditor from uiw/react-md-editor; import ReactMarkdown from react-markdown; import remarkGfm from remark-gfm; import rehypeHighlight from rehype-highlight; import highlight.js/styles/github.css; // 代码高亮样式 import { invoke } from tauri-apps/api/tauri; import { listen } from tauri-apps/api/event; import { open } from tauri-apps/api/dialog; import { message } from tauri-apps/api/dialog; // 定义文件状态接口 interface FileState { path: string | null; content: string; isDirty: boolean; // 标记内容是否已修改未保存 } function App() { // 状态管理当前文件路径、内容、编辑模式、脏标记 const [fileState, setFileState] useStateFileState({ path: null, content: # Welcome to Writer Computer\n\nStart writing your **Local-First** Markdown here..., isDirty: false, }); const [viewMode, setViewMode] useStateedit | preview | split(split); // 学习使用 useCallback 记忆化函数避免不必要的重渲染 const handleEditorChange useCallback((value?: string) { setFileState(prev ({ ...prev, content: value || , isDirty: true, // 内容变化标记为脏 })); }, []); // 打开文件 const handleOpenFile useCallback(async () { try { // 调用我们定义的 Rust 命令 open_file_dialog const selectedPath: string | null await invoke(open_file_dialog); if (!selectedPath) return; // 用户取消了选择 // 调用 Rust 命令 read_file 读取内容 const content: string await invoke(read_file, { path: selectedPath }); setFileState({ path: selectedPath, content, isDirty: false, }); await message(Opened: ${selectedPath.split(/).pop()}, { title: Writer Computer, type: info }); } catch (error) { console.error(Failed to open file:, error); await message(Error: ${error}, { title: File Open Failed, type: error }); } }, []); // 保存文件 const handleSaveFile useCallback(async () { if (!fileState.path) { // 如果文件没有路径新文件先让用户选择保存位置 const savePath await open({ directory: false, multiple: false, filters: [{ name: Markdown, extensions: [md] }], title: Save Markdown File, }); if (!savePath || Array.isArray(savePath)) return; setFileState(prev ({ ...prev, path: savePath as string })); // 注意这里需要递归调用自身或者将保存逻辑提取出来。为了清晰我们简化处理。 // 更优解是提取一个 saveToPath 函数。 const finalPath savePath as string; try { await invoke(write_file, { path: finalPath, contents: fileState.content }); setFileState(prev ({ ...prev, isDirty: false })); await message(Saved to: ${finalPath.split(/).pop()}, { title: Writer Computer, type: info }); } catch (error) { await message(Save failed: ${error}, { title: Error, type: error }); } return; } // 已有路径直接保存 try { await invoke(write_file, { path: fileState.path, contents: fileState.content }); setFileState(prev ({ ...prev, isDirty: false })); // 可以给用户一个简单的反馈这里使用 Tauri 的对话框 await message(Saved!, { title: Writer Computer, type: info }); } catch (error) { console.error(Failed to save file:, error); await message(Save failed: ${error}, { title: Error, type: error }); } }, [fileState.path, fileState.content]); // 自动保存逻辑简易防抖实现 useEffect(() { if (!fileState.isDirty || !fileState.path) return; const timer setTimeout(() { console.log(Auto-saving...); invoke(write_file, { path: fileState.path, contents: fileState.content }).catch(console.error); // 注意自动保存后我们可能不想清除 isDirty 标记因为用户可能继续编辑。 // 或者可以设置一个“最后自动保存时间”的状态。 }, 2000); // 2秒防抖 return () clearTimeout(timer); }, [fileState.content, fileState.isDirty, fileState.path]); // 监听 Tauri 事件例如窗口关闭前提示保存 useEffect(() { const unlisten listen(tauri://close-requested, async (event) { if (fileState.isDirty) { const confirmed await message(You have unsaved changes. Are you sure you want to exit?, { title: Writer Computer, type: warning, buttons: [Yes, No], }); if (!confirmed) { // 阻止关闭 event.preventDefault(); } } }); return () { unlisten.then(f f()); }; }, [fileState.isDirty]); // 提取文件名用于显示 const currentFileName fileState.path ? fileState.path.split(/[\\/]/).pop() : Untitled; return ( Layout onSave{handleSaveFile} onOpen{handleOpenFile} fileName{${currentFileName}${fileState.isDirty ? * : }} div classNameflex h-full {/* 模式切换工具栏 */} div classNameabsolute top-14 left-1/2 transform -translate-x-1/2 z-10 flex gap-1 bg-background/80 backdrop-blur-sm rounded-md border p-1 {([edit, split, preview] as const).map((mode) ( button key{mode} className{px-3 py-1 text-sm rounded-sm transition-colors ${viewMode mode ? bg-primary text-primary-foreground : hover:bg-muted}} onClick{() setViewMode(mode)} {mode.charAt(0).toUpperCase() mode.slice(1)} /button ))} /div {/* 编辑器与预览面板 */} div classNameflex flex-1 {/* 编辑面板 */} {(viewMode edit || viewMode split) ( div className{h-full ${viewMode split ? w-1/2 border-r : w-full}} MDEditor value{fileState.content} onChange{handleEditorChange} height100% visibleDragbar{false} previewedit / /div )} {/* 预览面板 */} {(viewMode preview || viewMode split) ( div className{h-full overflow-y-auto p-6 ${viewMode split ? w-1/2 : w-full}} div classNameprose prose-slate dark:prose-invert max-w-none ReactMarkdown remarkPlugins{[remarkGfm]} rehypePlugins{[rehypeHighlight]} {fileState.content} /ReactMarkdown /div /div )} /div /div /Layout ); } export default App;4.5 运行与验证启动开发模式在项目根目录下运行pnpm tauri dev这将同时启动前端开发服务器和 Tauri 应用窗口。你应该能看到一个带有编辑器、预览区和顶部工具栏的桌面应用。测试文件操作点击“打开”按钮选择一个已有的.md文件。内容应加载到编辑器中。在编辑器中修改内容顶部文件名旁会出现*号表示未保存。点击“保存”按钮文件将被写回磁盘*号消失。你也可以在文件系统中验证文件已被更新。尝试不保存直接关闭窗口会弹出警告对话框。构建生产版本开发完成后可以构建分发版本pnpm tauri build构建产物位于src-tauri/target/release/目录下根据你的操作系统生成可执行文件或安装包。5. 常见问题与排查思路在开发和使用过程中你可能会遇到以下问题问题现象可能原因排查与解决思路pnpm tauri dev启动失败Rust 相关错误1. Rust 工具链未安装或版本不匹配。2. 系统依赖缺失如 Windows 上的 Microsoft Visual C 构建工具。1. 运行rustc --version检查 Rust 安装。使用rustup update更新。2. 参考 Tauri 官方安装指南 安装所有系统依赖。前端 React 服务器启动但 Tauri 窗口白屏或报错1. 前端资源加载失败。2. Tauri 通信配置错误。3. 防病毒软件或防火墙拦截。1. 检查终端日志看前端服务器是否正常启动通常为http://localhost:1420。2. 检查tauri.conf.json中的build.devUrl是否正确指向前端地址。3. 暂时禁用安全软件测试。“打开/保存”文件对话框不弹出1. Tauri 的对话框 API 调用错误。2. 前端invoke调用路径错误。3. macOS 权限问题如没有权限访问目录。1. 检查 Rust 命令open_file_dialog是否正确定义并注册到invoke_handler。2. 在前端代码中检查invoke的函数名是否与后端完全一致。3. 在 macOS 的“系统设置-隐私与安全性-文件和文件夹”中为你的应用或终端授予权限。保存文件时提示“Permission Denied”1. 尝试写入受保护的系统目录。2. 文件被其他进程锁定。3. 应用没有足够的用户权限。1. 避免保存到C:\Windows、/System等目录。建议默认保存到用户文档目录。2. 关闭可能占用该文件的程序。3. 以管理员/root身份运行应用不推荐应改进代码逻辑。自动保存功能过于频繁导致性能问题防抖时间设置过短或每次输入都触发保存。优化防抖逻辑例如只在用户停止输入一段时间后如 1.5 秒或内容变化量较大时触发保存。使用useRef存储定时器。Markdown 预览样式错乱或代码不高亮1. CSS 样式未正确引入。2.rehype-highlight语言检测失败。1. 确认highlight.js的 CSS 文件已导入如import ‘highlight.js/styles/github.css‘。2. 在代码块上指定语言如javascript。检查rehypeHighlight插件是否正确配置。应用打包后体积过大默认的 Tauri 打包包含了整个 WebView 运行时。这是 Tauri 相比 Electron 的优势之一体积已经小很多。可以进一步通过配置tauri.conf.json中的bundle选项排除不必要的资源或使用upx压缩二进制文件。6. 最佳实践与工程建议将基础版本打造成一个健壮、可维护的 Local-first 编辑器还需要考虑以下方面6.1 状态管理与数据持久化使用 Zustand 或 Jotai当应用功能增多如多标签页、主题设置、用户偏好时考虑使用更专业的状态管理库。它们更适合 Tauri React 的架构。持久化用户设置使用 Tauri 的pathAPI 获取应用配置目录如app_local_data_dir将用户设置主题、字体大小、自动保存间隔以 JSON 格式保存到本地文件。可以使用tauri-plugin-store官方插件简化此过程。编辑历史与撤销/重做为编辑器内容实现一个简单的命令历史栈。每次内容变化时不是直接覆盖而是将快照压入栈中。这比依赖编辑器的内置历史更可控。6.2 文件与 IO 安全路径安全校验在 Rust 后端对所有传入的文件路径进行规范化std::fs::canonicalize和校验防止目录遍历攻击如../../../etc/passwd。文件锁对于可能的多进程访问场景虽然不常见可以考虑实现简单的文件锁机制防止同时写入导致数据损坏。备份与版本实现自动备份功能。每次保存前将旧文件复制到一个备份目录如.backups并加上时间戳。这提供了简单的本地版本控制。6.3 性能与用户体验虚拟化长文档列表如果实现文件管理器侧边栏当文件数量巨大时使用react-virtualized或tanstack-virtual进行虚拟滚动。编辑器性能对于超大的 Markdown 文件1MB纯文本编辑可能仍会卡顿。考虑将编辑器组件替换为基于 CodeMirror 或 Monaco Editor 的专门 Markdown 模式它们对大型文件优化更好。离线指示器虽然我们是 Local-first但若集成了同步功能需要一个清晰的 UI 指示器显示网络连接状态和同步状态。6.4 同步功能进阶Local-first 精髓选择同步协议真正的 Local-first 同步推荐使用CRDT (Conflict-Free Replicated Data Type)或操作转换 (OT)。对于文本有成熟的库如automerge、yjs。集成这些库可以实现在多设备间无冲突地合并更改。传输层可以使用 WebRTC 进行点对点直连同步或通过用户自己控制的服务器使用 WebSocket进行中继。Tauri 支持 WebRTC。同步策略设计为“手动触发”或“间隔同步”避免实时同步对性能和流量的影响。首次同步时需要处理整个文档的合并。6.5 生产环境部署代码签名为 macOS 和 Windows 的可执行文件进行代码签名否则用户首次打开时会看到安全警告。自动更新集成 Tauri 的自动更新插件 (tauri-plugin-updater)方便后续推送功能更新和漏洞修复。日志系统在生产版本中集成日志记录如tracing库将错误和警告记录到本地文件方便用户反馈问题。构建一个完整的 Local-first 应用是一个持续的工程。本文提供了一个坚实的地基——一个真正将数据存储在本地、响应迅速的桌面 Markdown 编辑器。你可以在此基础上根据上述最佳实践逐步添加文件管理、搜索替换、图表渲染、同步等高级功能最终打造出一个完全符合你工作流、真正尊重你数据主权的写作工具。
