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 的插件生态建立在一套标准化的工程流程之上而 generator-joplin 正是负责初始化插件工程的官方 Yeoman 生成器。本文以仓库中的用户文档 GENERATOR_DOC.md 为核心骨架结合生成器源码与脚手架模板完整讲解插件的安装、工程结构、构建、发布、框架升级与外部脚本编译帮助你从零产出可提交到 Joplin 官方插件仓库的 JPL 插件包。一、generator-joplin 是什么generator-joplin 是一个基于 Yeoman 的项目脚手架生成器用于快速创建结构完整、可直接开发、构建与发布的 Joplin 插件工程。它位于仓库的 packages/generator-joplin 目录下其生成的模板同时被官方插件仓库如仓库内的 ToggleSidebars 示例插件所使用是 Joplin 插件开发的统一起点。从实现上看生成器主体 继承自yeoman-generator通过问答prompting→ 写入writing两个阶段完成脚手架搭建先收集插件元信息再把 templates 目录 下的模板文件按用户输入渲染到目标目录。二、安装与快速开始与所有 Yeoman 生成器一样需要先全局安装yo与generator-joplin依赖 Node.js 与 npm 环境npm install -g yo npm install -g generator-joplin然后进入你想要放置插件的目录执行yo joplin生成器会以交互式问答的方式向你收集以下字段对应 index.js 中的 prompts 定义字段含义pluginId全局唯一的插件 ID例如com.example.MyPlugin或一个 UUIDpluginName插件显示名称会出现在 Joplin 界面中pluginDescription插件功能描述pluginAuthor作者名pluginRepositoryUrl源码仓库地址pluginHomepageUrl插件主页地址packageNamenpm 包名默认由插件名自动推导直接回车可接受默认值其中默认 npm 包名由 utils.js 中的packageNameFromPluginName自动生成先把插件名中的特殊字符替换为-再经 slugify 转小写、去除首尾连字符最后加上joplin-plugin-前缀总长度限制 214 字符。例如插件名 Table of Contents 会得到joplin-plugin-table-of-contents这样的包名。三、生成的项目结构生成后的插件工程核心文件如下原文档明确指出最需要关注的是src/下的两个文件plugin-root/ ├── src/ │ ├── index.ts # 插件源码入口 │ └── manifest.json # 插件清单名称、版本、ID 等 ├── api/ # Joplin 插件 API 的 TypeScript 类型声明 ├── script/publish/ # 发布辅助脚本含认证、校验、提交步骤 ├── plugin.config.json # 构建配置extraScripts 等 ├── package.json ├── tsconfig.json ├── webpack.config.js ├── .gitignore / .npmignore └── README.md3.1 入口文件src/index.ts模板入口非常精简它从api导入joplin全局对象并注册插件回调见 模板源码import joplin from api; joplin.plugins.register({ onStart: async function() { console.info(Hello world. Test plugin started!); }, });api并非一个真实 npm 依赖而是通过 webpack.config.js 中的 alias 配置 指向本地api/目录。该目录内是完整的插件 API 类型声明Joplin.d.ts、JoplinContentScripts.d.ts、JoplinViewsPanels.d.ts等api/index.ts统一导出joplin实例类型见 api_index.ts让你在开发时获得完整的类型提示。3.2 清单文件src/manifest.json模板清单见 manifest.json 模板包含发布所需的核心字段{ manifest_version: 1, id: % pluginId %, app_min_version: 3.7, version: 1.0.0, name: % pluginName %, description: % pluginDescription %, author: % pluginAuthor %, homepage_url: % pluginHomepageUrl %, repository_url: % pluginRepositoryUrl %, keywords: [], categories: [], screenshots: [], icons: {}, promo_tile: {} }其中categories与screenshots会在构建时被校验类别必须来自allPossibleCategories白名单appearance、developer tools、productivity、themes、integrations、viewer、search、tags、editor、files、personal knowledge management由 updateCategories.ts 自动维护且不允许重复截图仅支持 jpg/jpeg/png/gif/webp 且单张不超过 1MB见 webpack.config.js 中的校验函数。3.3 构建配置plugin.config.jsonplugin.config.json 默认内容为{extraScripts: []}仅在你需要编译额外脚本时才需要修改详见第七节。四、构建插件一条命令产出 JPL 归档执行npm run dist即可完成构建。该命令来自 package_TEMPLATE.json 中的 scripts 定义dist: webpack --env joplin-plugin-configbuildMain webpack --env joplin-plugin-configbuildExtraScripts webpack --env joplin-plugin-configcreateArchive它依次触发 webpack.config.js 中的三个阶段buildMain以src/index.ts为入口编译主插件逻辑并把src/下其余资源CSS、图片、未被编译的 JS 等复制到dist/同时清理重建dist/与publish/目录buildExtraScripts按plugin.config.json中的extraScripts逐个编译外部脚本详见第七节createArchive将dist/打包为.jpl归档并生成插件信息文件这一步会在 webpack 完成钩子中执行见 onBuildCompleted。构建产物有两类dist/编译后的完整插件代码与资源publish/pluginId.jpl与publish/pluginId.json可分发/提交的 JPL 归档与配套信息文件。其中.json会额外写入_publish_hashJPL 文件的 sha256 摘要与_publish_commit当前 git 分支与提交号供插件仓库校验来源见 createPluginInfo。默认工程使用 TypeScript但 tsconfig 与 webpack 的allowJs配置允许你改用纯 JavaScript 开发见 tsconfig.json 模板 与 webpack 的 ts-loader 规则。五、发布插件到 Joplin 插件仓库构建完成后通过npm publish把插件发布到 npmjs.com之后官方脚本会自动收录插件到 Joplin 插件仓库前提是满足以下三个条件这也是 validatePackageJson 在构建时检查的内容package.json的name以joplin-plugin-开头例如joplin-plugin-tocpackage.json的keywords中包含joplin-pluginpublish/目录下存在.jpl与.json文件由npm run dist生成。正常情况下生成器已自动完成上述配置模板package.json的files字段只包含publish目录见 package_TEMPLATE.json确保 npm 发布时只携带插件归档。若插件未出现在插件仓库中请按上述三点逐项排查。此外模板还内置了一条npm run submit发布脚本tsc --project script/publish/tsconfig.json node ./script/publish/dist/index.js其发布流程分为 authenticate认证、verifyBuild校验构建产物、verifyGitState校验 git 状态、submitPayload提交载荷四个步骤见 script/publish 目录。六、更新插件框架npm run update当 Joplin 插件框架升级后执行npm run update该命令会先重新安装最新版generator-joplin再以更新模式重新运行生成器yo joplin --node-package-manager npm --update --force。从 index.js 的 update 分支 可以看出更新策略package.json与.gitignore/.npmignore采用智能合并而非覆盖合并逻辑实现在 utils.js 的mergePackageKey与mergeIgnoreFile中。mergePackageKey会保留你已经自定义的字段只补充缺失的键、强制保留joplin-plugin关键字、用新版本覆盖devDependencies以及dist/prepare/update等关键脚本mergeIgnoreFile则把新旧忽略规则按行去重合并。src/目录与 README.md 完全不受影响这三类文件src/index.ts、src/manifest.json、README.md被列入noUpdateFiles更新时直接跳过你的插件代码与说明文档安全无损。plugin.config.json保留现状更新时不会改动其中已配置的内容。webpack.config.js会被整体覆盖这是最容易引发问题的文件。原文档明确建议如需自定义构建行为不要在 webpack.config.js 中直接改动而是把自定义逻辑抽到独立的 JavaScript 文件中再在 webpack.config.js 里引入。这样框架升级后只需恢复那一行引入语句即可。另外模板还提供npm run updateVersion用于统一递增package.json与manifest.json中的版本号实现见 updateVersion 函数仅递增最后一段版本号。七、外部脚本文件content scripts 与 webview scripts 的编译默认情况下 webpack 只编译src/index.ts以及它 import 的文件其余文件会被原样复制到插件包中。但有两种情况必须额外编译对应 Joplin 的 content scripts 与 webview scripts 功能脚本本身是 TypeScript 文件必须先编译成 JavaScript脚本依赖了你加入package.json的第三方模块无论 JS 还是 TS都必须编译使依赖被捆绑进 JPL 文件否则运行时无法解析。具体做法是在plugin.config.json的extraScripts数组中声明脚本路径路径相对于src/目录。例如src/webviews/index.ts对应配置{ extraScripts: [webviews/index.ts] }编译后产物固定使用.js扩展名因此插件包内对应文件是webviews/index.js——在代码中引用外部脚本时要用这个编译后的路径。底层实现见 resolveExtraScriptPath它把src/name作为 webpack 入口输出到dist/下同名去扩展名的.js文件同时为 content scripts 预置了codemirror/*与lezer/*系列的 externals见 externalContentScriptLibraries使这些库既可以被require使用又不会重复打包进每个脚本。八、从模板到实战进一步探索理解生成器与模板后你可以沿着以下仓库路径继续深入阅读完整 API 类型声明了解插件可调用的全部能力api 类型声明目录查看仓库内真实插件 ToggleSidebars 的工程形态对照模板理解生产级插件的组织方式官方默认插件如 default-plugins 构建脚本同样基于这套脚手架体系维护可作为多插件工程与发布流水线的参考插件运行期的注册机制与内容脚本 API可结合 lib 包中的 plugin 相关类型 进一步研读。至此从npm install -g yo generator-joplin、yo joplin初始化到npm run dist构建、npm publish发布、npm run update升级框架、extraScripts编译外部脚本Joplin 插件从零到发布的完整生命周期已经全部打通。这套由生成器、Webpack 模板与发布脚本组成的工程链是 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创作声明：本文部分内容由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 的插件生态建立在一套标准化的工程流程之上而 generator-joplin 正是负责初始化插件工程的官方 Yeoman 生成器。本文以仓库中的用户文档 GENERATOR_DOC.md 为核心骨架结合生成器源码与脚手架模板完整讲解插件的安装、工程结构、构建、发布、框架升级与外部脚本编译帮助你从零产出可提交到 Joplin 官方插件仓库的 JPL 插件包。一、generator-joplin 是什么generator-joplin 是一个基于 Yeoman 的项目脚手架生成器用于快速创建结构完整、可直接开发、构建与发布的 Joplin 插件工程。它位于仓库的 packages/generator-joplin 目录下其生成的模板同时被官方插件仓库如仓库内的 ToggleSidebars 示例插件所使用是 Joplin 插件开发的统一起点。从实现上看生成器主体 继承自yeoman-generator通过问答prompting→ 写入writing两个阶段完成脚手架搭建先收集插件元信息再把 templates 目录 下的模板文件按用户输入渲染到目标目录。二、安装与快速开始与所有 Yeoman 生成器一样需要先全局安装yo与generator-joplin依赖 Node.js 与 npm 环境npm install -g yo npm install -g generator-joplin然后进入你想要放置插件的目录执行yo joplin生成器会以交互式问答的方式向你收集以下字段对应 index.js 中的 prompts 定义字段含义pluginId全局唯一的插件 ID例如com.example.MyPlugin或一个 UUIDpluginName插件显示名称会出现在 Joplin 界面中pluginDescription插件功能描述pluginAuthor作者名pluginRepositoryUrl源码仓库地址pluginHomepageUrl插件主页地址packageNamenpm 包名默认由插件名自动推导直接回车可接受默认值其中默认 npm 包名由 utils.js 中的packageNameFromPluginName自动生成先把插件名中的特殊字符替换为-再经 slugify 转小写、去除首尾连字符最后加上joplin-plugin-前缀总长度限制 214 字符。例如插件名 Table of Contents 会得到joplin-plugin-table-of-contents这样的包名。三、生成的项目结构生成后的插件工程核心文件如下原文档明确指出最需要关注的是src/下的两个文件plugin-root/ ├── src/ │ ├── index.ts # 插件源码入口 │ └── manifest.json # 插件清单名称、版本、ID 等 ├── api/ # Joplin 插件 API 的 TypeScript 类型声明 ├── script/publish/ # 发布辅助脚本含认证、校验、提交步骤 ├── plugin.config.json # 构建配置extraScripts 等 ├── package.json ├── tsconfig.json ├── webpack.config.js ├── .gitignore / .npmignore └── README.md3.1 入口文件src/index.ts模板入口非常精简它从api导入joplin全局对象并注册插件回调见 模板源码import joplin from api; joplin.plugins.register({ onStart: async function() { console.info(Hello world. Test plugin started!); }, });api并非一个真实 npm 依赖而是通过 webpack.config.js 中的 alias 配置 指向本地api/目录。该目录内是完整的插件 API 类型声明Joplin.d.ts、JoplinContentScripts.d.ts、JoplinViewsPanels.d.ts等api/index.ts统一导出joplin实例类型见 api_index.ts让你在开发时获得完整的类型提示。3.2 清单文件src/manifest.json模板清单见 manifest.json 模板包含发布所需的核心字段{ manifest_version: 1, id: % pluginId %, app_min_version: 3.7, version: 1.0.0, name: % pluginName %, description: % pluginDescription %, author: % pluginAuthor %, homepage_url: % pluginHomepageUrl %, repository_url: % pluginRepositoryUrl %, keywords: [], categories: [], screenshots: [], icons: {}, promo_tile: {} }其中categories与screenshots会在构建时被校验类别必须来自allPossibleCategories白名单appearance、developer tools、productivity、themes、integrations、viewer、search、tags、editor、files、personal knowledge management由 updateCategories.ts 自动维护且不允许重复截图仅支持 jpg/jpeg/png/gif/webp 且单张不超过 1MB见 webpack.config.js 中的校验函数。3.3 构建配置plugin.config.jsonplugin.config.json 默认内容为{extraScripts: []}仅在你需要编译额外脚本时才需要修改详见第七节。四、构建插件一条命令产出 JPL 归档执行npm run dist即可完成构建。该命令来自 package_TEMPLATE.json 中的 scripts 定义dist: webpack --env joplin-plugin-configbuildMain webpack --env joplin-plugin-configbuildExtraScripts webpack --env joplin-plugin-configcreateArchive它依次触发 webpack.config.js 中的三个阶段buildMain以src/index.ts为入口编译主插件逻辑并把src/下其余资源CSS、图片、未被编译的 JS 等复制到dist/同时清理重建dist/与publish/目录buildExtraScripts按plugin.config.json中的extraScripts逐个编译外部脚本详见第七节createArchive将dist/打包为.jpl归档并生成插件信息文件这一步会在 webpack 完成钩子中执行见 onBuildCompleted。构建产物有两类dist/编译后的完整插件代码与资源publish/pluginId.jpl与publish/pluginId.json可分发/提交的 JPL 归档与配套信息文件。其中.json会额外写入_publish_hashJPL 文件的 sha256 摘要与_publish_commit当前 git 分支与提交号供插件仓库校验来源见 createPluginInfo。默认工程使用 TypeScript但 tsconfig 与 webpack 的allowJs配置允许你改用纯 JavaScript 开发见 tsconfig.json 模板 与 webpack 的 ts-loader 规则。五、发布插件到 Joplin 插件仓库构建完成后通过npm publish把插件发布到 npmjs.com之后官方脚本会自动收录插件到 Joplin 插件仓库前提是满足以下三个条件这也是 validatePackageJson 在构建时检查的内容package.json的name以joplin-plugin-开头例如joplin-plugin-tocpackage.json的keywords中包含joplin-pluginpublish/目录下存在.jpl与.json文件由npm run dist生成。正常情况下生成器已自动完成上述配置模板package.json的files字段只包含publish目录见 package_TEMPLATE.json确保 npm 发布时只携带插件归档。若插件未出现在插件仓库中请按上述三点逐项排查。此外模板还内置了一条npm run submit发布脚本tsc --project script/publish/tsconfig.json node ./script/publish/dist/index.js其发布流程分为 authenticate认证、verifyBuild校验构建产物、verifyGitState校验 git 状态、submitPayload提交载荷四个步骤见 script/publish 目录。六、更新插件框架npm run update当 Joplin 插件框架升级后执行npm run update该命令会先重新安装最新版generator-joplin再以更新模式重新运行生成器yo joplin --node-package-manager npm --update --force。从 index.js 的 update 分支 可以看出更新策略package.json与.gitignore/.npmignore采用智能合并而非覆盖合并逻辑实现在 utils.js 的mergePackageKey与mergeIgnoreFile中。mergePackageKey会保留你已经自定义的字段只补充缺失的键、强制保留joplin-plugin关键字、用新版本覆盖devDependencies以及dist/prepare/update等关键脚本mergeIgnoreFile则把新旧忽略规则按行去重合并。src/目录与 README.md 完全不受影响这三类文件src/index.ts、src/manifest.json、README.md被列入noUpdateFiles更新时直接跳过你的插件代码与说明文档安全无损。plugin.config.json保留现状更新时不会改动其中已配置的内容。webpack.config.js会被整体覆盖这是最容易引发问题的文件。原文档明确建议如需自定义构建行为不要在 webpack.config.js 中直接改动而是把自定义逻辑抽到独立的 JavaScript 文件中再在 webpack.config.js 里引入。这样框架升级后只需恢复那一行引入语句即可。另外模板还提供npm run updateVersion用于统一递增package.json与manifest.json中的版本号实现见 updateVersion 函数仅递增最后一段版本号。七、外部脚本文件content scripts 与 webview scripts 的编译默认情况下 webpack 只编译src/index.ts以及它 import 的文件其余文件会被原样复制到插件包中。但有两种情况必须额外编译对应 Joplin 的 content scripts 与 webview scripts 功能脚本本身是 TypeScript 文件必须先编译成 JavaScript脚本依赖了你加入package.json的第三方模块无论 JS 还是 TS都必须编译使依赖被捆绑进 JPL 文件否则运行时无法解析。具体做法是在plugin.config.json的extraScripts数组中声明脚本路径路径相对于src/目录。例如src/webviews/index.ts对应配置{ extraScripts: [webviews/index.ts] }编译后产物固定使用.js扩展名因此插件包内对应文件是webviews/index.js——在代码中引用外部脚本时要用这个编译后的路径。底层实现见 resolveExtraScriptPath它把src/name作为 webpack 入口输出到dist/下同名去扩展名的.js文件同时为 content scripts 预置了codemirror/*与lezer/*系列的 externals见 externalContentScriptLibraries使这些库既可以被require使用又不会重复打包进每个脚本。八、从模板到实战进一步探索理解生成器与模板后你可以沿着以下仓库路径继续深入阅读完整 API 类型声明了解插件可调用的全部能力api 类型声明目录查看仓库内真实插件 ToggleSidebars 的工程形态对照模板理解生产级插件的组织方式官方默认插件如 default-plugins 构建脚本同样基于这套脚手架体系维护可作为多插件工程与发布流水线的参考插件运行期的注册机制与内容脚本 API可结合 lib 包中的 plugin 相关类型 进一步研读。至此从npm install -g yo generator-joplin、yo joplin初始化到npm run dist构建、npm publish发布、npm run update升级框架、extraScripts编译外部脚本Joplin 插件从零到发布的完整生命周期已经全部打通。这套由生成器、Webpack 模板与发布脚本组成的工程链是 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考