Joplin 插件开发实战使用 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/joplinJoplin 是支持 Windows、macOS、Linux、Android 与 iOS 的隐私优先笔记应用插件系统是其扩展能力的关键。本文以当前仓库中的官方插件生成器 generator-joplin 为核心完整讲解从环境安装、脚手架生成、工程结构、Webpack 构建、JPL 打包到 npm 发布、框架更新的全流程并结合仓库源码生成器入口、Webpack 构建配置剖析每一步背后的实现原理读完后你可以独立创建并发布一个可被 Joplin 插件仓库收录的插件。一、什么是 generator-joplingenerator-joplin 是 Joplin 官方的 Yeoman 生成器用于快速搭建一个新的 Joplin 插件工程骨架。它位于仓库的 packages/generator-joplin 目录源码结构如下generators/app/index.jsYeoman 生成器主体负责交互式提问、模板渲染与文件落盘generators/app/utils.js工具函数包括包名规范化、package.json/忽略文件的合并策略generators/app/utils.test.js对上述工具函数的单元测试generators/app/templates/脚手架模板包含插件入口、manifest、Webpack 配置、插件 API 类型声明api/目录下的Joplin.d.ts、JoplinViews*.d.ts等以及发布辅助脚本script/publish/。仓库中由该生成器产出的真实插件示例是 packages/plugins/ToggleSidebars其目录结构src/、api/、plugin.config.json、webpack.config.js、package.json可作为你生成后工程的对照参考。二、安装与创建项目安装前请确保已预装 node.js。随后全局安装 Yeoman 与生成器npm install -g yo npm install -g generator-joplin说明在较新的模板文档 GENERATOR_DOC.md 中推荐固定 Yeoman 版本并显式指定包管理器即npm install -g yo4.3.1生成时使用yo --node-package-manager npm joplin。如果你遇到 Yeoman 版本兼容问题可以按此方式安装。生成新插件工程yo joplin交互过程中生成器会依次向你提问以下字段对应 index.js 中的 prompts 定义字段含义备注pluginId插件 ID必须是全局唯一 ID如com.example.MyPlugin或 UUID最终写入 manifestpluginName插件名用户友好的字符串显示在 UI 中pluginDescription插件描述写入 manifest 的 description 字段pluginAuthor作者写入 manifest 的 author 字段pluginRepositoryUrl仓库地址写入 manifest 的 repository_urlpluginHomepageUrl主页地址写入 manifest 的 homepage_urlpackageNamenpm 包名默认由插件名自动推导回车保留默认值或手动修改其中packageName的默认值由packageNameFromPluginName()函数计算先将特殊字符替换为-再 slugify 为小写、去除首尾横线、追加joplin-plugin-前缀并限制总长不超过 214 个字符。函数实现见 utils.js其行为有对应单元测试覆盖见 utils.test.js例如Thats my plugin!会得到joplin-plugin-that-s-my-plugin。三、生成的工程结构生成器产出的工程包含以下关键文件src/index.ts插件源码入口。模板内容通过joplin.plugins.register({ onStart })注册插件并打印一条 Hello world 日志src/manifest.json插件清单包含manifest_version、id、app_min_version模板默认3.7、version、name、description、author、homepage_url、repository_url、keywords、categories、screenshots、icons、promo_tile等字段package.jsonnpm 包配置。注意模板名以_TEMPLATE结尾这是因为 npm 对.gitignore、package.json有特殊处理生成器在落盘时才将其重命名为正式名称源码注释见 index.jstsconfig.jsonTypeScript 编译配置webpack.config.js构建与打包配置plugin.config.json插件附加配置默认内容为{extraScripts: []}用于声明需要额外编译的外部脚本api/完整的插件 API TypeScript 类型声明Joplin.d.ts、JoplinSettings.d.ts、JoplinViewsPanels.d.ts、JoplinContentScripts.d.ts等为开发提供类型提示script/publish/发布辅助脚本包含认证、构建校验、提交 payload 等步骤见 script/publish/index.ts。模板中的package.json定义了如下核心脚本scripts: { dist: webpack --env joplin-plugin-configbuildMain webpack --env joplin-plugin-configbuildExtraScripts webpack --env joplin-plugin-configcreateArchive, prepare: npm run dist, updateVersion: webpack --env joplin-plugin-configupdateVersion, update: npm install -g generator-joplin yo joplin --node-package-manager npm --update --force, submit: tsc --project script/publish/tsconfig.json node ./script/publish/dist/index.js }四、构建插件与生成 JPL 包在工程根目录执行npm run dist该命令串联执行三个 Webpack 配置阶段实现见 webpack.config.jsbuildMain编译src/index.ts及其导入的模块并借助copy-webpack-plugin将src/下其余静态资源CSS、图片、不需要编译的 JS 等复制到dist/该阶段还会先清空并重建dist/与publish/目录buildExtraScripts按plugin.config.json中的extraScripts列表逐一编译外部脚本编译产物覆盖dist/中对应文件createArchive以dist/index.js为入口触发onBuildCompleted回调见 webpack.config.js该回调负责用tar将dist/全部文件压缩为publish/pluginId.jplJPL 即 Joplin Plugin 归档是插件的分发格式生成publish/pluginId.json插件信息文件写入_publish_hashJPL 文件的 sha256 摘要格式sha256:...与_publish_commit当前 git 分支与 commit如master:abc123...非 git 仓库时跳过校验package.json的发布条件并给出告警。构建完成后dist/是编译产物目录publish/下则出现.jpl与.json两个用于分发的文件。版本号同步更新模板还提供了npm run updateVersion它会在package.json与manifest.json中同时递增补丁号如 1.0.3 → 1.0.4实现见updateVersion()webpack.config.js若两处版本号不一致会打印警告提示手动修正。五、发布插件到 Joplin 插件仓库发布前先将包发布到 npmjs.comnpm publish随后 Joplin 的自动化脚本会定期扫描并自动收录符合以下条件的包详见 GENERATOR_DOC.md 与关联文档 GENERATOR_DOC.mdpackage.json中的name以joplin-plugin-开头例如joplin-plugin-tocpackage.json中的keywords包含joplin-pluginpublish/目录中存在.jpl与.json文件由npm run dist生成。生成器默认已将这些条件配置好模板package.json的name由插件名推导并自动带上joplin-plugin-前缀keywords固定包含joplin-plugin且files字段仅包含publish目录即 npm 包中只发布publish/下的产物。构建时的自动校验逻辑validatePackageJson()也会对这三项外加避免使用postinstall脚本的提醒给出警告见 webpack.config.js。如果你的插件没有出现在仓库中请逐一复查上述条件。提示模板还内置了npm run submit脚本它先编译再执行script/publish/下的发布辅助程序用于将插件提交到插件仓库。需要仔细阅读脚本内部实现并按其要求配置认证信息后再使用。六、更新插件框架运行npm run update该命令重新全局安装 generator-joplin 并以--update模式重新生成工程update选项的处理见 index.js。更新遵循以下合并策略package.json采用mergePackageKey()递归合并utils.js。原则是目标中不存在的键从源补充keywords确保包含joplin-plugindevDependencies与scripts中的dist、prepare、update以框架版本为准否则可能导致插件构建失败其余键保留用户现有值.gitignore与.npmignore采用mergeIgnoreFile()按行去重合并utils.js其合并行为有测试用例验证utils.test.jsplugin.config.json更新时保留现有内容src/与README.md不会被触碰你的业务代码与说明文档得以完整保留。需要特别留意的是webpack.config.js会在更新时被覆盖。因此如果你要修改构建配置建议把自定义逻辑放进独立的 JS 文件再在webpack.config.js中引入这样更新后只需恢复那一行引入代码即可。七、外部脚本文件extraScripts默认情况下Webpack 只编译src/index.ts及其导入链src/下其他文件会被原样复制进插件包。但在以下两种场景中你需要让外部脚本也参与编译详见文档 GENERATOR_DOC.md 的 External script files 一节脚本是 TypeScript 文件必须编译为 JavaScript 才能运行脚本引用了你在package.json中新增的第三方模块无论 JS 还是 TS都必须编译以便依赖被打包进 JPL 文件。做法是在plugin.config.json的extraScripts数组中声明脚本路径路径相对于src/。例如你的脚本位于src/webviews/index.ts则配置为{ extraScripts: [webviews/index.ts] }编译后文件始终以.js结尾因此最终得到dist/webviews/index.js同时也是插件包内的路径你应该用这个路径在joplin.views.panels.addScript(...)、joplin.contentScripts.register(...)等 API 中引用脚本。其实现位于 webpack.config.jsresolveExtraScriptPath()会校验文件必须存在于src/下否则报错随后为每个额外脚本生成一个独立 Webpack 配置输出为commonjs库格式的name.js。该文件同时为codemirror/*与lezer/*系列库配置了 externalswebpack.config.js使内容脚本可以直接通过require(codemirror/...)使用这些由 Joplin 运行时提供的库避免重复打包。八、更多阅读与开发资源插件入口与 API 类型声明packages/generator-joplin/generators/app/templates/api/含Joplin.d.ts、JoplinContentScripts.d.ts、JoplinViewsPanels.d.ts等真实的生成器产物示例packages/plugins/ToggleSidebars含 src/index.ts、src/manifest.json、plugin.config.json构建与打包核心实现webpack.config.js生成器合并策略的单元测试utils.test.js。九、许可证generator-joplin 采用 MIT 许可证版权归 Laurent Cozic 所有见文档末尾 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Joplin 插件开发实战：使用 generator-joplin 脚手架从零构建、打包与发布插件
Joplin 插件开发实战使用 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/joplinJoplin 是支持 Windows、macOS、Linux、Android 与 iOS 的隐私优先笔记应用插件系统是其扩展能力的关键。本文以当前仓库中的官方插件生成器 generator-joplin 为核心完整讲解从环境安装、脚手架生成、工程结构、Webpack 构建、JPL 打包到 npm 发布、框架更新的全流程并结合仓库源码生成器入口、Webpack 构建配置剖析每一步背后的实现原理读完后你可以独立创建并发布一个可被 Joplin 插件仓库收录的插件。一、什么是 generator-joplingenerator-joplin 是 Joplin 官方的 Yeoman 生成器用于快速搭建一个新的 Joplin 插件工程骨架。它位于仓库的 packages/generator-joplin 目录源码结构如下generators/app/index.jsYeoman 生成器主体负责交互式提问、模板渲染与文件落盘generators/app/utils.js工具函数包括包名规范化、package.json/忽略文件的合并策略generators/app/utils.test.js对上述工具函数的单元测试generators/app/templates/脚手架模板包含插件入口、manifest、Webpack 配置、插件 API 类型声明api/目录下的Joplin.d.ts、JoplinViews*.d.ts等以及发布辅助脚本script/publish/。仓库中由该生成器产出的真实插件示例是 packages/plugins/ToggleSidebars其目录结构src/、api/、plugin.config.json、webpack.config.js、package.json可作为你生成后工程的对照参考。二、安装与创建项目安装前请确保已预装 node.js。随后全局安装 Yeoman 与生成器npm install -g yo npm install -g generator-joplin说明在较新的模板文档 GENERATOR_DOC.md 中推荐固定 Yeoman 版本并显式指定包管理器即npm install -g yo4.3.1生成时使用yo --node-package-manager npm joplin。如果你遇到 Yeoman 版本兼容问题可以按此方式安装。生成新插件工程yo joplin交互过程中生成器会依次向你提问以下字段对应 index.js 中的 prompts 定义字段含义备注pluginId插件 ID必须是全局唯一 ID如com.example.MyPlugin或 UUID最终写入 manifestpluginName插件名用户友好的字符串显示在 UI 中pluginDescription插件描述写入 manifest 的 description 字段pluginAuthor作者写入 manifest 的 author 字段pluginRepositoryUrl仓库地址写入 manifest 的 repository_urlpluginHomepageUrl主页地址写入 manifest 的 homepage_urlpackageNamenpm 包名默认由插件名自动推导回车保留默认值或手动修改其中packageName的默认值由packageNameFromPluginName()函数计算先将特殊字符替换为-再 slugify 为小写、去除首尾横线、追加joplin-plugin-前缀并限制总长不超过 214 个字符。函数实现见 utils.js其行为有对应单元测试覆盖见 utils.test.js例如Thats my plugin!会得到joplin-plugin-that-s-my-plugin。三、生成的工程结构生成器产出的工程包含以下关键文件src/index.ts插件源码入口。模板内容通过joplin.plugins.register({ onStart })注册插件并打印一条 Hello world 日志src/manifest.json插件清单包含manifest_version、id、app_min_version模板默认3.7、version、name、description、author、homepage_url、repository_url、keywords、categories、screenshots、icons、promo_tile等字段package.jsonnpm 包配置。注意模板名以_TEMPLATE结尾这是因为 npm 对.gitignore、package.json有特殊处理生成器在落盘时才将其重命名为正式名称源码注释见 index.jstsconfig.jsonTypeScript 编译配置webpack.config.js构建与打包配置plugin.config.json插件附加配置默认内容为{extraScripts: []}用于声明需要额外编译的外部脚本api/完整的插件 API TypeScript 类型声明Joplin.d.ts、JoplinSettings.d.ts、JoplinViewsPanels.d.ts、JoplinContentScripts.d.ts等为开发提供类型提示script/publish/发布辅助脚本包含认证、构建校验、提交 payload 等步骤见 script/publish/index.ts。模板中的package.json定义了如下核心脚本scripts: { dist: webpack --env joplin-plugin-configbuildMain webpack --env joplin-plugin-configbuildExtraScripts webpack --env joplin-plugin-configcreateArchive, prepare: npm run dist, updateVersion: webpack --env joplin-plugin-configupdateVersion, update: npm install -g generator-joplin yo joplin --node-package-manager npm --update --force, submit: tsc --project script/publish/tsconfig.json node ./script/publish/dist/index.js }四、构建插件与生成 JPL 包在工程根目录执行npm run dist该命令串联执行三个 Webpack 配置阶段实现见 webpack.config.jsbuildMain编译src/index.ts及其导入的模块并借助copy-webpack-plugin将src/下其余静态资源CSS、图片、不需要编译的 JS 等复制到dist/该阶段还会先清空并重建dist/与publish/目录buildExtraScripts按plugin.config.json中的extraScripts列表逐一编译外部脚本编译产物覆盖dist/中对应文件createArchive以dist/index.js为入口触发onBuildCompleted回调见 webpack.config.js该回调负责用tar将dist/全部文件压缩为publish/pluginId.jplJPL 即 Joplin Plugin 归档是插件的分发格式生成publish/pluginId.json插件信息文件写入_publish_hashJPL 文件的 sha256 摘要格式sha256:...与_publish_commit当前 git 分支与 commit如master:abc123...非 git 仓库时跳过校验package.json的发布条件并给出告警。构建完成后dist/是编译产物目录publish/下则出现.jpl与.json两个用于分发的文件。版本号同步更新模板还提供了npm run updateVersion它会在package.json与manifest.json中同时递增补丁号如 1.0.3 → 1.0.4实现见updateVersion()webpack.config.js若两处版本号不一致会打印警告提示手动修正。五、发布插件到 Joplin 插件仓库发布前先将包发布到 npmjs.comnpm publish随后 Joplin 的自动化脚本会定期扫描并自动收录符合以下条件的包详见 GENERATOR_DOC.md 与关联文档 GENERATOR_DOC.mdpackage.json中的name以joplin-plugin-开头例如joplin-plugin-tocpackage.json中的keywords包含joplin-pluginpublish/目录中存在.jpl与.json文件由npm run dist生成。生成器默认已将这些条件配置好模板package.json的name由插件名推导并自动带上joplin-plugin-前缀keywords固定包含joplin-plugin且files字段仅包含publish目录即 npm 包中只发布publish/下的产物。构建时的自动校验逻辑validatePackageJson()也会对这三项外加避免使用postinstall脚本的提醒给出警告见 webpack.config.js。如果你的插件没有出现在仓库中请逐一复查上述条件。提示模板还内置了npm run submit脚本它先编译再执行script/publish/下的发布辅助程序用于将插件提交到插件仓库。需要仔细阅读脚本内部实现并按其要求配置认证信息后再使用。六、更新插件框架运行npm run update该命令重新全局安装 generator-joplin 并以--update模式重新生成工程update选项的处理见 index.js。更新遵循以下合并策略package.json采用mergePackageKey()递归合并utils.js。原则是目标中不存在的键从源补充keywords确保包含joplin-plugindevDependencies与scripts中的dist、prepare、update以框架版本为准否则可能导致插件构建失败其余键保留用户现有值.gitignore与.npmignore采用mergeIgnoreFile()按行去重合并utils.js其合并行为有测试用例验证utils.test.jsplugin.config.json更新时保留现有内容src/与README.md不会被触碰你的业务代码与说明文档得以完整保留。需要特别留意的是webpack.config.js会在更新时被覆盖。因此如果你要修改构建配置建议把自定义逻辑放进独立的 JS 文件再在webpack.config.js中引入这样更新后只需恢复那一行引入代码即可。七、外部脚本文件extraScripts默认情况下Webpack 只编译src/index.ts及其导入链src/下其他文件会被原样复制进插件包。但在以下两种场景中你需要让外部脚本也参与编译详见文档 GENERATOR_DOC.md 的 External script files 一节脚本是 TypeScript 文件必须编译为 JavaScript 才能运行脚本引用了你在package.json中新增的第三方模块无论 JS 还是 TS都必须编译以便依赖被打包进 JPL 文件。做法是在plugin.config.json的extraScripts数组中声明脚本路径路径相对于src/。例如你的脚本位于src/webviews/index.ts则配置为{ extraScripts: [webviews/index.ts] }编译后文件始终以.js结尾因此最终得到dist/webviews/index.js同时也是插件包内的路径你应该用这个路径在joplin.views.panels.addScript(...)、joplin.contentScripts.register(...)等 API 中引用脚本。其实现位于 webpack.config.jsresolveExtraScriptPath()会校验文件必须存在于src/下否则报错随后为每个额外脚本生成一个独立 Webpack 配置输出为commonjs库格式的name.js。该文件同时为codemirror/*与lezer/*系列库配置了 externalswebpack.config.js使内容脚本可以直接通过require(codemirror/...)使用这些由 Joplin 运行时提供的库避免重复打包。八、更多阅读与开发资源插件入口与 API 类型声明packages/generator-joplin/generators/app/templates/api/含Joplin.d.ts、JoplinContentScripts.d.ts、JoplinViewsPanels.d.ts等真实的生成器产物示例packages/plugins/ToggleSidebars含 src/index.ts、src/manifest.json、plugin.config.json构建与打包核心实现webpack.config.js生成器合并策略的单元测试utils.test.js。九、许可证generator-joplin 采用 MIT 许可证版权归 Laurent Cozic 所有见文档末尾 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考