Joplin 插件开发入门指南-第一步测试项目构建

Joplin 插件开发入门指南

在插件生态日益丰富的今天，为你常用的工具定制插件能极大提升工作效率。本文将带你一步步了解如何在 Joplin（一款开源笔记应用）中搭建插件开发环境、构建基础插件并完成测试，即使是新手也能快速上手。

一、前期准备：支持与捐赠（可选）

如果你觉得 Joplin 或其插件生态有帮助，可通过以下方式支持开发者：

• 通过 PayPal 捐赠
• 在 GitHub 上成为赞助商（Sponsor）
• 成为 Patron（赞助人）
• 通过 IBAN 转账捐赠

二、第一步：搭建开发环境

在开始编写插件前，需先完成基础环境配置，确保工具链齐全。

1. 安装必备软件

首先确认你的电脑已安装以下工具，它们是插件开发的基础：

• Node.js：用于运行 JavaScript/TypeScript 代码及管理依赖（建议安装 LTS 版本，确保兼容性）
• Git：用于版本控制，跟踪代码变更

2. 安装 Joplin 应用

前往 Joplin 官网 下载并安装最新版 Joplin，后续将在该应用中测试插件。

3. 安装插件生成工具

Joplin 提供了官方脚手架工具，可快速生成插件基础框架。打开终端，执行以下命令全局安装：

npm install -g yo generator-joplin

• yo：即 Yeoman，是一款流行的项目脚手架工具
• generator-joplin：Joplin 官方提供的插件生成器

4. 生成插件基础框架

1. 新建一个文件夹（作为插件项目根目录），并通过终端进入该文件夹：

   mkdir my-joplin-plugin && cd my-joplin-plugin
   

2. 执行以下命令生成脚手架：

   yo joplin
   

3. 按照终端提示输入插件信息（如名称、描述、作者等），完成后会自动生成完整的项目结构。

三、了解项目结构

生成的插件项目包含多个文件和文件夹，核心结构如下：

路径	作用
src/	插件源代码目录（核心代码存放处）
src/index.ts	插件入口文件（默认使用 TypeScript，也可改用 JavaScript）
src/manifest.json	插件配置清单（包含插件名称、版本、主页、依赖等关键信息）
dist/	编译后的输出目录（Joplin 会从这里加载插件，初始为空）
根目录配置文件	如 package.json（依赖管理）、.eslintrc（代码检查）等，通常无需修改

注意：

• manifest.json 可随时编辑，但插件发布后修改可能导致用户需重新下载插件。
• 项目默认使用 TypeScript，但你可删除 .ts 文件并新建 .js 文件，改用纯 JavaScript 开发（最终都会编译为纯 JS 供 Joplin 加载）。

四、配置版本控制（可选但推荐）

为了方便跟踪代码变更、回滚错误版本，建议用 Git 管理项目。在插件根目录执行以下命令初始化 Git 仓库：

git init

后续开发中，可通过 git add、git commit 等命令提交代码。

五、以开发模式运行 Joplin

直接在日常使用的 Joplin 中测试插件有风险（可能误删数据），因此推荐用「开发模式」运行 Joplin，其会使用独立配置文件，不影响正常数据。

无需额外配置，后续安装插件时指定开发路径即可自动启用开发模式。

六、构建并安装基础插件

生成的脚手架中，src/index.ts 已包含一个「Hello World」基础插件代码，我们可直接编译并测试。

1. 编译插件

插件需编译为 Joplin 可识别的格式，在项目根目录执行以下命令：

npm run dist

执行成功后，会在 dist/ 目录生成编译后的文件（如 index.js、manifest.json 等），这是 Joplin 实际加载的文件。

2. 在 Joplin 中安装开发插件

1. 打开 Joplin 应用，点击左侧菜单栏的「设置」（齿轮图标）。
2. 在设置页面中，选择「插件」选项卡，然后滚动到「高级设置」区域。
3. 在「开发插件」文本框中，粘贴你的插件项目根目录路径（不是 dist/ 目录），例如：
   • Windows：C:\Users\YourName\my-joplin-plugin
   • macOS/Linux：/Users/YourName/my-joplin-plugin
4. 点击「应用」保存设置。

七、测试插件：验证 Hello World

1. 关闭 Joplin，然后重新启动（确保加载新安装的开发插件）。
2. 启动后，打开 Joplin 的「插件控制台」（通常在「视图」>「开发者工具」>「插件控制台」）。
3. 如果一切正常，控制台会输出消息：Hello world. Test plugin started!，说明插件已成功运行。
4. 同时，在「设置」>「插件」页面中，可看到你的插件信息（来自 manifest.json）。

八、下一步：深入开发

恭喜！你已成功搭建 Joplin 插件开发环境并运行了第一个基础插件。接下来可通过以下资源继续深入：

1. 学习插件 API：

   • 官方插件教程：逐步讲解如何使用 API 实现复杂功能（如操作笔记、添加菜单按钮等）。
   • Plugin API 参考文档：完整的 API 列表，包含参数、返回值及示例。

2. 获取插件开发灵感：

   • 查看社区讨论：Any suggestions on what plugins could be created?，里面有大量用户需求和创意。

3. 参考现有插件：

   • 浏览 Joplin 插件市场，查看热门插件的源代码（多数开源），学习最佳实践。

通过以上步骤，你已掌握 Joplin 插件开发的核心流程。接下来就可以根据自己的需求，定制属于你的 Joplin 插件了！