ByteNoteByteNote
字

字节笔记本

2026年6月25日

ZenNotes：键盘优先的本地 Markdown 笔记应用

#开源工具
API中转
¥120
每日科技简报 · 每天一篇,快速了解科技圈大事

ZenNotes 是一款键盘优先的本地 Markdown 笔记应用，把笔记当作普通 .md 文件存在磁盘上，在文件之上叠加 Vim 友好编辑、分屏/预览、任务标签、CSV 数据库和 MCP 集成。GitHub 1.7k stars，TypeScript + Go 编写，MIT 协议，最新版本 v2.8.0。

项目简介

ZenNotes 由 Adib Hanna 开发，是一款 local-first 的 Markdown 笔记应用。它有一个共享的产品核心和多个运行时：Electron 桌面端、Go 后端的自托管 web 端，以及规划中的托管版。截至撰稿，项目在 GitHub 上获得 1.7k stars，主要使用 TypeScript（87.6%）编写，Go 占 5.4%（自托管服务端），遵循 MIT 协议。

核心理念有三：纯文件优先（笔记就是普通 .md 文件，不存隐藏数据库）、键盘优先（一等公民的 Vim 模式、leader-key、命令面板）、预览是工作流的一部分（编辑/预览/分屏模式一体化）。

核心特性

  • 纯文件优先：每条笔记是 vault 里的普通 .md 文件，ZenNotes 不把笔记内容存进隐藏数据库。
  • 键盘优先：一等公民的 Vim 模式、leader-key 流程、命令面板、面板/标签移动、本地 ex 命令、内置帮助。
  • 预览即工作流：编辑模式、预览模式、分屏模式、钉住的参考面板，桌面端还支持分离的笔记窗口。
  • 共享 vault、共享工具：内置 MCP 服务器 + 桌面端安装流程，让 AI 工具直接操作你同一个 vault，而不是副本。
  • CSV 数据库：Notion 风格的 Table / Board 视图，直接跑在普通 .csv 文件上。
  • 多运行时：Electron 桌面、Go 自托管 web、规划中的托管版，三者共享同一个 app-core。
  • Obsidian 友好：主笔记可放在 vault 根（不必强制 inbox/），![[image.png]] 嵌入、引用文件默认落在根目录，导入的 Obsidian vault 行为更自然。

技术栈

层技术
桌面端Electron（原生菜单、更新器、浮窗、打包）
编辑器CodeMirror 6（Markdown 工作流、实时预览、标题折叠、大纲、Vim 块光标）
前端核心React（packages/app-core 共享应用与渲染逻辑）
Web 壳Vite / PWA
服务端Go（自托管与托管的 vault 访问、文件监听）
渲染GitHub-flavored Markdown、KaTeX、Mermaid、TikZ、JSXGraph、function-plot
搜索内置引擎 / ripgrep / fzf，自动检测
构建单 monorepo（turborepo）

安装

桌面端安装包随每个 GitHub Release 发布，应用自动更新（只需下载一次）。

macOS（推荐 Homebrew）：

bash
brew install --cask zennotes/tap/zennotes

或下载 .dmg（构建已签名 + 公证）。Apple Silicon 用 arm64 包，Intel 用 x64 包。

Windows：下载并运行 ZenNotes-<version>-win-x64.exe。

Linux（按发行版任选）：

bash
# Arch / CachyOS / Manjaro — AUR（推荐，无需 libfuse2）
yay -S zennotes-bin

# Arch 原生包
sudo pacman -U ZenNotes-<version>-linux-x86_64.pacman

# Debian / Ubuntu
sudo apt install ./ZenNotes-<version>-linux-amd64.deb

# 任意发行版 — AppImage
chmod +x ZenNotes-<version>-linux-x86_64.AppImage
./ZenNotes-<version>-linux-x86_64.AppImage

AppImage 需要 FUSE 2。只带 FUSE 3 的发行版（Arch、CachyOS、Fedora）可以装 fuse2，或直接 --appimage-extract-and-run，或干脆用 AUR/.pacman/.deb 绕开。

自托管 Docker

bash
make up
# 然后打开 http://localhost:7878

默认挂载：宿主机 ./vault → 容器同绝对路径，./data → /data（服务端配置存于 /data/server.json）。

安全默认（这点做得到位）：

  • 端口默认绑 127.0.0.1，不对外
  • 首次 make up 生成 bootstrap auth token，存于 ./data/auth-token
  • 浏览器用 token 登一次，之后走 HttpOnly session cookie（不再依赖 URL/localStorage 里的 token）
  • 容器以本地 UID/GID 运行、只读根文件系统、no-new-privileges、丢弃 Linux capabilities

关键环境变量：

变量作用
ZENNOTES_VAULT_PATH锁死服务端到指定 vault 路径
ZENNOTES_BROWSE_ROOTS限制 web picker 能浏览哪些目录
ZENNOTES_ALLOWED_ORIGINS浏览器来源白名单
ALLOW_INSECURE_NOAUTH=1关闭默认 auth（仅在明确需要时用）

重要限制：容器只能浏览被挂载进来的目录。想在 web picker 里浏览 Obsidian vault 或 iCloud Drive，得先把那个目录挂进容器。官方建议把 ZenNotes 放在反代/VPN/私网之后，不要把裸 Go server 直接暴露公网。

zen CLI 与 Raycast

桌面端从 Settings → CLI 安装 zen 命令行伴侣：列出、读取、搜索、捕获、编辑、归档笔记，外加任务、文件夹、MCP 工作流。macOS 上还能本地安装 Raycast 扩展（走 zennotes:// deep link，支持搜索、在主程序/浮窗打开、归档、移入回收站、Finder 定位、复制路径或 wikilink），绕过 Raycast Store 审核。

MCP 集成

ZenNotes 内置专用 MCP 服务器，桌面端支持为 Claude Code、Claude Desktop、Codex 一键安装/卸载，能检测是否已装、显示启动用的运行时、在设置里编辑默认指令。MCP 暴露的 vault 操作包括：

  • 读取 / 创建 / 移动 / 追加笔记
  • 列出笔记、搜索 vault 文本
  • 列出文件资产
  • 切换任务

本地开发

要求：Node.js 22+、npm、Go 1.22+（服务端构建）、Docker（可选）。

bash
npm ci                 # 装依赖
npm run dev:desktop    # 桌面端开发
npm run dev:web        # web 客户端
npm run dev:server     # Go 服务端
npm run dev:web-stack  # web + 服务端一起跑

dev 模式下浏览器 app 和 Go server 是独立进程：前端改动通常只需 web dev server；后端改动需重启 Go server。仓库根目录的 Makefile 提供 make desktop / web-dev / server-dev / web-stack / build / up / down 等更简洁的入口，make help 可打印全部命令。

项目链接

开源工具
上一篇

测了一个 4000 行的安全 AI 项目，核心能用，但用户第一步就会卡住

下一篇

ZenNotes：键盘优先的本地 Markdown 笔记应用

分享: