Joplin 插件开发完全指南基于 Yeoman 的 generator-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 官方插件生成器generator-joplin为核心系统讲解从零创建一个 Joplin 插件项目的完整流程环境安装、项目脚手架生成、目录结构与关键文件、Webpack 构建与 JPL 打包、版本号同步更新、发布到官方插件仓库以及 content script / webview script 等外部脚本的编译配置。文中所有命令与配置均以当前仓库中 generator-joplin 的真实模板代码为依托读者学完后可直接动手编写并发布自己的第一个 Joplin 插件。一、插件开发基础先理解 Joplin 的插件体系Joplin 是一个注重隐私的笔记应用其桌面端Windows / macOS / Linux通过插件机制对外开放扩展能力。插件本质上是一个用 TypeScript或 JavaScript编写、经过 Webpack 编译、最终打包为.jplJoplin Plugin archive压缩包的模块运行在 Electron 的 Node 环境中。开发者不需要手工搭建这一整套工程Joplin 官方提供了脚手架工具generator-joplinYeoman generator它会把标准目录、构建脚本、API 类型声明一次性生成好。该生成器在仓库中的实现位于 packages/generator-joplin其模板文件是理解整个插件工程结构的最佳参考。二、安装与项目生成2.1 前置条件开始之前需要先安装 Node.jsnodejs.org 提供下载。之后通过 npm 全局安装 Yeoman 与 generator-joplinnpm install -g yo npm install -g generator-joplin2.2 生成新项目在希望创建插件项目的目录下执行yo --node-package-manager npm joplin--node-package-manager npm显式指定使用 npm 作为包管理器。生成器会依次询问以下信息对应 generator-joplin/generators/app/index.js 中定义的 prompts提示项含义说明Plugin ID插件唯一 ID必须是全局唯一标识如com.example.MyPlugin或一个 UUIDPlugin name插件显示名称展示在 Joplin UI 中的用户友好名称Plugin description插件描述插件功能简介Author作者插件作者名Repository URL仓库地址源码仓库 URLHomepage URL主页地址插件主页 URL随后生成器会根据插件名称自动推导 npm 包名默认格式为joplin-plugin-slug并允许你按回车确认或手动修改。命名转换逻辑见 generator-joplin/generators/app/utils.js特殊字符会被替换为-非字母字符被 slugify包名最长 214 个字符并自动加上joplin-plugin-前缀。生成完成后即得到一个可直接npm install并运行的完整插件工程。三、项目结构三个最需要关心的文件生成器会写入一批文件清单见 generator-joplin/generators/app/index.js其中最重要的是以下两个/src/index.ts—— 插件源码的入口文件所有业务逻辑从这里开始/src/manifest.json—— 插件清单manifest包含插件 id、名称、版本、最低 Joplin 版本等元信息。以仓库中真实的测试插件为例packages/app-cli/tests/support/plugins/codemirror6/src/manifest.json 展示了清单的完整字段{ manifest_version: 1, id: com.example.codemirror6-line-numbers, app_min_version: 2.13, version: 1.0.0, name: CodeMirror6 line numbers, description: Displays line numbers in the CodeMirror 6 editor, author: , homepage_url: , repository_url: , keywords: [], categories: [], screenshots: [], icons: {} }生成器模板默认的 manifest见 generator-joplin/generators/app/templates/src/manifest.json中app_min_version为3.7实际编写时可按需要调低以兼容更多 Joplin 版本。第三个值得了解的文件是/plugin.config.json。若你的插件需要编译 content script 或 webview script 等外部脚本就要在这里配置extraScripts数组详见第六节。四、构建插件npm run dist插件使用 Webpack 构建构建产物分为两部分/dist目录编译后的代码仓库根目录下的.jpl归档可分发、可安装到 Joplin 的插件包。构建命令只有一个npm run dist该命令在模板的 package_TEMPLATE.json 中定义实际由三个依次执行的 Webpack 步骤组成dist: webpack --env joplin-plugin-configbuildMain webpack --env joplin-plugin-configbuildExtraScripts webpack --env joplin-plugin-configcreateArchive三个步骤的含义见 generator-joplin/generators/app/templates/webpack.config.js 中的configs定义buildMain编译入口src/index.ts及它 import 的所有模块并把/src下的其他内容CSS、脚本、资源复制到/dist同时清理并重建dist与publish目录buildExtraScripts按plugin.config.json中的extraScripts逐个编译外部脚本如 TS 文件或带有第三方依赖的 JS 文件createArchive把/dist内容用 tar 打包成.jpl文件实现见createPluginArchivewebpack.config.js并额外生成包含插件元信息与_publish_hash、_publish_commit的.json信息文件createPluginInfo输出到publish/目录。构建完成后publish/目录中会出现manifest.id.jpl与manifest.id.json两个文件它们正是插件发布所需的内容。项目默认使用 TypeScript模板通过 ts-loader 编译*.tsx?文件见 webpack.config.js。如果你更喜欢纯 JavaScript调整 Webpack 配置即可生成器并不强制。此外模板还提供prepare脚本npm run prepare会先执行npm run dist这保证了发布前构建产物一定存在。五、版本号管理npm run updateVersion插件版本号需要同时维护在package.json与src/manifest.json两处。为避免手改造成的不一致运行npm run updateVersion该命令实现见 webpack.config.js 中的updateVersion会把两处版本号的patch 位加一例如1.0.3变为1.0.4并保持两者同步。若同步后发现仍不一致脚本会打印警告提示手动对齐。注意它只递增最后一段数字主版本与次版本需要你自行调整。六、发布插件到 Joplin 插件仓库6.1 发布步骤将插件发布到 npmjs.comnpm publish之后官方脚本会自动把满足条件的插件收录进 Joplin 插件仓库前提是 package.json 满足以下三个条件包名以joplin-plugin-开头例如joplin-plugin-tockeywords 中包含joplin-pluginpublish/目录中存在.jpl与.json文件由npm run dist生成。正常情况下生成器已自动完成上述配置package.json的 name 与 keywords 均正确设置keywords 默认含joplin-plugin见 package_TEMPLATE.jsondist会输出正确的publish内容。如果发布后插件没有出现在仓库中请按上述三点逐项排查。6.2 构建期校验逻辑构建脚本会在打包后执行validatePackageJson见 webpack.config.js对包名、keywords、postinstall 脚本给出黄色警告——这些警告是发布条件的第一道防线。同时readManifest会校验 manifest 中的categories必须小写且来自白名单与screenshots本地截图需为 jpg/jpeg/png/gif/webp 且不超过 1MB不合法直接抛错中止构建。七、更新插件框架npm run updateJoplin 插件框架会持续演进模板提供了更新命令npm run update它实际上执行的是见 package_TEMPLATE.jsonupdate: npm install -g generator-joplin yo joplin --node-package-manager npm --update --force即先升级全局 generator-joplin再以--update模式重新运行生成器。更新模式的合并策略见 generator-joplin/generators/app/index.js 与 utils.jspackage.json采用“合并而非覆盖”策略——已有键保留你的值缺失的键补上框架新值keywords确保包含joplin-plugindevDependencies以框架版本为准dist、prepare、update等关键 scripts 强制采用框架版本.gitignore / .npmignore按行去重合并mergeIgnoreFile/src 目录与 README.md完全不动你的代码与文档不会丢失plugin.config.json保留你现有的内容当前策略是原样保留见 index.js 的注释webpack.config.js会被整体覆盖。正因为webpack.config.js会被覆盖官方建议如需自定义构建逻辑把改动写进一个单独的 JS 文件然后在webpack.config.js中require它。这样每次更新框架后只需恢复那一行 include 语句即可自定义逻辑永远不会被冲掉。八、外部脚本文件content scripts 与 webview scripts8.1 什么时候需要编译外部脚本默认情况下Webpack 只编译src/index.ts以及它 import 的文件其余文件原样复制进插件包。这对多数场景已经足够但在以下两种情况content script 或 webview script 必须被额外编译脚本是 TypeScript 文件—— 必须先编译成 JavaScript 才能运行脚本 require 了你在 package.json 中新增的第三方模块—— 无论 JS 还是 TS都必须编译把这些依赖一并打进.jpl否则运行时找不到依赖。8.2 配置 extraScripts将需要编译的外部脚本加入plugin.config.json的extraScripts数组路径相对于/src。例如/src/webviews/index.ts应写为{ extraScripts: [webviews/index.ts] }编译产物固定使用.js扩展名输出到/dist下同名路径即webviews/index.js。之后在代码中引用该路径即可。仓库中的真实示例测试插件 packages/app-cli/tests/support/plugins/codemirror6/plugin.config.json 配置为{ extraScripts: [ contentScript.ts ] }其src/contentScript.ts会被编译为dist/contentScript.js。构建脚本中对应的路径解析与输出配置见 webpack.config.jsresolveExtraScriptPath与buildExtraScriptConfigs入口指向./src/name输出文件名去掉原扩展名并强制为.js。8.3 外部脚本可用的内置库对于 content script模板在 webpack.config.js 中把一批 CodeMirror 6 生态库声明为 external不打进产物运行时通过require(...)或joplin.require(...)从 Joplin 环境获取包括codemirror/view、codemirror/state、codemirror/search、codemirror/language、codemirror/autocomplete、codemirror/commands、codemirror/highlight、codemirror/lintcodemirror/lang-html、codemirror/lang-markdown、codemirror/language-datalezer/common、lezer/markdown、lezer/highlight这意味着编写编辑器扩展类插件时可以直接require(codemirror/view)等而不必担心打包体积与依赖冲突。8.4 普通资源文件怎么办不需要编译的资源CSS、图片、纯 JS 等无需任何配置buildMain 阶段会通过 copy-webpack-plugin 把/src下所有非.ts/.tsx文件复制到/dist见 webpack.config.js再随.jpl一起分发。codemirror6 插件中src/assets/style.css正是这样被原样带入插件包的。九、其他信息与参考资料官方还提供以下参考资料对应原文档链接访问时请以 joplinapp.org 官方文档为准Joplin Plugin API以joplin.*开头的插件运行时 API 文档含 JoplinContentScripts、JoplinViewsPanels 等类的完整说明Joplin Data API通过 HTTP 访问笔记数据的 REST APIJoplin Plugin Manifestmanifest.json 各字段的完整参考社区求助渠道Joplin 官方论坛与 Discord 频道。本仓库中还内置了完整的插件 API 类型声明与大量可运行的示例插件。想要进阶学习的读者可以直接阅读 generator-joplin/generators/app/templates/api 下的.d.ts类型文件了解全部 API 形态或在 packages/app-cli/tests/support/plugins 目录中浏览 content_script、settings、dialog、menu、editor_context_menu 等 20 余个覆盖不同 API 面的真实测试插件。十、许可证generator-joplin 及相关模板代码以MIT许可证发布版权归 Laurent Cozic 所有见仓库根目录 LICENSE。小结从一个yo joplin命令开始到npm run dist构建 JPL再到npm publish发布generator-joplin 已经把插件开发中繁琐的工程化细节全部封装好。理解manifest.json、plugin.config.json与webpack.config.js三个文件的职责边界就能在框架自动更新的前提下长期维护自己的插件。【免费下载链接】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），仅供参考
Joplin 插件开发完全指南：基于 Yeoman 的 generator-joplin 构建、打包与发布实战
Joplin 插件开发完全指南基于 Yeoman 的 generator-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 官方插件生成器generator-joplin为核心系统讲解从零创建一个 Joplin 插件项目的完整流程环境安装、项目脚手架生成、目录结构与关键文件、Webpack 构建与 JPL 打包、版本号同步更新、发布到官方插件仓库以及 content script / webview script 等外部脚本的编译配置。文中所有命令与配置均以当前仓库中 generator-joplin 的真实模板代码为依托读者学完后可直接动手编写并发布自己的第一个 Joplin 插件。一、插件开发基础先理解 Joplin 的插件体系Joplin 是一个注重隐私的笔记应用其桌面端Windows / macOS / Linux通过插件机制对外开放扩展能力。插件本质上是一个用 TypeScript或 JavaScript编写、经过 Webpack 编译、最终打包为.jplJoplin Plugin archive压缩包的模块运行在 Electron 的 Node 环境中。开发者不需要手工搭建这一整套工程Joplin 官方提供了脚手架工具generator-joplinYeoman generator它会把标准目录、构建脚本、API 类型声明一次性生成好。该生成器在仓库中的实现位于 packages/generator-joplin其模板文件是理解整个插件工程结构的最佳参考。二、安装与项目生成2.1 前置条件开始之前需要先安装 Node.jsnodejs.org 提供下载。之后通过 npm 全局安装 Yeoman 与 generator-joplinnpm install -g yo npm install -g generator-joplin2.2 生成新项目在希望创建插件项目的目录下执行yo --node-package-manager npm joplin--node-package-manager npm显式指定使用 npm 作为包管理器。生成器会依次询问以下信息对应 generator-joplin/generators/app/index.js 中定义的 prompts提示项含义说明Plugin ID插件唯一 ID必须是全局唯一标识如com.example.MyPlugin或一个 UUIDPlugin name插件显示名称展示在 Joplin UI 中的用户友好名称Plugin description插件描述插件功能简介Author作者插件作者名Repository URL仓库地址源码仓库 URLHomepage URL主页地址插件主页 URL随后生成器会根据插件名称自动推导 npm 包名默认格式为joplin-plugin-slug并允许你按回车确认或手动修改。命名转换逻辑见 generator-joplin/generators/app/utils.js特殊字符会被替换为-非字母字符被 slugify包名最长 214 个字符并自动加上joplin-plugin-前缀。生成完成后即得到一个可直接npm install并运行的完整插件工程。三、项目结构三个最需要关心的文件生成器会写入一批文件清单见 generator-joplin/generators/app/index.js其中最重要的是以下两个/src/index.ts—— 插件源码的入口文件所有业务逻辑从这里开始/src/manifest.json—— 插件清单manifest包含插件 id、名称、版本、最低 Joplin 版本等元信息。以仓库中真实的测试插件为例packages/app-cli/tests/support/plugins/codemirror6/src/manifest.json 展示了清单的完整字段{ manifest_version: 1, id: com.example.codemirror6-line-numbers, app_min_version: 2.13, version: 1.0.0, name: CodeMirror6 line numbers, description: Displays line numbers in the CodeMirror 6 editor, author: , homepage_url: , repository_url: , keywords: [], categories: [], screenshots: [], icons: {} }生成器模板默认的 manifest见 generator-joplin/generators/app/templates/src/manifest.json中app_min_version为3.7实际编写时可按需要调低以兼容更多 Joplin 版本。第三个值得了解的文件是/plugin.config.json。若你的插件需要编译 content script 或 webview script 等外部脚本就要在这里配置extraScripts数组详见第六节。四、构建插件npm run dist插件使用 Webpack 构建构建产物分为两部分/dist目录编译后的代码仓库根目录下的.jpl归档可分发、可安装到 Joplin 的插件包。构建命令只有一个npm run dist该命令在模板的 package_TEMPLATE.json 中定义实际由三个依次执行的 Webpack 步骤组成dist: webpack --env joplin-plugin-configbuildMain webpack --env joplin-plugin-configbuildExtraScripts webpack --env joplin-plugin-configcreateArchive三个步骤的含义见 generator-joplin/generators/app/templates/webpack.config.js 中的configs定义buildMain编译入口src/index.ts及它 import 的所有模块并把/src下的其他内容CSS、脚本、资源复制到/dist同时清理并重建dist与publish目录buildExtraScripts按plugin.config.json中的extraScripts逐个编译外部脚本如 TS 文件或带有第三方依赖的 JS 文件createArchive把/dist内容用 tar 打包成.jpl文件实现见createPluginArchivewebpack.config.js并额外生成包含插件元信息与_publish_hash、_publish_commit的.json信息文件createPluginInfo输出到publish/目录。构建完成后publish/目录中会出现manifest.id.jpl与manifest.id.json两个文件它们正是插件发布所需的内容。项目默认使用 TypeScript模板通过 ts-loader 编译*.tsx?文件见 webpack.config.js。如果你更喜欢纯 JavaScript调整 Webpack 配置即可生成器并不强制。此外模板还提供prepare脚本npm run prepare会先执行npm run dist这保证了发布前构建产物一定存在。五、版本号管理npm run updateVersion插件版本号需要同时维护在package.json与src/manifest.json两处。为避免手改造成的不一致运行npm run updateVersion该命令实现见 webpack.config.js 中的updateVersion会把两处版本号的patch 位加一例如1.0.3变为1.0.4并保持两者同步。若同步后发现仍不一致脚本会打印警告提示手动对齐。注意它只递增最后一段数字主版本与次版本需要你自行调整。六、发布插件到 Joplin 插件仓库6.1 发布步骤将插件发布到 npmjs.comnpm publish之后官方脚本会自动把满足条件的插件收录进 Joplin 插件仓库前提是 package.json 满足以下三个条件包名以joplin-plugin-开头例如joplin-plugin-tockeywords 中包含joplin-pluginpublish/目录中存在.jpl与.json文件由npm run dist生成。正常情况下生成器已自动完成上述配置package.json的 name 与 keywords 均正确设置keywords 默认含joplin-plugin见 package_TEMPLATE.jsondist会输出正确的publish内容。如果发布后插件没有出现在仓库中请按上述三点逐项排查。6.2 构建期校验逻辑构建脚本会在打包后执行validatePackageJson见 webpack.config.js对包名、keywords、postinstall 脚本给出黄色警告——这些警告是发布条件的第一道防线。同时readManifest会校验 manifest 中的categories必须小写且来自白名单与screenshots本地截图需为 jpg/jpeg/png/gif/webp 且不超过 1MB不合法直接抛错中止构建。七、更新插件框架npm run updateJoplin 插件框架会持续演进模板提供了更新命令npm run update它实际上执行的是见 package_TEMPLATE.jsonupdate: npm install -g generator-joplin yo joplin --node-package-manager npm --update --force即先升级全局 generator-joplin再以--update模式重新运行生成器。更新模式的合并策略见 generator-joplin/generators/app/index.js 与 utils.jspackage.json采用“合并而非覆盖”策略——已有键保留你的值缺失的键补上框架新值keywords确保包含joplin-plugindevDependencies以框架版本为准dist、prepare、update等关键 scripts 强制采用框架版本.gitignore / .npmignore按行去重合并mergeIgnoreFile/src 目录与 README.md完全不动你的代码与文档不会丢失plugin.config.json保留你现有的内容当前策略是原样保留见 index.js 的注释webpack.config.js会被整体覆盖。正因为webpack.config.js会被覆盖官方建议如需自定义构建逻辑把改动写进一个单独的 JS 文件然后在webpack.config.js中require它。这样每次更新框架后只需恢复那一行 include 语句即可自定义逻辑永远不会被冲掉。八、外部脚本文件content scripts 与 webview scripts8.1 什么时候需要编译外部脚本默认情况下Webpack 只编译src/index.ts以及它 import 的文件其余文件原样复制进插件包。这对多数场景已经足够但在以下两种情况content script 或 webview script 必须被额外编译脚本是 TypeScript 文件—— 必须先编译成 JavaScript 才能运行脚本 require 了你在 package.json 中新增的第三方模块—— 无论 JS 还是 TS都必须编译把这些依赖一并打进.jpl否则运行时找不到依赖。8.2 配置 extraScripts将需要编译的外部脚本加入plugin.config.json的extraScripts数组路径相对于/src。例如/src/webviews/index.ts应写为{ extraScripts: [webviews/index.ts] }编译产物固定使用.js扩展名输出到/dist下同名路径即webviews/index.js。之后在代码中引用该路径即可。仓库中的真实示例测试插件 packages/app-cli/tests/support/plugins/codemirror6/plugin.config.json 配置为{ extraScripts: [ contentScript.ts ] }其src/contentScript.ts会被编译为dist/contentScript.js。构建脚本中对应的路径解析与输出配置见 webpack.config.jsresolveExtraScriptPath与buildExtraScriptConfigs入口指向./src/name输出文件名去掉原扩展名并强制为.js。8.3 外部脚本可用的内置库对于 content script模板在 webpack.config.js 中把一批 CodeMirror 6 生态库声明为 external不打进产物运行时通过require(...)或joplin.require(...)从 Joplin 环境获取包括codemirror/view、codemirror/state、codemirror/search、codemirror/language、codemirror/autocomplete、codemirror/commands、codemirror/highlight、codemirror/lintcodemirror/lang-html、codemirror/lang-markdown、codemirror/language-datalezer/common、lezer/markdown、lezer/highlight这意味着编写编辑器扩展类插件时可以直接require(codemirror/view)等而不必担心打包体积与依赖冲突。8.4 普通资源文件怎么办不需要编译的资源CSS、图片、纯 JS 等无需任何配置buildMain 阶段会通过 copy-webpack-plugin 把/src下所有非.ts/.tsx文件复制到/dist见 webpack.config.js再随.jpl一起分发。codemirror6 插件中src/assets/style.css正是这样被原样带入插件包的。九、其他信息与参考资料官方还提供以下参考资料对应原文档链接访问时请以 joplinapp.org 官方文档为准Joplin Plugin API以joplin.*开头的插件运行时 API 文档含 JoplinContentScripts、JoplinViewsPanels 等类的完整说明Joplin Data API通过 HTTP 访问笔记数据的 REST APIJoplin Plugin Manifestmanifest.json 各字段的完整参考社区求助渠道Joplin 官方论坛与 Discord 频道。本仓库中还内置了完整的插件 API 类型声明与大量可运行的示例插件。想要进阶学习的读者可以直接阅读 generator-joplin/generators/app/templates/api 下的.d.ts类型文件了解全部 API 形态或在 packages/app-cli/tests/support/plugins 目录中浏览 content_script、settings、dialog、menu、editor_context_menu 等 20 余个覆盖不同 API 面的真实测试插件。十、许可证generator-joplin 及相关模板代码以MIT许可证发布版权归 Laurent Cozic 所有见仓库根目录 LICENSE。小结从一个yo joplin命令开始到npm run dist构建 JPL再到npm publish发布generator-joplin 已经把插件开发中繁琐的工程化细节全部封装好。理解manifest.json、plugin.config.json与webpack.config.js三个文件的职责边界就能在框架自动更新的前提下长期维护自己的插件。【免费下载链接】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），仅供参考
