Joplin 全面指南：隐私优先的跨平台笔记与待办应用

Joplin 全面指南隐私优先的跨平台笔记与待办应用【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplinJoplin 是一款免费开源、以隐私为核心的笔记与待办事项应用支持 Windows、Linux、macOS、Android 与 iOS核心特色是离线优先的本地数据存储、端到端加密同步、Markdown 编辑与全平台全文搜索。本文基于当前仓库的官方文档readme/index.md整理并结合源码深入讲解其数据模型、导入导出、同步、加密与扩展机制帮助读者掌握 Joplin 的完整使用与定制能力。核心定位与设计理念Joplin 是一款免费的笔记与待办应用能够处理大量组织在笔记本notebooks中的笔记。笔记支持搜索、复制、打标签既可以在应用内直接修改也可以在你自己的文本编辑器中编辑。笔记采用 Markdown 格式详见 Markdown 指南。从设计理念上看Joplin 有几个关键特征隐私优先所有数据默认存储在你的设备上不依赖任何单一公司或服务。正如项目描述所述它是the privacy-focused note taking app。离线优先offline first你始终在手机或电脑上拥有全部数据无论是否有网络连接笔记都随时可用。开放格式笔记是纯文本 Markdown易于编辑、迁移与长期保存。从源码结构看这一理念贯穿整个仓库核心业务逻辑集中在 packages/lib所有平台共享的 TypeScript 库桌面端、移动端、终端客户端与 Clipper 各自基于它构建。例如 packages/lib/BaseModel.ts 定义了笔记、笔记本、标签、资源等统一的数据模型基类。从 Evernote 迁移ENEX 导入Joplin 支持从 Evernote 完整导入笔记本包括格式化内容转换为 Markdown、资源图片、附件等以及完整元数据地理位置、更新时间、创建时间等。细节见 导入导出文档。导入时会发生的转换导入 ENEX 文件时以下三点需要特别留意识别数据Recognition dataEvernote 中扫描或拍摄文档附带的 OCR 识别文本不会在导入时保留。但如果你在 Joplin 中启用了 OCR这部分识别数据会以 Joplin 兼容的格式被重新创建。颜色、字体大小与字型Evernote 文本以 HTML 存储导入过程中会转换为 Markdown。对于纯文本或基础格式粗体、斜体、项目符号、链接等的笔记转换是无损的渲染回 HTML 后非常接近原样表格也会被导入并转换为 Markdown 表格。对于非常复杂的笔记部分格式数据尤其是颜色、字体大小与字型可能丢失但文本内容始终完整导入。若必须保留这些额外数据Joplin 也支持将 ENEX 文件按 HTML 导入。笔记间链接大部分链接会被保留但 ENEX 格式并未包含确定链接目标的全部信息Evernote 使用 ID 作为链接但该 ID 并未关联到目标笔记。Joplin 会尝试根据笔记标题猜测链接目标这大多数时候有效但当存在同名笔记或链接标题与目标笔记标题不一致时可能失败——失败时 Evernote 链接会原样保留。导入操作步骤首先按 Evernote 官方指引将笔记本导出为 ENEX 文件然后桌面应用打开 File Import ENEX 并选择文件。笔记会导入到一个新的独立笔记本中之后可以移动或重命名。终端应用在命令行模式下输入import /path/to/file.enex笔记会导入到以文件名命名的新笔记本中。两种方式都可以导入单个文件或包含多个 ENEX 文件的目录导入单个文件时会创建一个同名笔记本所有笔记导入其中导入目录时Joplin 会为每个文件创建一个笔记本。从源码看ENEX 的解析与 HTML→Markdown 转换逻辑位于 packages/lib/import-enex.ts、packages/lib/import-enex-html-gen.ts 与 packages/lib/import-enex-md-gen.ts并在 packages/lib/import-enex-html-gen.test.ts 等测试中验证了转换结果的正确性。此外仓库还提供了测试用的 ENEX 样例文件见 packages/app-cli/tests 目录下的*.enex可用于了解导入格式的多样性。其他导入途径Markdown 与 OneNote从 Markdown 文件导入Joplin 可以导入纯 Markdown 文件支持完整目录或单个文件桌面应用文件导入File Import MD - Markdown (file)导入到当前选中的笔记本目录导入File Import MD - Markdown (directory)目录结构会保留为 Joplin 中的 笔记本 子笔记本 笔记 层级。终端应用命令行模式输入import --format md /path/to/file.md或import --format md /path/to/directory/。从 OneNote 导入从 OneNote Online 导入需要 Joplin ≥ v3.5.1笔记本存储在 OneDrive注意超过 2-4 GB 的笔记本可能无法完整下载访问 OneNote Web点击Show all notebooks打开 OneDrive 页面在 OneDrive 的My Files中下载包含 OneNote 笔记本的文件夹必要时先把笔记本移到一个新文件夹右键文件夹并点击download得到一个 ZIP 文件按照指引下载备份ZIP 文件打开桌面应用File Import ZIP - OneNote Notebook选择导出的文件。从 OneNote Windows 桌面应用导入需要 Joplin ≥ v3.5.5注意 OneNote 桌面应用不同于OneNote for Windows 10打开 OneNote 桌面应用打开File菜单进入Export标签页选择Section→OneNote 2010-2016 Section*.one/*.onex或选择Notebook→OneNote Package*.onepkg其中*.onepkg文件只有在 Joplin 运行于 Windows 时才能导入打开 Joplin 桌面应用从File Import菜单选择ZIP - OneNote Notebook在文件选择器中选中刚导出的文件。OneNote 解析器的实际实现位于 packages/onenote-converter采用 Rust 编写parser、renderer、parser-utils等子模块并提供*.one、*.onetoc2测试样例见 packages/onenote-converter/test-data。从其他应用导入通用的迁移路径是先把其他应用的笔记转换为 ENEXEvernote 格式、HTML 或 Markdown再导入 Joplin。针对具体应用的迁移帮助可参考 Joplin 论坛的Importing notes from other notebook applications一文。导出JEX、RAW、HTML 与 PDFJoplin 支持多种导出格式JEXJoplin Export file一个 tar 文件可包含多个笔记、笔记本等。这是无损格式笔记及地理位置、更新时间、标签等元数据全部保留适合备份并可重新导入 Joplin。RAW 格式与 JEX 相同但数据保存到目录中每个条目对应一个单独文件。HTML 与 PDF可针对单个笔记、笔记本或全部内容导出。从源码看导入导出interop能力由 packages/lib/services/interop 模块统一实现负责 JEX/RAW/ENEX/MD 等多种格式与 Joplin 内部模型之间的双向转换。同步机制解耦的驱动架构Joplin 的设计目标之一是避免被任何特定公司或服务绑定——无论是 Evernote、Google 还是 Microsoft。同步过程大部分在抽象层完成对 Nextcloud、Dropbox 等外部服务的访问通过轻量驱动drivers进行驱动只需提供类似文件系统的接口即读取、写入、删除和列出条目的能力。因此很容易支持新服务也很容易从一个服务切换到另一个。详见同步文档。当前支持与以下目标同步Joplin Cloud、Nextcloud、S3、WebDAV、Dropbox、OneDrive 或本地文件系统。启用同步后应用运行期间会在后台自动同步点击Synchronise可手动触发本地内容发生任何变更后 Joplin 也会自动后台同步。如果安装了终端客户端还可以在 UI 之外执行joplin sync从而用 cron 定时同步例如每 30 分钟一次*/30 * * * * /path/to/joplin sync源码视角的同步实现同步核心实现在 packages/lib/Synchronizer.ts。它采用步骤steps流水线设计一次完整同步默认包含[update_remote, delete_remote, delta]三个步骤见start方法附近packages/lib/Synchronizer.tsupdate_remote把本地需要同步的条目加密/序列化后上传到远端delete_remote删除远端已被本地删除的条目delta拉取远端变更应用回本地。代码中还定义了partialSyncSteps [update_remote, delete_remote]用于移动端等资源受限场景的增量同步。所有同步目标实现统一接口注册在 packages/lib/SyncTargetRegistry.ts具体驱动包括本地文件系统packages/lib/SyncTargetFilesystem.ts、Dropboxpackages/lib/SyncTargetDropbox.ts、OneDrivepackages/lib/SyncTargetOneDrive.ts、Nextcloud/WebDAVpackages/lib/SyncTargetNextcloud.ts、Joplin Cloud/Serverpackages/lib/SyncTargetJoplinCloud.ts、packages/lib/SyncTargetJoplinServer.ts以及 S3packages/lib/SyncTargetAmazonS3.js等。端到端加密E2EEJoplin 在所有应用上支持端到端加密E2EE只有数据所有者笔记、笔记本、标签或资源才能读取数据它防止潜在的窃听者——包括电信运营商、互联网服务提供商甚至 Joplin 的开发者——访问数据。系统设计目标就是抵御任何形式的监视与篡改因为任何第三方都无法解读被传输或存储的数据。详见 E2EE 文档 与加密技术规格。需要注意的是E2EE 会带来少量开销数据需要持续加解密请先评估是否真的需要该功能。启用 E2EE 的步骤由于 Joplin 的去中心化特性E2EE 需要先在单台设备上手动启用这会创建一把由你的密码保护的主密钥 Master Key 用于加密然后与其他设备同步。建议先在桌面或终端应用上操作因为它们通常运行在性能更强的设备上能更快加密初始数据在第一台设备如桌面应用进入 Encryption 配置界面点击Enable encryption输入密码。这是用于加密所有笔记的主密钥密码务必牢记——出于安全原因密码无法找回同步所有笔记使其以加密形式发送到同步目标如 OneDrive、Nextcloud 等。等待可能正在进行的同步结束后点击Synchronise等待同步完成。由于所有数据需要重新加密后发送到目标可能耗时较长尤其是笔记和资源较多时。即使看起来卡住大多时候仍在运行——不要取消必要时让它跑一整夜首次同步完成后打开下一台同步设备点击Synchronise并等待完成。该设备会收到主密钥你需要为其输入密码此时 E2EE 会在该设备上自动启用。完成后再次点击 Synchronise 并等待完成对每台设备重复第 5 步。不要在多个设备上并行手动启用加密而应等待其他设备与第一台已加密设备同步否则可能产生多个加密密钥Joplin 虽支持但通常不是你想要的。所有设备完成 E2EE 同步后加解密基本透明偶尔会看到加密条目它们会在后台被逐步解密。禁用 E2EE与启用流程相同但需在每台设备上逐一禁用 E2EE同样建议一台一台地操作并每次等待同步完成。加密数据格式与密钥体系根据加密技术规格加密数据被编码为 ASCII因为 React Native 的加解密函数只能处理字符串为兼容所有应用必须采用最低公共标准。加密数据的格式为头部标识符3 字符 JED 版本号2 字符十六进制加密元数据长度6 字符十六进制 加密方法2 字符十六进制 主密钥 ID32 字符十六进制数据块数据按一个或多个块编码出于性能考虑这样可以从一个文件取一块数据加密到另一文件移动端尤其无法一次性加密整个文件每块为长度6 字符十六进制 数据ASCII。可用的加密方法列表见 packages/lib/services/e2ee/EncryptionService.ts。密钥体系包含两种类型数据密钥Data keys用于加密 Joplin 条目笔记、笔记本、标签等。启用 E2EE 时生成一把当用户与他人共享笔记本时还会动态生成独立密钥使接收者只能解密该特定笔记本公钥-私钥对PPK用于在用户之间传递机密。启用 E2EE 并在同步时自动生成存储于同步目标的 info.json 中同步过程中先生成是因为多个客户端可能同时生成 PPK 造成冲突而同步器先获取 info.json——只有不存在 PPK 时才生成从而保证唯一性。主密钥用于加密数据密钥与用户私钥。主密码可以修改此时所有密钥会用新密码重新加密但笔记等数据本身无需重新加密。如果忘记主密码则无法恢复但可以重置重置后所有关联密钥被禁用公钥-私钥对重新生成——这意味着用遗忘密码加密过的内容将永远无法解密。PPK 的典型共享流程以 Alice 与 Bob 为例Alice 与 Bob 共享加密笔记本时需要把密钥也发给 Bob她先下载 Bob 的公钥并用它加密密钥Bob 接受共享后收到该密钥用自己的私钥解密再用主密码重新加密。之后双方都持有该密钥即可在 E2EE 下共享笔记。每个用户只能有一对 PPK。加解密工作流根据规格说明条目仅在同步期间被加密——在序列化BaseItem.serializeForSync时、发送到同步目标之前加密解密则由后台的 DecryptionWorker见 packages/lib/services/DecryptionWorker.ts完成。应用会同时展示已解密与未解密的条目让用户知道它们存在加密条目对用户基本只读但可以删除。关于启用/禁用 E2EE 与多客户端同步的细节行为规格文档readme/dev/spec/e2ee/index.md给出了若干值得注意的场景客户端 1 启用 E2EE 后所有条目会重新上传到目标并以加密形式出现由于条目的时间戳没有改变数据本身未变只是表示形式变了客户端 2不会重新下载这些条目也没必要它已拥有条目数据当客户端首次同步并下载到主密钥时E2EE 会自动启用用户需提供主密钥密码此时所有未加密条目会被重新同步——只上传未加密条目是一种优化因为本地已加密说明目标上也已加密若两个客户端都已启用 E2EE客户端 1 禁用 E2EE 后会把所有条目以未加密形式重新上传客户端 2 同样不会重新下载原因同上。必须手动在所有客户端上禁用 E2EE否则部分客户端会继续上传加密条目——因为同步是无状态的客户端无法知道其他客户端是否使用 E2EEJoplin 允许部分客户端发送加密条目、部分发送未加密条目虽然混乱一旦所有客户端统一 E2EE 设置即可解决目前没有删除不再需要的加密密钥的方法。即使完全禁用了加密新设备上仍会收到提供主密钥密码的持久通知输入主密钥密码并保持加密禁用即可消除通知。Markdown 支持与扩展语法Joplin 桌面与移动应用可以同时显示 Markdown 源码和渲染后的富文本。Joplin 遵循 CommonMark 规范并通过插件追加额外功能。完整语法请参考 Markdown 指南。基础语法速查功能Markdown 写法渲染结果标题 1# Heading 1h1Heading 1/h1标题 2## Heading 2h2Heading 2/h2标题 3### Heading 3h3Heading 3/h3粗体This is some **bold text**这是bold text斜体This is some *italic text*这是italic text引用块 Kent.多行blockquote…/blockquote无序列表- Milk等可用缩进嵌套ulli…/li/ul有序列表1. Introduction等可嵌套olli…/li/ol行内代码This is someJavaScript()等宽文本代码块三个反引号包裹可指定语言如sql语法高亮代码块未格式化文本用 Tab 或 4 空格缩进原样文本链接https://joplinapp.org、[Joplin](https://joplinapp.org)或带标题的[Joplin](https://joplinapp.org Joplin project page)自动检测/可点击链接可悬停查看标题图片Joplin icon渲染图片水平分割线***或---hr表格见下方表格表格语法表格使用竖线|和连字符-创建| First Header | Second Header | | ------------- | ------------- | | Content Cell | Content Cell | | Content Cell | Content Cell |注意每个表头单元格之间至少需要 3 个连字符。使用冒号可以对齐列| Tables | Are | Cool | | ------------- |:-------------:| -----:| | col 3 is | right-aligned | $1600 | | col 2 is | centered | $12 |笔记间链接可以通过在 URL 中指定笔记 ID 来创建指向其他笔记的链接例如Link to my note由于获取笔记 ID 并不直观各应用都提供了生成方式桌面应用中把笔记拖放到另一笔记中即可创建链接或右键笔记选择Copy Markdown link移动应用中打开笔记后在右上角菜单中选择Copy Markdown link然后粘贴到其他笔记的任意位置。数学公式KaTeX数学表达式使用 KaTeX 记号。行内公式用$EXPRESSION$包裹例如$\sqrt{3x-1}(1x)^2$独立公式块如下$$ f(x) \int_{-\infty}^\infty \hat f(\xi)\,e^{2 \pi i \xi x} \,d\xi $$化学方程式mhchemJoplin 通过 KaTeX 的 mhchem 插件支持化学方程式只要启用数学记号该插件会自动启用。图表Mermaid使用 Mermaid 语法在 Joplin 中创建图表。把 Mermaid 脚本放入mermaid graph TD; A--B; A--C; B--D; C--D;注意Mermaid 图无论当前主题如何**始终在白色背景上渲染**因为图中可能包含与主题不兼容的各种颜色。 ### 乐谱ABC 记谱法 Joplin 可以将 [ABC notation](https://abcnotation.com) 渲染为乐谱创建一个以 abc 为标识的围栏代码块内容会渲染成乐谱。例如 abc K:F !f!(fgag-g2c2)|全局选项在配置界面的 Markdown 部分可以设置 ABC 渲染器的附加选项对所有乐谱全局生效需以 JSON5 对象形式设置。例如把前景色设为红色并把乐谱放大一倍{ foregroundColor: #ff0000, scale: 2 }单张乐谱选项也可以为特定乐谱激活选项——在 ABC 标记顶部添加一个用---分隔的头部包含渲染器选项。例如为乐谱添加小提琴指法谱{tablature: [{instrument: violin}]} --- X:1 T: Cooleys M: 4/4 L: 1/8 R: reel K: G |:D2|EB{c}BA B2 EB|~B2 AB dBAG|FDAD BDAD|FDAD dAFD|即使设置了单张乐谱选项全局选项仍然生效发生冲突时由单张乐谱选项覆盖全局选项。复选框复选框写法如下- [ ] Milk - [x] Rice - [ ] Eggs在移动与桌面应用中可以直接勾选。HTML 支持官方建议以 Markdown 记录笔记更易编辑但当某些功能不支持时如删除线或文本高亮可以直接使用 HTML。例如This is sstrikethrough text/s mixed with regular **Markdown**.Markdown 插件PluginsJoplin 支持在标准 Markdown 功能之上、通过可开关的 Markdown 插件扩展功能。与普通插件不同Markdown 插件必须在配置界面的 Markdown 部分启用并非所有插件默认启用下表Enabled列为 no 的需到选项界面开启禁用方式相同。这些插件带来的功能不属于 CommonMark 规范因此在 Joplin 内都可用但不保证在其他 Markdown 阅读器中生效。如果需要与其他 Markdown 应用兼容请留意这一点。插件语法描述默认启用Soft breaks见 markdown-it breaks 演示Joplin 默认使用硬换行换行渲染为br启用后恢复传统 Markdown 软换行行为noTypographer见 markdown-it typographer 演示进行排版替换如 (c) → © 等noLinkify见 markdown-it linkify 演示自动检测 URL 并转为可点击链接yesKatex$$math expr$$或$math$数学公式见上文yesFountainfountain 代码块支持 Fountain 剧本写作纯文本标记语言noMermaidmermaid 代码块Mermaid 图表见上文yesMarkmarked转为markmarked/mark高亮yesFootnoteSimple inline footnote ^[Im inline!]脚注支持yesTOC${toc}、[[toc]]、[toc]、[[_toc_]]之一基于标题与子标题在 toc 位置生成目录yesSubX~1~转为 X1noSupX^2^转为 X2noDeflist见 pandoc 定义列表语法支持dl定义列表noAbbr*[HTML]: Hyper Text Markup Language定义缩写悬停可查看完整展开noEmoji:smile:转为 noInsertinserted转为insinserted/insnoMultitable见 MultiMarkdown 表格语法为 Markdown 表格增加更多能力与定制no从源码看Markdown 渲染由 packages/renderer 包实现其中 packages/renderer/MarkupToHtml.ts 负责 Markdown→HTML 的整体管线packages/renderer/MdToHtml 目录承载 markdown-it 相关的渲染插件配置packages/renderer/MdToHtml.ts 与 packages/renderer/assetsToHeaders.ts 则处理渲染资产的注入。全文搜索Joplin 在所有平台上提供全文搜索用于快速定位所需信息。搜索能力在源码中由 packages/lib/services/search 模块实现支持按笔记内容、标签等维度检索。主题与自定义应用可以通过插件和主题进行自定义也可以轻松创建自己的主题。主题定义文件位于 packages/lib/themes例如light.ts、dark.ts等而桌面端把主题编译为 CSSpackages/app-desktop/style 与 tools/convertThemesToCss.ts移动端也有对应的主题配置。插件系统桌面与移动应用都可以通过插件扩展标准功能。插件遵循 Joplin 插件 API可在配置界面的Plugins页面安装与配置既可搜索上传到插件仓库的插件也可通过 Joplin Plugin Archive*.jpl文件手动安装。应用重新加载后插件会出现在插件菜单中可开关或彻底移除。详见 插件文档。安装插件搜索安装在Plugins页面搜索框中输入插件名即可输入一个空格会显示全部插件桌面端还可通过Plugin tools齿轮按钮选择Browse all plugins浏览仓库。推荐插件带有金色皇冠图标由 Joplin 团队审核推荐。点击插件的Install按钮后应用会提示重启以完成安装。手动安装桌面先下载插件的.jpl文件。可通过Plugin tools齿轮按钮选择Install from file并选择该文件也可以把.jpl复制到配置文件目录的plugins目录如~/.config/joplin-desktop/plugins具体路径因设备而异可在配置界面的 Options 页顶部查看重启后插件自动加载执行。注意确认 Joplin 没有最小化到系统托盘/通知区域而不是完全关闭。手动安装Android配置界面Plugins标签页的Advanced settings下有Install from file按钮。注为遵守 AppStore 准则iOS 应用只允许安装推荐插件。管理、更新与卸载开关在 Plugins 页面用开关控件逐个启用/禁用插件更改后必须重启 Joplin同样注意系统托盘问题。插件融入应用本身每个插件可能有自己的配置选项和多种执行方式务必完整阅读作者文档。更新插件可在应用内自动更新。有可用更新时设置菜单的Plugins页面会显示橙色Update按钮点击更新完成后提示重启。卸载在 Plugins 页面点击插件上的 Delete 按钮重启后生效也可以直接从插件目录移除*.jpl文件见上文安装部分重启后变更生效。插件开发插件 API 与开发文档见 API 概览。仓库内的参考实现包括 packages/default-plugins内置默认插件含构建脚本 buildDefaultPlugins.ts、packages/plugins/ToggleSidebars 以及生成插件脚手架的工具 packages/generator-joplin。Web Clipper 浏览器扩展Web Clipper 是一个浏览器扩展用于保存网页与截图。要开始使用打开 Joplin 桌面应用进入配置界面的Web Clipper部分并按照说明操作。详见 Web Clipper 文档。Web Clipper 扩展与 Joplin 应用通过服务通信该服务由 Joplin 桌面应用启动。故障排查如果 Clipper 服务不可用或无法启动请依次检查服务是否已启动在桌面应用的 Web Clipper 选项中检查端口是否被防火墙拦截端口号可在桌面 Joplin 应用的 Web Clipper 选项中查看是否有代理运行确保来自 Web Clipper 服务的请求被过滤并放行。若以上都无效可在官方论坛或 GitHub Issue 中反馈。调试扩展Chrome先在 chrome://extensions/ 启用开发者模式。调试弹出窗口右键 Joplin 扩展图标选择Inspect popup调试后台脚本在chrome://extensions/点击Inspect background script调试内容脚本按 CtrlShiftI 打开当前页面控制台。Firefox打开 about:debugging勾选Enable add-on debugging向下滚动到 Joplin Web Clipper 扩展点击Debugging打开新的控制台窗口同时按 F12 打开 Firefox 常规控制台部分 Joplin 扩展消息也会输出到这里。复现问题后把调试窗口与浏览器控制台的内容复制并粘贴到论坛反馈。Clipper 服务 APIWeb Clipper 服务可以从任何其他应用用于创建、修改或删除笔记、笔记本、标签等它暴露了一组管理 Joplin 数据的 API 方法详见 REST API 文档。从源码看该服务由 packages/lib/ClipperServer.ts 实现配套测试见 packages/lib/ClipperServer.test.ts浏览器端的扩展主体位于 packages/app-clipper。平台支持与获取方式Joplin 可用于 Windows、Linux、macOS、Android 和 iOS。安装方式、系统要求与下载指引见安装文档与下载页。延伸阅读桌面应用指南 与 移动应用指南同步设置 与端到端加密Markdown 完整指南导入与导出插件系统 与 插件 API配置界面说明终端应用命令行模式加密技术规格开发与架构文档【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考