尧图网站建设 
Joplin 插件脚手架详解generator-joplin 的项目结构、Webpack 构建、外部资源打包与 npm 发布流程【免费下载链接】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_DOC.md 为核心系统讲解generator-joplin如何从零生成一个 Joplin 插件项目从安装脚手架、理解src/index.ts与src/manifest.json的项目结构到 Webpack 三步构建产物JPL 压缩包与插件信息文件、npm publish后被插件仓库自动收录的条件再到plugin.config.json的extraScripts机制与外部资源如文本、CSS、content script的打包方式。读完本文你可以完整复现“生成插件项目 → 构建 JPL → 发布到 npm → 更新框架版本”的插件开发全流程并理解构建脚本中每一步的底层实现。一、generator-joplin用 Yeoman 生成一个插件项目Joplin 官方提供基于 Yeoman 的生成器generator-joplin用于自动搭好一个可直接构建、可发布的 Joplin 插件项目。生成器源码就存放在当前 monorepo 的 packages/generator-joplin 目录中与桌面端、CLI、移动端等包并列随仓库一起维护。安装与生成前提是本机已安装 Node.js。使用 npm 全局安装 Yeoman 和生成器npm install -g yo npm install -g generator-joplin然后执行生成命令yo joplin生成器会交互式地创建插件目录并按约定填充package.json的 name以joplin-plugin-开头与 keywords包含joplin-plugin这样后续发布条件天然满足。若插件日后需要跟进官方框架升级生成器同样提供了更新入口见下文“框架更新”一节。生成器自身处于开发阶段时可参照 Yeoman 官方的 “Running the generator” 章节进行本地调试仓库文档原文即引用了这一开发方式。二、项目结构两个核心文件加一个可选配置生成后的插件项目最值得关注的两个文件是src/index.ts插件源码的入口。Joplin 插件的宿主对象通过import joplin from api引入在joplin.plugins.register({...})中注册生命周期钩子如onStart和命令、菜单等。src/manifest.json插件清单文件声明插件的 id、名称、版本、最低应用版本、描述等元信息。以仓库中用于测试的外部资源示例插件为例其 src/index.ts 演示了插件启动时读取随插件打包的外部文件import joplin from api; joplin.plugins.register({ onStart: async function() { setTimeout(async () { const installDir await joplin.plugins.installationDir(); const fs joplin.require(fs-extra); const fileContent await fs.readFile(installDir /external.txt, utf8); console.info(Read external file content: fileContent); }, 5000); }, });对应的 src/manifest.json 展示了典型清单内容{ manifest_version: 1, id: org.joplinapp.plugins.ExternalAssetsTest, app_min_version: 1.7, version: 1.0.0, name: External Assets Test, description: Demonstrates how to access external assets that were packaged with the plugin, author: , homepage_url: , repository_url: , keywords: [] }其中id是插件在 Joplin 中的唯一标识发布产物文件名会以它命名app_min_version声明运行所需的最低 Joplin 版本。清单中还允许声明categories构建脚本会对其做校验不允许重复、必须是小写的合法分类名。可选的 plugin.config.json第三个文件是根目录下的plugin.config.json当你需要使用 content scripts、webview scripts 等“外部脚本文件”时会用到它详见第六节。示例插件的配置就是最简单的空数组形式plugin.config.json{ extraScripts: [] }三、构建插件npm run dist 背后的三步 Webpack 流程插件使用 Webpack 构建编译产物输出到dist/同时在publish/目录生成可直接分发的 JPL 压缩包和插件信息文件。执行npm run dist即可完成全部构建。示例插件的 package.json 揭示了dist脚本的真实构成——它实际上是按顺序执行的三段 Webpack 构建{ scripts: { dist: webpack --joplin-plugin-config buildMain webpack --joplin-plugin-config buildExtraScripts webpack --joplin-plugin-config createArchive, prepare: npm run dist, update: npm install -g generator-joplin yo joplin --update }, files: [publish] }这三段流程与 webpack.config.js 中的main()函数一一对应configs.buildMain、buildExtraScripts、createArchive见 webpack.config.js#L234-L273buildMain以./src/index.ts为入口用ts-loader编译主入口并通过copy-webpack-plugin把src/下除*.ts/*.tsx以外的所有文件CSS、文本、图片等原样复制到dist/。也就是说默认情况下src/index.ts及其 import 的模块会被编译其余文件只是被拷贝。这一步还会清理并重建dist/与publish/目录。buildExtraScripts按plugin.config.json的extraScripts列表逐个编译外部脚本无需编译时该配置为空数组Webpack 会直接退出exportedConfigs.length为 0 时process.exit(0)。createArchiveWebpack 本身并不需要真正的入口脚本借这次构建触发onBuildCompleted()回调完成 JPL 打包与信息文件生成。关于 TypeScript项目默认按 TypeScript 配置ts-loadertsconfig.json也可以改为纯 JavaScript 使用。JPL 压缩包与插件信息文件的生成细节onBuildCompleted()见 webpack.config.js#L116-L125依次做了三件事删除createArchive步骤在publish/中产生的临时index.js用tar把整个dist/打包为publish/manifest.id.jpl压缩包内为空时会直接报错 “Plugin archive was not created because the dist directory is empty”生成publish/manifest.id.json内容即manifest.json但额外写入两个字段——_publish_hashJPL 文件内容的 sha256形如sha256:…与_publish_commit当前 Git 仓库的分支:commit非 Git 仓库时置空。这两个字段用于插件仓库追踪插件的构建来源与完整性。打包完成后脚本还会执行validatePackageJson()做发布合规性预警见 webpack.config.js#L37-L50包名必须以joplin-plugin-开头、keywords 必须包含joplin-plugin、若存在postinstall脚本则建议使用prepare保证在发布前执行。这三条恰好对应插件仓库的收录条件。四、发布插件npm publish 与自动收录构建完成后把插件发布到 npmnpm publishJoplin 插件仓库有定期运行的收录脚本会自动抓取满足以下全部条件的 npm 包并加入插件仓库package.json中 name 以joplin-plugin-开头例如joplin-plugin-tocpackage.json的 keywords 中包含joplin-pluginpublish/目录中同时存在.jpl文件和.json文件两者都由npm run dist生成且package.json的files: [publish]保证它们会被一并发布到 npm。生成器在项目创建时已经自动设置好 name 和 keywords并安排正确的publish/目录内容因此通常无需手动处理。如果插件发布后没有出现在仓库中逐条核对上述条件即可。仓库测试 fixture 中的示例包名joplin-plugin-external-assets-test就是遵循该约定的真实案例。五、更新插件框架npm run updateJoplin 插件框架api/类型声明等会随版本演进生成器提供了升级命令npm run update对应示例package.json中的npm install -g generator-joplin yo joplin --update。该命令的设计原则是“尽量做对的事”对package.json和.gitignore执行合并而非覆盖保留你新增的依赖与脚本不触碰src/目录和README.md你的业务代码安全无虞webpack.config.js会被覆盖这是唯一可能出问题的文件。因此官方建议如需修改 Webpack 配置另建一个独立的 JS 文件并在webpack.config.js中require引入它升级时你只需恢复那一条引用语句即可保住自定义逻辑。仓库中webpack.config.js文件头的注释也把这一做法写成了醒目提示。六、外部脚本文件extraScripts 与资源打包机制默认构建规则下只有src/index.ts及其 import 的文件会被 Webpack 编译其他文件一律原样拷贝进插件包。多数情况下这已足够但存在两种必须编译外部脚本的情形脚本是TypeScript文件——必须先编译成 JavaScript 才能在运行时执行脚本依赖你在package.json中新增的第三方模块——无论 JS 还是 TS都必须经过编译把依赖一起 bundle 进 JPL否则运行时无法解析这些模块。配置方法extraScripts 数组要让某个外部脚本参与编译把它加入plugin.config.json的extraScripts数组路径相对于src/目录。例如文件位于src/webviews/index.ts则应写{ extraScripts: [webviews/index.ts] }编译后的产物固定以.js结尾插件包中会得到webviews/index.js你在代码中如joplin.views.panels.addScript引用的也必须是这个.js路径。源码层面的实现印证webpack.config.js中extraScripts从plugin.config.json读出并带默认空数组webpack.config.js#L26-L28resolveExtraScriptPath()webpack.config.js#L196-L216负责解析每一项若src/name不存在会直接抛出Could not find extra script错误输出文件名通过去掉原名扩展名再拼.js得到输出目标为dist/并以commonjs库格式导出。buildExtraScriptConfigs()再为每个脚本生成独立的 Webpack 配置。注释中特别说明这一步编译出的 JS 可能覆盖 buildMain 阶段拷贝的旧 JS 文件这是有意为之——不需要编译的 JS 停留在拷贝版本需要编译的则被正确编译的版本替换。非脚本类外部资源直接随包发布对于 CSS、图片、文本等非脚本资源无需任何配置buildMain 阶段的CopyPlugin会把src/下除 TS 外的全部文件复制进dist/最终进入 JPL。仓库中的external_assets测试插件正是这一机制的示范——src/external.txt内容为一行Some external file随包进入插件安装目录插件运行时通过joplin.plugins.installationDir()取得安装路径后再拼接external.txt用fs-extra读取见 src/index.ts。这类插件 fixture 位于 packages/app-cli/tests/support/plugins 下CLI 集成测试会在真实插件环境中安装并运行它们来验证打包行为。七、小结一条完整的插件交付链路把文档各节串起来一个 Joplin 插件的标准生命周期是npm install -g yo npm install -g generator-joplin再yo joplin生成项目或从仓库模板复制在src/index.ts中编写插件逻辑在src/manifest.json中声明 id、版本、最低应用版本需要 content script / webview script 或依赖第三方模块的脚本时登记到plugin.config.json的extraScripts其他资源文件直接放入src/即可随包分发npm run dist依次完成 buildMain编译入口 拷贝资源、buildExtraScripts编译外部脚本、createArchive打包 JPL 生成含 sha256 与 Git 信息的.json并输出发布合规性警告npm publish发布到 npm插件仓库脚本按包名前缀、keywords、publish/目录三个条件自动收录框架升级时执行npm run update注意webpack.config.js会被覆盖自定义配置应外置到独立文件。该生成器模板采用 MIT 许可© Laurent Cozic。以上内容均基于当前仓库中的生成器文档与测试插件 fixture 的实际文件核实可作为插件开发的第一手参考。【免费下载链接】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 的项目结构、Webpack 构建、外部资源打包与 npm 发布流程
Joplin 插件脚手架详解generator-joplin 的项目结构、Webpack 构建、外部资源打包与 npm 发布流程【免费下载链接】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_DOC.md 为核心系统讲解generator-joplin如何从零生成一个 Joplin 插件项目从安装脚手架、理解src/index.ts与src/manifest.json的项目结构到 Webpack 三步构建产物JPL 压缩包与插件信息文件、npm publish后被插件仓库自动收录的条件再到plugin.config.json的extraScripts机制与外部资源如文本、CSS、content script的打包方式。读完本文你可以完整复现“生成插件项目 → 构建 JPL → 发布到 npm → 更新框架版本”的插件开发全流程并理解构建脚本中每一步的底层实现。一、generator-joplin用 Yeoman 生成一个插件项目Joplin 官方提供基于 Yeoman 的生成器generator-joplin用于自动搭好一个可直接构建、可发布的 Joplin 插件项目。生成器源码就存放在当前 monorepo 的 packages/generator-joplin 目录中与桌面端、CLI、移动端等包并列随仓库一起维护。安装与生成前提是本机已安装 Node.js。使用 npm 全局安装 Yeoman 和生成器npm install -g yo npm install -g generator-joplin然后执行生成命令yo joplin生成器会交互式地创建插件目录并按约定填充package.json的 name以joplin-plugin-开头与 keywords包含joplin-plugin这样后续发布条件天然满足。若插件日后需要跟进官方框架升级生成器同样提供了更新入口见下文“框架更新”一节。生成器自身处于开发阶段时可参照 Yeoman 官方的 “Running the generator” 章节进行本地调试仓库文档原文即引用了这一开发方式。二、项目结构两个核心文件加一个可选配置生成后的插件项目最值得关注的两个文件是src/index.ts插件源码的入口。Joplin 插件的宿主对象通过import joplin from api引入在joplin.plugins.register({...})中注册生命周期钩子如onStart和命令、菜单等。src/manifest.json插件清单文件声明插件的 id、名称、版本、最低应用版本、描述等元信息。以仓库中用于测试的外部资源示例插件为例其 src/index.ts 演示了插件启动时读取随插件打包的外部文件import joplin from api; joplin.plugins.register({ onStart: async function() { setTimeout(async () { const installDir await joplin.plugins.installationDir(); const fs joplin.require(fs-extra); const fileContent await fs.readFile(installDir /external.txt, utf8); console.info(Read external file content: fileContent); }, 5000); }, });对应的 src/manifest.json 展示了典型清单内容{ manifest_version: 1, id: org.joplinapp.plugins.ExternalAssetsTest, app_min_version: 1.7, version: 1.0.0, name: External Assets Test, description: Demonstrates how to access external assets that were packaged with the plugin, author: , homepage_url: , repository_url: , keywords: [] }其中id是插件在 Joplin 中的唯一标识发布产物文件名会以它命名app_min_version声明运行所需的最低 Joplin 版本。清单中还允许声明categories构建脚本会对其做校验不允许重复、必须是小写的合法分类名。可选的 plugin.config.json第三个文件是根目录下的plugin.config.json当你需要使用 content scripts、webview scripts 等“外部脚本文件”时会用到它详见第六节。示例插件的配置就是最简单的空数组形式plugin.config.json{ extraScripts: [] }三、构建插件npm run dist 背后的三步 Webpack 流程插件使用 Webpack 构建编译产物输出到dist/同时在publish/目录生成可直接分发的 JPL 压缩包和插件信息文件。执行npm run dist即可完成全部构建。示例插件的 package.json 揭示了dist脚本的真实构成——它实际上是按顺序执行的三段 Webpack 构建{ scripts: { dist: webpack --joplin-plugin-config buildMain webpack --joplin-plugin-config buildExtraScripts webpack --joplin-plugin-config createArchive, prepare: npm run dist, update: npm install -g generator-joplin yo joplin --update }, files: [publish] }这三段流程与 webpack.config.js 中的main()函数一一对应configs.buildMain、buildExtraScripts、createArchive见 webpack.config.js#L234-L273buildMain以./src/index.ts为入口用ts-loader编译主入口并通过copy-webpack-plugin把src/下除*.ts/*.tsx以外的所有文件CSS、文本、图片等原样复制到dist/。也就是说默认情况下src/index.ts及其 import 的模块会被编译其余文件只是被拷贝。这一步还会清理并重建dist/与publish/目录。buildExtraScripts按plugin.config.json的extraScripts列表逐个编译外部脚本无需编译时该配置为空数组Webpack 会直接退出exportedConfigs.length为 0 时process.exit(0)。createArchiveWebpack 本身并不需要真正的入口脚本借这次构建触发onBuildCompleted()回调完成 JPL 打包与信息文件生成。关于 TypeScript项目默认按 TypeScript 配置ts-loadertsconfig.json也可以改为纯 JavaScript 使用。JPL 压缩包与插件信息文件的生成细节onBuildCompleted()见 webpack.config.js#L116-L125依次做了三件事删除createArchive步骤在publish/中产生的临时index.js用tar把整个dist/打包为publish/manifest.id.jpl压缩包内为空时会直接报错 “Plugin archive was not created because the dist directory is empty”生成publish/manifest.id.json内容即manifest.json但额外写入两个字段——_publish_hashJPL 文件内容的 sha256形如sha256:…与_publish_commit当前 Git 仓库的分支:commit非 Git 仓库时置空。这两个字段用于插件仓库追踪插件的构建来源与完整性。打包完成后脚本还会执行validatePackageJson()做发布合规性预警见 webpack.config.js#L37-L50包名必须以joplin-plugin-开头、keywords 必须包含joplin-plugin、若存在postinstall脚本则建议使用prepare保证在发布前执行。这三条恰好对应插件仓库的收录条件。四、发布插件npm publish 与自动收录构建完成后把插件发布到 npmnpm publishJoplin 插件仓库有定期运行的收录脚本会自动抓取满足以下全部条件的 npm 包并加入插件仓库package.json中 name 以joplin-plugin-开头例如joplin-plugin-tocpackage.json的 keywords 中包含joplin-pluginpublish/目录中同时存在.jpl文件和.json文件两者都由npm run dist生成且package.json的files: [publish]保证它们会被一并发布到 npm。生成器在项目创建时已经自动设置好 name 和 keywords并安排正确的publish/目录内容因此通常无需手动处理。如果插件发布后没有出现在仓库中逐条核对上述条件即可。仓库测试 fixture 中的示例包名joplin-plugin-external-assets-test就是遵循该约定的真实案例。五、更新插件框架npm run updateJoplin 插件框架api/类型声明等会随版本演进生成器提供了升级命令npm run update对应示例package.json中的npm install -g generator-joplin yo joplin --update。该命令的设计原则是“尽量做对的事”对package.json和.gitignore执行合并而非覆盖保留你新增的依赖与脚本不触碰src/目录和README.md你的业务代码安全无虞webpack.config.js会被覆盖这是唯一可能出问题的文件。因此官方建议如需修改 Webpack 配置另建一个独立的 JS 文件并在webpack.config.js中require引入它升级时你只需恢复那一条引用语句即可保住自定义逻辑。仓库中webpack.config.js文件头的注释也把这一做法写成了醒目提示。六、外部脚本文件extraScripts 与资源打包机制默认构建规则下只有src/index.ts及其 import 的文件会被 Webpack 编译其他文件一律原样拷贝进插件包。多数情况下这已足够但存在两种必须编译外部脚本的情形脚本是TypeScript文件——必须先编译成 JavaScript 才能在运行时执行脚本依赖你在package.json中新增的第三方模块——无论 JS 还是 TS都必须经过编译把依赖一起 bundle 进 JPL否则运行时无法解析这些模块。配置方法extraScripts 数组要让某个外部脚本参与编译把它加入plugin.config.json的extraScripts数组路径相对于src/目录。例如文件位于src/webviews/index.ts则应写{ extraScripts: [webviews/index.ts] }编译后的产物固定以.js结尾插件包中会得到webviews/index.js你在代码中如joplin.views.panels.addScript引用的也必须是这个.js路径。源码层面的实现印证webpack.config.js中extraScripts从plugin.config.json读出并带默认空数组webpack.config.js#L26-L28resolveExtraScriptPath()webpack.config.js#L196-L216负责解析每一项若src/name不存在会直接抛出Could not find extra script错误输出文件名通过去掉原名扩展名再拼.js得到输出目标为dist/并以commonjs库格式导出。buildExtraScriptConfigs()再为每个脚本生成独立的 Webpack 配置。注释中特别说明这一步编译出的 JS 可能覆盖 buildMain 阶段拷贝的旧 JS 文件这是有意为之——不需要编译的 JS 停留在拷贝版本需要编译的则被正确编译的版本替换。非脚本类外部资源直接随包发布对于 CSS、图片、文本等非脚本资源无需任何配置buildMain 阶段的CopyPlugin会把src/下除 TS 外的全部文件复制进dist/最终进入 JPL。仓库中的external_assets测试插件正是这一机制的示范——src/external.txt内容为一行Some external file随包进入插件安装目录插件运行时通过joplin.plugins.installationDir()取得安装路径后再拼接external.txt用fs-extra读取见 src/index.ts。这类插件 fixture 位于 packages/app-cli/tests/support/plugins 下CLI 集成测试会在真实插件环境中安装并运行它们来验证打包行为。七、小结一条完整的插件交付链路把文档各节串起来一个 Joplin 插件的标准生命周期是npm install -g yo npm install -g generator-joplin再yo joplin生成项目或从仓库模板复制在src/index.ts中编写插件逻辑在src/manifest.json中声明 id、版本、最低应用版本需要 content script / webview script 或依赖第三方模块的脚本时登记到plugin.config.json的extraScripts其他资源文件直接放入src/即可随包分发npm run dist依次完成 buildMain编译入口 拷贝资源、buildExtraScripts编译外部脚本、createArchive打包 JPL 生成含 sha256 与 Git 信息的.json并输出发布合规性警告npm publish发布到 npm插件仓库脚本按包名前缀、keywords、publish/目录三个条件自动收录框架升级时执行npm run update注意webpack.config.js会被覆盖自定义配置应外置到独立文件。该生成器模板采用 MIT 许可© Laurent Cozic。以上内容均基于当前仓库中的生成器文档与测试插件 fixture 的实际文件核实可作为插件开发的第一手参考。【免费下载链接】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），仅供参考