企业官网建设流程全解析

Joplin 终端应用完全指南：命令系统、快捷键映射与多目标同步实战

【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin

本文围绕 Joplin 的终端应用（Terminal Application）展开，覆盖从安装、Vim 式双模式交互、完整命令行参考，到文件系统/Nextcloud/WebDAV/Dropbox/OneDrive 等多目标同步配置与自定义 keymap 的全部实操要点，并结合packages/app-cli与packages/lib源码印证命令实现、同步目标注册与本地资源短链服务的底层机制。读完后你将能够独立完成 Joplin Terminal 的安装、日常笔记管理、自动化同步（含 cron 定时同步）与个性化快捷键定制。

一、Joplin Terminal 是什么

Joplin 是一款免费、开源的笔记与待办管理应用，可以处理组织在笔记本（Notebook）中的大量笔记。笔记可被搜索、复制、打标签，并可以用你偏好的外部文本编辑器修改。

终端应用（npm 包名joplin，位于 packages/app-cli）是 Joplin 最基础的客户端形态：

• 支持从.enex文件导入 Evernote 数据，包括格式化内容（转换为 Markdown）、资源（图片、附件）与完整元数据（地理位置、创建/更新时间）；也支持导入纯 Markdown 文件；
• 笔记、笔记本、标签等元数据在同步时保存为纯文本文件，便于检查、备份与迁移；
• 从源码结构看，终端 UI 基于terminal-kit构建（见 packages/app-cli/package.json 中的依赖声明），主程序入口为 packages/app-cli/app/main.js，界面主体在 packages/app-cli/app/app-gui.ts，各面板拆分为gui/目录下的独立组件：Notebooks 列表、Notes 列表、笔记正文、控制台、元数据面板 与 状态栏。

二、安装

官方支持的安装方式如下（macOS、Linux，或 Windows 的 WSL 环境）：

1. 先安装 Node 12+；
2. 执行以下命令安装 Joplin Terminal：

NPM_CONFIG_PREFIX=~/.joplin-bin npm install --loglevel=error -g joplin sudo ln -s ~/.joplin-bin/bin/joplin /usr/local/bin/joplin

3. 启动：

joplin

默认情况下应用二进制安装在~/.joplin-bin下，可按需更换目录。如果已按 npm 官方建议（"Option 2：修改 npm 默认安装目录"）配置好 npm 权限，则直接npm -g install joplin即可。

适用前提：packages/app-cli/package.json 的engines字段声明 Node>=10.0.0，但官方文档要求 Node 12+，请以文档要求为准。

不受支持的安装方式

其他方式（如社区包）不受官方支持，出现问题需向对应上游项目反馈。以 Arch Linux 为例，可通过 AUR 安装（使用 yay 等工具执行yay -S joplin，会同时打包 CLI 工具joplin与桌面应用joplin-desktop），也可使用 chaotic-aur 仓库的预编译包；支持问题请到对应的社区包项目仓库反馈。

三、基本使用：三面板与两种输入模式

运行joplin后进入用户界面，包含三个主面板：Notebooks（笔记本列表）、Notes（笔记列表）与当前笔记正文，此外还有可通过快捷键开关的附加面板（控制台、元数据面板）。

Joplin 终端界面部分借鉴 Vim 的设计，提供两种交互模式：

普通模式（Normal mode）

• 使用Tab/Shift-Tab在面板间切换焦点；
• 使用方向键选择/浏览笔记，也可以滚动文本区域；
• 按Enter进入编辑状态；
• 其余操作见快捷键。

命令行模式（Command-line mode）

按:进入命令行模式，即可输入mknote、search等 Joplin 命令（完整清单见命令参考）。

笔记或笔记本可以用标题或 ID 引用，但最简便的方式是引用"当前选中项"：

示例：

创建一篇标题为 "Wednesday's meeting" 的新笔记：

mknote "Wednesday's meeting"

创建一个待办事项：

mktodo "Buy bread"

将当前选中的笔记（$n）移动到标题为 "Personal" 的笔记本：

mv $n "Personal"

把当前选中的笔记本（$b）重命名为 "Something"：

ren $b "Something"

把本地文件附加到当前选中的笔记（$n）：

attach $n /home/laurent/pictures/Vacation12.jpg

命令行模式下同样可以修改配置，例如把默认编辑器改为 Sublime Text：

config editor "subl -w"

编辑笔记

选中笔记后按ENTER即可编辑；或在命令行模式输入edit $n编辑当前选中笔记、edit "Note title"编辑指定笔记。对应实现为 packages/app-cli/app/command-edit.ts。

获取帮助

在命令行模式输入：

如果帮助内容显示不全，可多次按Tab直到控制台获得焦点，再用方向键或翻页键滚动查看。

四、从 Evernote 导入笔记

1. 先从 Evernote 将笔记本导出为 ENEX 文件（按 Evernote 官方"备份/导出"说明操作）；
2. 在 Joplin 命令行模式输入import /path/to/file.enex，笔记会被导入到一个以文件名命名的新笔记本；
3. 对每个需要导入的笔记本重复上述过程。

ENEX 解析与 Markdown 生成逻辑位于共享库 packages/lib/import-enex.ts、import-enex-html-gen.ts 与 import-enex-md-gen.ts，终端侧入口为 command-import.ts。

五、同步（Synchronisation）

Joplin 的目标之一是避免被绑定到任何特定公司或服务（Evernote、Google 或 Microsoft）。因此同步在设计上不对任何特定服务产生硬依赖：大部分同步过程运行在抽象层，对 Nextcloud、Dropbox 等外部服务的访问通过轻量级"驱动器"完成。新增服务只需实现一个提供类文件系统接口（读取、写入、删除、列举）的简单驱动器；在服务之间切换也因此非常简单。

从源码结构看，这套抽象由 packages/lib/SyncTargetRegistry.ts 统一管理，各具体目标分别实现：本地文件系统、Nextcloud、WebDAV、Dropbox、OneDrive、S3、Joplin Server、Joplin Cloud。

当前可与 Joplin Cloud、Nextcloud、S3、WebDAV、Dropbox、OneDrive 或本地文件系统同步。配置完成后，应用运行时会在后台自动同步（任何本地内容变更后自动触发后台同步），也可手动执行 "Synchronise"。

若安装了终端客户端，还可以在界面之外直接同步：在终端执行joplin sync。这可以配合 cron 定时同步，例如每 30 分钟一次：

*/30 * * * * /path/to/joplin sync

sync.target 取值对照（源码已验证）

文档中sync.target配置为枚举类型，默认0。各取值与源码实现的对应关系如下（ID 均取自对应SyncTarget*.ts的static id()）：

Nextcloud 同步

需要设置sync.target以及sync.5.path、sync.5.username、sync.5.password三个配置，分别对应 Nextcloud 的 WebDAV URL、用户名与密码。在命令行模式执行：

:config sync.target 5 :config sync.5.path https://example.com/nextcloud/remote.php/webdav/Joplin :config sync.5.username YOUR_USERNAME :config sync.5.password YOUR_PASSWORD

如果同步失败，请查看应用配置目录（~/.config/joplin）中的日志——问题通常出在 URL 或密码配置错误，日志会给出具体原因。

WebDAV 同步

选择 "WebDAV" 同步目标，配置步骤与 Nextcloud 相同，但终端应用中需选择同步目标 6 而不是 5：

:config sync.target 6 :config sync.6.path <WebDAV URL> :config sync.6.username <用户名> :config sync.6.password <密码>

与 Joplin 确认兼容的 WebDAV 服务清单见 readme/apps/sync/webdav.md。

Dropbox 同步

:config sync.target 7

Joplin 会在 Dropbox 的/Apps/Joplin子目录中读写笔记与笔记本，应用无权访问该目录之外的任何内容。输入:sync启动同步后，按提示访问授权链接即可完成应用授权。

本地文件系统同步

启动终端应用后，在命令行模式执行：

:config sync.target 2 :config sync.2.path <本地同步目录的绝对路径>

重要警告（来自配置说明原文）：sync.2.path、sync.5.path、sync.6.path、sync.8.path、sync.9.path均为"位置"类配置——如果更改这些位置，务必先把全部旧内容复制过去再同步，否则所有文件会被删除！官方 FAQ 有更详细说明。配置项sync.wipeOutFailSafe（bool，默认true）正是为此设计的保险开关：当同步目标为空（通常是配置错误或 bug 所致）时，拒绝清空本地数据。

OneDrive 同步

Joplin 会在 OneDrive 的/Apps/Joplin子目录中读写数据，无权访问该目录之外的内容。输入:sync启动同步，按提示输入 Microsoft 账号凭据即可授权（无需单独向 OneDrive 注册应用）。

六、命令参考

以下是命令行模式可用的命令（摘自官方文档，与 packages/app-cli/app/ 下command-*.ts文件一一对应）：

attach <note> <file> 把指定文件附加到笔记。 batch <file-path> 执行文本文件中的命令，每行一条命令。 cat <note> 显示指定笔记。 -v, --verbose 显示笔记的完整信息。 config [name] [value] 读取或设置配置项。不提供 [value] 时显示 [name] 的值；两者都不提供时列出当前配置。 -v, --verbose 同时显示未设置与隐藏的配置变量。 --export 以 JSON 形式把全部设置（含安全变量）写到 STDOUT。 --import 从 STDIN 读取 JSON 格式的设置。 --import-file <file> 从 <file> 读取设置，文件必须包含合法 JSON。 cp <note> [notebook] 把匹配 <note> 的笔记复制到 [notebook]；不指定笔记本时复制到当前笔记本。 done <note> 把待办标记为已完成。 e2ee <command> [path] 管理端到端加密（E2EE）配置。命令有 `enable`、`disable`、`decrypt`、 `status`、`decrypt-file` 和 `target-status`。 -p, --password <password> 使用指定密码作为主密码（出于安全考虑不推荐）。 -v, --verbose 对 `target-status` 命令输出更详细的结果。 -o, --output <directory> 输出目录。 --retry-failed-items 仅对 `decrypt` 命令生效：重试之前解密失败的条目。 edit <note> 编辑笔记。 export <path> 把 Joplin 数据导出到指定路径；默认导出完整数据库（笔记本、笔记、标签、资源）。 --format <format> 目标格式: jex (Joplin Export File), raw (Joplin Export Directory), md (Markdown), md_frontmatter (Markdown + Front Matter) --note <note> 只导出指定笔记。 --notebook <notebook> 只导出指定笔记本。 geoloc <note> 显示笔记的地理位置 URL。 help [command] 显示使用帮助。 import <path> [notebook] 向 Joplin 导入数据。 --format <format> 源格式: auto, jex, md, md_frontmatter, raw, enex -f, --force 不请求确认。 --output-format <output-format> 输出格式: md, html ls [note-pattern] 显示当前笔记本中的笔记；`ls /` 显示笔记本列表。 -n, --limit <num> 只显示前 <num> 条笔记。 -s, --sort <field> 按 <field> 排序（如 title, updated_time, created_time）。 -r, --reverse 反转排序。 -t, --type <type> 只显示指定类型的项。`n` 笔记、`t` 待办、`nt` 两者（如 `-tt` 只显示待办，`-tnt` 显示笔记和待办）。 -f, --format <format> "text" 或 "json"。 -l, --long 长列表格式：ID、NOTE_COUNT（笔记本）、DATE、 TODO_CHECKED（待办）、TITLE。 mkbook <new-notebook> 创建新笔记本。 mknote <new-note> 创建新笔记。 mktodo <new-todo> 创建新待办。 mv <note> [notebook] 把匹配 <note> 的笔记移动到 [notebook]。 ren <item> <name> 把 <item>（笔记或笔记本）重命名为 <name>。 rmbook <notebook> 删除指定笔记本。 -f, --force 不请求确认直接删除。 rmnote <note-pattern> 删除匹配 <note-pattern> 的笔记。 -f, --force 不请求确认直接删除。 server <command> 启动、停止或检查 API 服务器。运行端口通过 api.port 配置项指定，命令为 (start|stop|status)。这是实验性功能，风险自负！建议使用 --profile 指定 独立配置文件路径，让服务器运行在独立 profile 中，避免两个 CLI 实例同时 访问同一 profile。 set <note> <name> [value] 把 <note> 的属性 <name> 设为 [value]。可选属性： parent_id, title, body, created_time (int), updated_time (int), is_conflict (int), latitude/longitude/altitude (numeric), author, source_url, is_todo (int), todo_due (int), todo_completed (int), source, source_application, application_data, order (numeric), user_created_time (int), user_updated_time (int), encryption_cipher_text (text), encryption_applied (int), markup_language (int), is_shared (int), share_id (text), conflict_original_id (text), master_key_id (text)。 status 显示笔记与笔记本的汇总信息。 sync 与远程存储同步。 --target <target> 同步到指定目标（默认为 sync.target 配置值）。 --upgrade 把同步目标升级到最新版本。 --use-lock <value> 禁用防止多客户端同时同步的本地锁（默认 = 1）。 tag <tag-command> [tag] [note] <tag-command> 可为 "add"、"remove"、"list"、"notetags"：分别为 [note] 添加/移除 [tag]、列出关联 [tag] 的笔记、或列出 [note] 关联的标签。 `tag list` 列出全部标签（-l 使用长格式）。 -l, --long 长列表格式：ID、NOTE_COUNT（笔记本）、DATE、 （待办的）TODO_CHECKED、TITLE。 todo <todo-command> <note-pattern> <todo-command> 可为 "toggle" 或 "clear"。"toggle" 在已完成/未完成之间 切换（若目标是普通笔记则先转换为待办）；"clear" 把待办还原为普通笔记。 undone <note> 把待办标记为未完成。 use <notebook> 切换到 [notebook]，之后的所有操作都在该笔记本中进行。 version 显示版本信息。

config命令"可设置的键/值"完整清单（含类型、取值与默认值）即下节配置参数详解。

七、配置参数详解

以下参数可通过config <name> [value]读取/设置（摘自官方config帮助输出）：

八、URL 短链与本地资源服务

在终端中 Ctrl+Click（或高亮链接后按快捷键o）通常会用默认浏览器打开 URL。但长 URL 在终端里容易被折行切断，导致文本难以阅读、链接也不可点击。

Joplin 的解决方案是在后台启动一个迷你 HTTP 服务器：启动成功后，笔记中的所有链接（包括外部链接与笔记附件资源）都会被转换为指向本地服务的短 URL——由于仍是合法 URL，终端依旧可以使其可点击，且短链接大幅降低被切断的概率。

源码实现见 packages/app-cli/app/ResourceServer.ts：

• 服务器仅绑定127.0.0.1（baseUrl()返回http://127.0.0.1:<port>），不对外暴露；
• 通过findAvailablePort（packages/lib/net-utils.ts）依次尝试9167、9267、8167、8267四个端口；
• 请求路径形如/<resourceId>，由linkHandler回调解析资源 ID 后返回对应内容，未处理的路径返回 400 与错误信息。

附件 / 资源（Resources）

在 Markdown 中，资源链接表现为简单的资源 ID。为让终端用户能访问这些资源，Joplin 会把它们和外部链接一样转换为本地 URL；点击后由浏览器处理该文件——显示图片、打开 PDF 等。

九、Shell 模式

Joplin 命令也可以直接在 shell 中使用。查看可用命令列表：joplin help all。引用笔记、笔记本或标签时可用 ID（joplin ls -l查看 ID）或标题。

例如，在笔记本 "My notebook" 中创建笔记 "My note"：

$ joplin mkbook "My notebook" $ joplin use "My notebook" $ joplin mknote "My note"

查看新建的笔记：

$ joplin ls -l fe889 07/12/2017 17:57 My note

为笔记设置新标题：

$ joplin set fe889 title "New title"

十、快捷键系统与 keymap.json 定制

快捷键分两类：一类直接操作界面（如TAB切换面板）；另一类是真实命令的快捷方式。类似 Vim，这些快捷键通常由"动词+对象"组成——例如输入mn（[m]ake [n]ote）会切换界面到命令行模式并预填mknote ""，随后输入标题即可。

默认快捷键列表：

: enter_command_line_mode TAB focus_next SHIFT_TAB focus_previous UP move_up DOWN move_down PAGE_UP page_up PAGE_DOWN page_down ENTER activate DELETE, BACKSPACE delete (SPACE) todo toggle $n n next_link b previous_link o open_link tc toggle_console tm toggle_metadata / search "" mn mknote "" mt mktodo "" mb mkbook "" yn cp $n "" dn mv $n ""

自定义 keymap

在配置目录~/.config/joplin/keymap.json放置 keymap 文件即可定制快捷键。文件内容是一个 JSON 数组，每个条目定义一条命令及其按键。默认 keymap 如下：

[ { "keys": [":"], "type": "function", "command": "enter_command_line_mode" }, { "keys": ["TAB"], "type": "function", "command": "focus_next" }, { "keys": ["SHIFT_TAB"], "type": "function", "command": "focus_previous" }, { "keys": ["UP"], "type": "function", "command": "move_up" }, { "keys": ["DOWN"], "type": "function", "command": "move_down" }, { "keys": ["PAGE_UP"], "type": "function", "command": "page_up" }, { "keys": ["PAGE_DOWN"], "type": "function", "command": "page_down" }, { "keys": ["ENTER"], "type": "function", "command": "activate" }, { "keys": ["DELETE", "BACKSPACE"], "type": "function", "command": "delete" }, { "keys": [" "], "command": "todo toggle $n" }, { "keys": ["n"], "type": "function", "command": "next_link" }, { "keys": ["b"], "type": "function", "command": "previous_link" }, { "keys": ["o"], "type": "function", "command": "open_link" }, { "keys": ["tc"], "type": "function", "command": "toggle_console" }, { "keys": ["tm"], "type": "function", "command": "toggle_metadata" }, { "keys": ["/"], "type": "prompt", "command": "search \"\"", "cursorPosition": -2 }, { "keys": ["mn"], "type": "prompt", "command": "mknote \"\"", "cursorPosition": -2 }, { "keys": ["mt"], "type": "prompt", "command": "mktodo \"\"", "cursorPosition": -2 }, { "keys": ["mb"], "type": "prompt", "command": "mkbook \"\"", "cursorPosition": -2 }, { "keys": ["yn"], "type": "prompt", "command": "cp $n \"\"", "cursorPosition": -2 }, { "keys": ["dn"], "type": "prompt", "command": "mv $n \"\"", "cursorPosition": -2 } ]

每个条目支持的属性：

内置特殊函数（type: "function"可用）：

十一、小结

Joplin 终端应用以最小的依赖面提供了完整的笔记管理能力：Vim 式的三面板交互、一套可映射到 shell 的命令集、keymap.json驱动的快捷键定制，以及基于"抽象同步层 + 轻量驱动器"的多目标同步架构。所有命令、配置与快捷键均可从help命令和本文引用的源码文件（packages/app-cli/app/、packages/lib/）中进一步查证。本文内容基于当前仓库readme/apps/terminal.md与配套源码整理；终端应用源码采用 AGPL-3.0-or-later 许可（见 packages/app-cli/package.json），Joplin 整体版权信息见仓库根目录 LICENSE。

【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin