基于Vue 3与Electron构建本地优先的Markdown知识管理工具

1. 项目概述从零开始构建一个轻量级个人知识管理工具最近在整理自己的学习笔记和工作文档时发现了一个普遍存在的痛点市面上的笔记软件要么功能过于臃肿干扰了纯粹的记录与思考要么过于封闭数据难以自由迁移和深度定制。作为一个有十多年经验的开发者我决定不再妥协动手为自己打造一个代号为“9pts/copaw1”的轻量级个人知识管理工具。这个名字听起来有点神秘其实“9pts”代表我对工具核心特性的九点要求而“copaw1”则是我个人项目的一个习惯性代号。这个工具的核心目标非常明确它必须极简、快速、完全由我掌控数据并且能够无缝衔接我的Markdown写作流。这个项目不是为了替代Notion或Obsidian这类功能强大的成熟产品而是为了解决一个更聚焦的需求当我需要快速捕捉灵感、整理单向的知识脉络或是撰写一篇技术博客的草稿时我希望有一个毫无干扰、启动迅速、并且文件就静静躺在本地文件夹里的工具。它应该像一个数字化的“便签纸”但具备一定的组织能力和渲染预览功能。如果你也厌倦了在复杂软件中配置各种插件和数据库或者担心云端服务的隐私与可持续性那么跟随我一起从零构建这样一个工具会是一次非常有益的实践。它不仅能让你的数字生活更清爽更能让你深入理解一个现代Web应用从设计到实现的完整链条。2. 核心设计思路与技术选型2.1 明确九点核心需求9pts在动手写第一行代码之前明确需求是至关重要的一步。我为自己列出的“9pts”需求清单构成了整个项目的设计基石纯本地优先所有数据以Markdown文件的形式存储在用户指定的本地文件夹中无需网络无需账户同步。极速启动与响应应用本身需要轻量启动时间应在秒级以内任何操作打开、编辑、保存都应有即时反馈。双栏Markdown编辑器左侧为纯文本编辑区右侧为实时渲染预览区这是高效Markdown写作的黄金布局。无干扰的极简界面界面元素尽可能少聚焦于编辑区域提供全屏写作模式。文件树导航在侧边栏清晰展示本地知识库的目录结构支持快速创建、重命名、删除文件和文件夹。基础搜索功能支持对当前知识库内所有Markdown文件进行全文搜索并高亮显示结果。主题切换至少提供浅色和深色两种视觉主题以适应不同环境下的写作需求。导出与备份支持将单篇文章或整个知识库以纯净的Markdown文件格式导出便于备份和迁移。技术栈可控且现代使用我熟悉且社区活跃的技术栈便于后期维护和功能扩展。这九点需求没有一项是追求“大而全”的它们共同指向了“专注”与“控制”。基于这份清单技术选型的方向就非常清晰了。2.2 技术栈选型与理由为了实现上述需求我选择了以下技术组合前端框架Vue 3 TypeScript理由Vue 3的Composition API非常适合构建这种交互复杂但模块清晰的桌面应用。TypeScript能提供良好的类型提示减少开发阶段的低级错误尤其是在处理文件系统路径、状态管理等场景时类型安全至关重要。其响应式系统也能轻松驱动双栏预览的实时更新。UI框架无主流UI库采用自制组件理由为了追求极致的轻量与定制化避免引入Element Plus或Ant Design Vue等大型UI库。它们虽然功能丰富但会带来不必要的体积和默认样式干扰。本项目界面简单所需的按钮、输入框、树形控件等完全可以从零开始构建或基于Headless UI组件库如headlessui/vue仅封装逻辑样式完全自定义。这能确保最终的应用程序包最小界面风格百分百符合“无干扰”的设计语言。构建工具与桌面运行时Vite Electron理由Vite提供了极快的开发服务器启动和热更新体验与Vue 3是绝配。Electron则允许我们使用Web技术来构建跨平台的桌面应用并赋予其访问本地文件系统的能力这是实现“纯本地”核心需求的关键。虽然Electron应用体积相对较大但通过精心优化依赖和构建配置可以将其控制在可接受范围内。核心功能库Markdown渲染Marked.js 或 VitePress的Markdown处理链理由Marked.js轻量且速度快适合基础的Markdown转HTML。但如果需要更丰富的扩展如自定义容器、语法高亮等可以借鉴VitePress的配置它基于markdown-it插件生态丰富。本项目初期选择Marked.js后期根据需求再考虑升级。文件树与搜索Node.jsfs模块 fuse.js理由文件树的生成和操作直接通过Electron暴露的Node.jsfs模块完成。对于全文搜索fuse.js是一个强大的、轻量级的模糊搜索库它可以在浏览器端对文件内容进行索引和搜索避免频繁的磁盘IO实现快速搜索体验。状态管理Pinia理由Vue官方的状态管理库比Vuex更简洁且完美支持Composition API。适合管理应用全局状态如当前打开的文件内容、知识库路径、UI主题等。注意技术选型没有绝对的对错只有是否适合当前场景。这里的选择是基于“快速实现一个可控、可维护的MVP最小可行产品”的目标。如果追求更小的打包体积可以考虑Tauri替代Electron如果追求极致的渲染性能可以评估Solid.js。但对于一个个人工具在熟悉度和开发效率上取得平衡是关键。3. 项目架构与核心模块实现3.1 项目初始化与基础工程配置首先我们使用Vite官方模板快速搭建一个Vue-TS项目并集成Electron。# 创建Vue项目 npm create vitelatest copaw1-editor -- --template vue-ts cd copaw1-editor # 安装Electron相关依赖 npm install electron electron-builder concurrently wait-on cross-env -D接下来调整package.json中的脚本以支持开发时同时启动Vite开发服务器和Electron主进程。{ scripts: { dev: concurrently -k \npm run dev:vite\ \npm run dev:electron\, dev:vite: vite, dev:electron: wait-on tcp:5173 cross-env NODE_ENVdevelopment electron ., build: npm run build:vite npm run build:electron, build:vite: vite build, build:electron: electron-builder, preview: vite preview } }然后在项目根目录创建Electron的主进程文件main.js或main.ts。它的核心职责是创建应用窗口并加载Vite开发服务器的URL开发环境或打包后的本地文件生产环境。同时我们需要在这里定义一些安全的IPC进程间通信通道让渲染进程我们的Vue应用可以请求主进程执行文件读写等敏感操作。关键点Electron的安全策略要求渲染进程网页默认不能直接使用Node.js的fs模块。我们必须通过contextBridge在预加载脚本preload.js中暴露有限的、安全的API给渲染进程然后渲染进程通过IPC调用这些API。这是Electron开发中最重要的一环能有效防止安全漏洞。3.2 核心模块文件系统访问与IPC通信这是整个应用的基石。我们在预加载脚本中定义并暴露一个名为electronAPI的对象给渲染进程。// preload.js const { contextBridge, ipcRenderer } require(electron); contextBridge.exposeInMainWorld(electronAPI, { // 读取目录 readDir: (path) ipcRenderer.invoke(read-dir, path), // 读取文件内容 readFile: (path) ipcRenderer.invoke(read-file, path), // 写入文件内容 writeFile: (path, content) ipcRenderer.invoke(write-file, path, content), // 创建文件/文件夹 createEntry: (path, type) ipcRenderer.invoke(create-entry, path, type), // 删除文件/文件夹 deleteEntry: (path) ipcRenderer.invoke(delete-entry, path), // 重命名/移动 renameEntry: (oldPath, newPath) ipcRenderer.invoke(rename-entry, oldPath, newPath), // 打开系统对话框选择文件夹用于设置知识库路径 selectDirectory: () ipcRenderer.invoke(select-directory), });在主进程中我们需要实现这些IPC事件的处理函数。以readDir为例// main.js (部分) const { ipcMain, dialog } require(electron); const fs require(fs).promises; const path require(path); ipcMain.handle(read-dir, async (event, dirPath) { try { const items await fs.readdir(dirPath, { withFileTypes: true }); return items.map(dirent ({ name: dirent.name, path: path.join(dirPath, dirent.name), type: dirent.isDirectory() ? directory : file, // 只处理.md文件 ext: path.extname(dirent.name) })).filter(item item.type directory || item.ext .md); } catch (error) { console.error(读取目录失败:, error); throw error; // 将错误抛回给渲染进程处理 } });实操心得在IPC通信中错误处理非常重要。主进程的异常必须通过Promise的reject或抛出错误的方式传递回渲染进程这样前端才能给用户友好的提示。同时对用户传入的路径参数一定要做安全校验防止目录遍历攻击。3.3 核心模块应用状态管理与知识库初始化在Vue渲染进程中我们使用Pinia来管理核心状态。首先创建一个useStore。// stores/editor.ts import { defineStore } from pinia; import { ref, computed } from vue; import type { FileTreeNode } from ../types; export const useEditorStore defineStore(editor, () { // 状态 const knowledgeBasePath refstring(); // 知识库根路径 const fileTree refFileTreeNode[]([]); // 文件树数据 const currentFile ref{ path: string; content: string } | null(null); // 当前打开的文件 const searchQuery ref(); // 搜索关键词 const theme reflight | dark(light); // 主题 // Getter const isDark computed(() theme.value dark); // Actions const setKnowledgeBasePath async (path: string) { knowledgeBasePath.value path; // 保存到本地存储下次启动时读取 localStorage.setItem(kb-path, path); await loadFileTree(path); // 加载文件树 }; const loadFileTree async (dirPath: string) { try { const tree await window.electronAPI.readDir(dirPath); // 这里需要将扁平列表转换为嵌套的树形结构涉及递归逻辑略 fileTree.value buildTreeStructure(tree, dirPath); } catch (error) { console.error(加载文件树失败:, error); // 触发UI提示 } }; // 其他action: openFile, saveFile, createFile等... return { knowledgeBasePath, fileTree, currentFile, searchQuery, theme, isDark, setKnowledgeBasePath, loadFileTree, // ... }; });应用启动时首先检查本地存储中是否有已设置的知识库路径。如果没有则引导用户选择一个文件夹。这个“首次设置”的流程体验很重要一个清晰的对话框和引导能降低用户的使用门槛。3.4 核心模块双栏编辑器的实现编辑器界面是整个应用的核心交互区域。我们将其拆分为三个主要组件Sidebar.vue侧边栏含文件树和搜索、EditorPane.vue左侧编辑区、PreviewPane.vue右侧预览区。EditorPane组件使用一个textarea或更专业的代码编辑器库如CodeMirror或Monaco Editor的轻量级集成。为了极致轻量初期选择textarea并监听其input事件将内容实时同步到Store中的currentFile.content。PreviewPane组件这是一个展示组件它监听Store中的currentFile.content变化。使用marked库将Markdown字符串转换为HTML并通过v-html指令渲染。这里必须注意XSS安全marked默认有简单的转义但对于生产环境建议使用DOMPurify对生成的HTML进行净化处理。!-- PreviewPane.vue 简化示例 -- template div classpreview-pane v-htmlrenderedContent/div /template script setup langts import { computed } from vue; import { marked } from marked; import DOMPurify from dompurify; import { useEditorStore } from ../stores/editor; const store useEditorStore(); const renderedContent computed(() { if (!store.currentFile?.content) return ; const rawHtml marked(store.currentFile.content); return DOMPurify.sanitize(rawHtml); // 关键的安全步骤 }); /script实时同步在EditorPane中每次输入都触发保存防抖debounce操作。例如在停止输入500毫秒后自动调用store.saveCurrentFile()该action会通过IPC通知主进程写入磁盘。同时内容变化会立即触发预览更新实现真正的“实时”。注意事项自动保存虽好但可能会在用户频繁快速输入时造成不必要的磁盘写入。一个更优的策略是结合防抖用于频繁输入和定时器例如每30秒强制保存一次并在应用窗口关闭或失去焦点时进行最终保存确保数据不丢失。4. 功能深化与体验优化4.1 文件树的递归生成与虚拟滚动当知识库文件很多时一次性渲染整个文件树可能导致性能问题。我们需要实现一个递归组件来渲染树并考虑引入虚拟滚动。首先定义树节点的数据结构并编写一个递归函数将主进程返回的扁平文件列表转换为嵌套的树结构。这需要根据文件的路径path属性来解析层级关系。然后创建TreeNode.vue递归组件。它接收一个node属性渲染自身并判断如果node.children存在且非空则递归地渲染子TreeNode。对于大型树虚拟滚动是必备的。我们可以使用vue-virtual-scroller这类库。其原理是只渲染可视区域内的节点大大减少DOM数量从而提升性能。实现时需要计算每个节点的高度或使用动态高度估算并处理好节点的展开/折叠状态与滚动位置的联动。4.2 全文搜索的实现与优化搜索功能使用fuse.js。我们不需要实时索引整个文件系统那样开销太大。合理的策略是初始索引在成功加载文件树后遍历所有.md文件读取其内容为每个文件创建一个包含path、name和content的文档对象加入Fuse索引列表。增量更新当文件被创建、修改或删除时同步更新内存中的索引列表。执行搜索当用户在搜索框输入时对索引列表执行Fuse搜索。Fuse.js支持模糊匹配和权重设置我们可以将name的权重设得比content高这样标题匹配的结果会排在前面。结果展示将搜索结果以列表形式展示在侧边栏点击结果项即可打开对应的文件。可以在预览中高亮显示搜索关键词这需要结合marked的渲染结果和DOM操作来实现。4.3 主题切换与样式管理为了实现深色/浅色主题切换我们采用CSS变量Custom Properties方案。在根元素:root上定义一套代表颜色的CSS变量。/* light-theme.css */ :root { --bg-primary: #ffffff; --bg-secondary: #f5f5f5; --text-primary: #333333; --border-color: #e0e0e0; --accent-color: #007acc; } /* dark-theme.css */ .dark-mode { --bg-primary: #1e1e1e; --bg-secondary: #252526; --text-primary: #cccccc; --border-color: #3e3e42; --accent-color: #569cd6; }在应用中所有组件的样式都使用这些CSS变量。切换主题时只需要在html或body标签上添加或移除dark-mode类即可。Pinia中的theme状态改变时触发这个DOM操作。// 在store的action或组件中 const switchTheme (newTheme: light | dark) { theme.value newTheme; if (newTheme dark) { document.documentElement.classList.add(dark-mode); } else { document.documentElement.classList.remove(dark-mode); } localStorage.setItem(app-theme, newTheme); };4.4 打包与分发优化使用electron-builder进行打包配置。在package.json中配置build字段可以指定应用图标、打包目录、是否压缩等。优化包体积是关键依赖分析使用rollup-plugin-visualizer分析构建产物剔除未使用的代码。压缩与分割确保Vite的生产构建配置启用了代码压缩和分块。Electron版本使用较新的LTS版本并确认其Node.js版本与项目依赖兼容。忽略无用文件在build.files配置中只包含必要的生产环境文件忽略测试文件、源码等。一个常见的优化是使用electron-builder的asar打包它将应用代码打包成一个归档文件能保护源码并略微提升加载速度。5. 开发中的常见问题与解决方案5.1 IPC通信延迟与错误处理问题在频繁保存文件时可能会遇到IPC通信的轻微延迟如果处理不当可能导致保存状态混乱。解决方案队列化写操作对于同一个文件的保存请求如果前一个请求还未完成应丢弃或排队后续请求。可以使用一个简单的Promise队列或基于文件路径的锁机制。明确的用户反馈在保存操作发生时在编辑器状态栏显示“保存中...”的提示保存成功后变为“已保存”并短暂显示后消失失败时则显示错误信息。这能让用户对应用状态有清晰的感知。完善的错误处理在所有IPC调用的地方使用try...catch并将错误信息以友好的方式提示给用户而不是在控制台抛出。5.2 文件系统监听与外部修改同步问题如果用户直接在系统的资源管理器中修改、删除或创建了Markdown文件应用内的文件树和编辑器内容不会自动更新导致状态不一致。解决方案轮询检查简单但低效定时如每10秒重新扫描知识库目录对比文件树变化。不推荐用于大型目录。使用Node.js的fs.watchAPI推荐在主进程中对知识库根目录使用fs.watch或更稳定的chokidar库进行监听。当检测到change、add、unlink等事件时通过IPC主动通知渲染进程“文件系统有变化”。渲染进程收到通知后可以重新加载文件树并检查当前打开的文件是否被外部修改如果被修改则提示用户“文件已在外部修改是否重新加载”。// main.js 中使用 chokidar const chokidar require(chokidar); let watcher; function watchKnowledgeBase(path) { if (watcher) watcher.close(); watcher chokidar.watch(path, { ignored: /(^|[\/\\])\../, // 忽略隐藏文件 persistent: true, ignoreInitial: true, depth: 5 // 监听深度 }); watcher .on(add, path mainWindow.webContents.send(file-change, { event: add, path })) .on(change, path mainWindow.webContents.send(file-change, { event: change, path })) .on(unlink, path mainWindow.webContents.send(file-change, { event: delete, path })); }5.3 Markdown扩展语法与代码高亮问题基础的Markdown渲染可能不满足需求比如需要支持表格、任务列表、数学公式、流程图等扩展语法以及代码块的高亮显示。解决方案切换或配置渲染引擎如果使用marked可以配置options并启用gfmGitHub Flavored Markdown来支持表格、删除线等。对于更复杂的扩展可以考虑迁移到markdown-it它拥有丰富的插件生态系统如markdown-it-task-lists,markdown-it-texmath。代码高亮使用highlight.js库。在marked的配置中设置highlight函数调用hljs.highlightAuto(code, language)。需要在前端引入highlight.js的样式文件如github-dark主题。为了减小体积可以只引入常用的语言包。// marked配置示例 import { marked } from marked; import hljs from highlight.js; import highlight.js/styles/github-dark.css; marked.setOptions({ highlight: function(code, lang) { if (lang hljs.getLanguage(lang)) { try { return hljs.highlight(code, { language: lang }).value; } catch (err) {} } return hljs.highlightAuto(code).value; }, gfm: true, breaks: true });5.4 应用性能与内存管理问题随着打开的文件越来越多或者单个文件非常大几十MB应用可能出现卡顿或内存占用过高。解决方案限制同时打开的文件在Store中不要保存所有打开文件的内容只保存当前活动文件的内容。对于其他标签页如果实现多标签可以只保存其路径和修改状态内容在激活时再加载。大文件处理对于超大的Markdown文件实时渲染整个文件的预览可能压力很大。可以考虑只渲染可视区域附近的段落即虚拟化预览但这实现复杂。一个更简单的折中方案是在用户打开大文件时给出提示并禁用实时预览改为手动触发预览。清理不必要的响应式数据确保Vue的响应式数据ref,reactive只用于需要动态更新的数据。对于静态配置或一次性加载的数据可以使用普通变量或shallowRef/shallowReactive来减少响应式开销。定期检查内存泄漏使用Chrome DevTools的Memory面板对渲染进程进行快照对比确保组件卸载后其相关内存能被正确回收。特别注意移除全局的事件监听器和定时器。构建“9pts/copaw1”的过程是一个不断在功能、复杂度与核心的“轻量、专注”理念之间做权衡的过程。每添加一个新特性都要回头问问自己这违背了最初的九点要求吗这个工具最终完美地服务于我的核心场景——快速、无干扰地记录与整理。它可能没有花哨的图谱视图和复杂的数据库但它启动飞快文件触手可及让我能完全专注于内容本身。如果你也需要这样一个工具不妨以这个项目为蓝本开始打造属于你自己的数字思考空间。