Joplin 插件开发实战:基于官方模板理解插件入口、manifest 与 JPL 打包构建全流程

原创2026-09-09 12:01:511,965 阅读
文章标签:知识管理桌面应用移动开发跨平台后端插件系统笔记

Joplin 插件开发实战:基于官方模板理解插件入口、manifest 与 JPL 打包构建全流程

Joplin 是一款以隐私为核心、支持多端同步的笔记应用,其插件机制允许开发者通过 TypeScript/JavaScript 扩展笔记编辑器、界面视图与桌面端行为。本文以仓库内置的 toast 示例插件(packages/app-cli/tests/support/plugins/toast/README.md)所附的官方模板 README 为主线,完整讲解 Joplin 插件工程的核心骨架:src/index.ts 入口点、src/manifest.json 插件清单、基于 Webpack 的 npm run dist 构建流水线,以及 yo joplin --update 的框架升级策略。读完本文,你将能够独立搭建、构建并发布一个可用的 Joplin 插件,并掌握如何在不被升级覆盖的前提下安全定制框架配置。

模板全景:一个标准 Joplin 插件工程包含什么

官方模板是一个完整的 npm 工程,除了 README 中强调的两个核心文件,还包含构建配置、API 类型声明与打包脚本。以 toast 示例插件的实际目录为例:

packages/app-cli/tests/support/plugins/toast/
├── api/                    # 官方插件 API 的 TypeScript 类型声明(Joplin.d.ts、JoplinViewsDialogs.d.ts 等)
├── src/
│   ├── index.ts            # 插件源码入口点
│   └── manifest.json       # 插件清单:名称、版本、ID 等元信息
├── GENERATOR_DOC.md        # yeoman 生成器补充文档
├── README.md               # 模板说明(本文主体)
├── package.json            # npm 脚本与依赖(dist / update 等)
├── plugin.config.json      # 额外脚本配置(extraScripts)
├── tsconfig.json           # TypeScript 编译配置
└── webpack.config.js       # 三段式构建流水线核心

README 明确指出,开发时最需要关注的两个文件是:

  • /src/index.ts:插件源码的入口点,所有插件逻辑从这里启动;
  • /src/manifest.json:插件清单,承载插件名称、版本号等元信息。

两者的作用可以在 toast 示例中直接验证。入口文件 src/index.ts 通过 joplin.plugins.register({ onStart }) 注册插件生命周期回调;而 src/manifest.json 声明了插件 ID org.joplinapp.plugins.DialogDemo、最低应用版本 app_min_version: "1.4"、插件名、描述、作者与主页。其中 manifest_version 当前为 1,是 Joplin 插件清单的协议版本号。

入口点 src/index.ts:插件如何启动

Joplin 插件的入口文件统一约定为 src/index.ts。它通过全局导入的 joplin 对象访问整个插件 API——正如 api/Joplin.d.ts 所述,这是“Joplin API 的主入口点”,提供 data、views、commands、settings、workspace 等访问器。

最基础的启动模式是调用 joplin.plugins.register() 并传入一个含 onStart 回调的注册对象。toast 示例展示了最小可用形态:

import joplin from 'api';
import { ToastType } from 'api/types';

joplin.plugins.register({
	onStart: async function() {
		const dialogs = joplin.views.dialogs;

		setTimeout(() => {
			dialogs.showToast({
				message: 'This is an info message',
			});
		}, 5000);

		setTimeout(() => {
			dialogs.showToast({
				type: ToastType.Error,
				message: 'This is an error message',
			});
		}, 7000);

		setTimeout(() => {
			dialogs.showToast({
				type: ToastType.Success,
				message: 'This is a success message',
			});
		}, 9000);
	},
});

从源码结构看,该示例依次在启动后 5 秒、7 秒、9 秒触发三条不同类型的 toast 通知,用于演示 showToast 的三种展示形态。onStart 被声明为 async,意味着可以在其中执行异步初始化(读取设置、创建视图等),插件框架会等待其完成。入口点之外,api/ 目录下的 .d.ts 声明文件为整个 API 提供类型提示与编译期校验,这是模板工程默认启用 TypeScript 的最大收益。

manifest.json:插件的身份证明

清单文件是插件能否被 Joplin 正确加载与发布的关键。以 toast 示例的 manifest.json 为准,各字段含义如下:

字段 示例值 说明
id org.joplinapp.plugins.DialogDemo 插件唯一 ID,构建脚本会将其用作 JPL 归档文件名(<id>.jpl)
manifest_version 1 清单协议版本号
app_min_version 1.4 支持该插件的最低 Joplin 应用版本
name Dialog Demo 插件显示名称
description Demonstrate how to create and use a custom dialog box 插件简介
version 1.0.0 插件版本号
author Laurent Cozic 作者
homepage_url https://joplinapp.org 主页地址(模板默认值)

构建脚本对 manifest 有硬性校验:在 webpack.config.js 的 readManifest() 中,若 id 缺失会直接抛出错误;若声明了 categories 字段,还会逐一校验其必须位于预置类别白名单内(如 appearance、productivity、themes、integrations、editor、personal knowledge management 等),且不允许重复。因此新增类别前务必核对白名单,否则构建会失败。

构建插件:npm run dist 背后的三段式 Webpack 流水线

README 给出的构建命令极其简单:npm run dist。它由 package.json 中的 scripts 定义,实际是串联三次带 --joplin-plugin-config 参数的不同 webpack 调用:

"dist": "webpack --joplin-plugin-config buildMain && webpack --joplin-plugin-config buildExtraScripts && webpack --joplin-plugin-config createArchive"

在 webpack.config.js 中,这三步分别对应 main() 函数里三套配置,注释中说明了它们必须按顺序串行执行(webpack 并行运行无法保证产物顺序):

  1. buildMain:以 ./src/index.ts 为入口,用 ts-loader 编译 TypeScript,输出到 /dist;同时通过 copy-webpack-plugin 把 src/ 下非 .ts/.tsx 的静态资源(脚本、CSS、其他资产)一并拷入 /dist。第一次执行时还会清空并重建 dist/ 与 publish/ 目录。
  2. buildExtraScripts:按 plugin.config.json 中 extraScripts 数组声明的额外脚本逐个编译,产物输出到 /dist 并可能覆盖上一步拷贝的原始 JS——设计意图是:不需要编译的 JS 直接拷贝,需要编译的则以编译产物为准。
  3. createArchive:通过 on-build-webpack 钩子在构建完成后触发 onBuildCompleted(),把 dist/ 下所有文件用 tar 打成 JPL 归档(publish/<manifest.id>.jpl),同时生成对应的插件信息文件 publish/<manifest.id>.json(内含 _publish_hash 的 SHA-256 校验值与 _publish_commit 的 git 分支/提交信息),最后执行 validatePackageJson() 检查发布规范。

dist 目录存放编译产物,publish 目录存放可直接分发/安装的 JPL 归档——README 中“JPL archive 也会在根目录创建,可用于分发插件”所指即此。若 dist 目录为空,createPluginArchive() 会抛出 Plugin archive was not created because the "dist" directory is empty 并中止打包。

用示例插件验证构建链路

本文讨论的 toast 插件位于 packages/app-cli/tests/support/plugins/toast,属于 app-cli 包测试支持目录下的插件示例(packages/app-cli/tests/support/plugins/ 下还同类存放了 dialog、externalEdit 等插件样例,可用于对照学习不同 API)。验证构建时:

cd packages/app-cli/tests/support/plugins/toast
npm install
npm run dist

执行完毕后检查 dist/index.js(编译后的插件主体)与 publish/org.joplinapp.plugins.DialogDemo.jpl(可分发归档)是否生成。此外,仓库根目录还提供了一键脚手架方案 packages/generator-joplin,可用 yo joplin 生成全新插件工程,与本文模板结构完全一致。

更新插件框架:yo joplin --update 及其风险控制

插件框架(构建脚本、webpack 配置、API 类型声明等)会随 Joplin 版本迭代,官方模板的升级方式为:

yo joplin --update

该命令由 package.json 的 update 脚本包装(npm install -g generator-joplin && yo joplin --update),其实现位于 packages/generator-joplin 包中。README 特别警告了两点:

  1. 升级会覆盖 src/ 之外的所有框架相关文件——包括 package.json、.gitignore、webpack.config.js 等,你自己的源码不受影响。因此若曾修改过框架文件,务必先提交到版本控制,升级后再对比 diff 并重新应用改动。
  2. 框架文件改动越少越好:如果必须改 Webpack 配置,推荐新建一个独立 JS 文件,并在 webpack.config.js 中通过 require 引入。这样升级时只需恢复那一行引入语句即可,其余自定义内容全部保留。

这一建议与 webpack.config.js 头部注释完全一致:“不建议编辑此文件,因为更新框架时会被覆盖;如确需修改,考虑使用外部 JS 文件并在此 require 它,以最小化改动、便于升级后恢复”。例如,把自定义 loader 或插件规则写进 my-custom-webpack.js,然后在模板配置里加一行 const custom = require('./my-custom-webpack'); 即可。

结合源码纵深:showToast API 与 Toast 参数模型

toast 示例插件是理解“入口 + 清单 + 构建”之外最有价值的 API 用例,其核心 API showToast 的完整签名位于 api/JoplinViewsDialogs.d.ts:

showToast(toast: Toast): Promise<void>;

参数类型 Toast 与枚举 ToastType 定义在 api/types.ts:

export enum ToastType {
	Info = 'info',
	Success = 'success',
	Error = 'error',
}

export interface Toast {
	message: string;
	type?: ToastType;
	duration?: number;
	timestamp?: number;
}

各字段说明:

  • message(必填):toast 显示的核心文本;
  • type(可选):通知类型,取 ToastType.Info / ToastType.Success / ToastType.Error 之一;示例中省略时默认为 info 风格(第一次 showToast 调用即未传 type);
  • duration(可选):显示时长(毫秒级数值);
  • timestamp(可选):时间戳,用于定位通知的产生时刻。

示例插件分别在 5s/7s/9s 触发 info、error、success 三种 toast,正好覆盖了枚举的全部取值,是测试 showToast 视觉表现的最小可运行程序。若需更复杂的交互界面(模态对话框、按钮、HTML 内容),可在同一 API 面上使用 create()、setHtml()、setButtons()、open() 等方法,toast 与 dialog 共用 joplin.views.dialogs 这一视图管理器。

发布前自检清单

结合模板构建脚本的校验逻辑,发布前应逐项确认:

  1. package.json 命名:包名应以 joplin-plugin- 开头(否则构建仅告警不报错,但不利于发布识别);
  2. keywords:必须包含 joplin-plugin;
  3. scripts 约定:若需安装时构建,推荐使用 prepare 脚本而非 postinstall(脚本内已针对 postinstall 输出警告);
  4. manifest 完整性:id 必填;categories 若填写必须在小写白名单内且不重复;
  5. 归档产物:确认 publish/<plugin-id>.jpl 与 .json 均已生成,.json 内含发布哈希与 git 提交信息,便于追溯版本来源;
  6. 升级前提交:执行 yo joplin --update 前,先提交所有框架文件改动到版本控制。

结语

这份官方模板 README 虽短,却勾勒出 Joplin 插件开发的最小闭环:用 src/index.ts 书写逻辑、用 manifest.json 声明身份、用 npm run dist 一键产出 JPL 归档、用 yo joplin --update 低成本跟随框架演进。结合 toast 示例的 showToast API 与 webpack 三段式构建源码,开发者可以从零开始搭建插件工程,并在后续开发中把“改框架文件”视为需要版本控制与最小化策略的高风险操作。更多 API 细节可继续研读模板自带的 api/ 类型声明目录,以及 packages/generator-joplin 下的生成器实现。

登录后查看全文
joplin