思源笔记插件开发完整路线：从本地跑通到集市发布

思源笔记插件开发完整路线从本地跑通到集市发布【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan思源笔记是一款开源、隐私优先、自托管的知识工作空间人与 AI 智能体在其中协作。它的扩展入口就是插件系统内部代号 petal一个插件只是工作区plugins/目录下的一个文件夹。本文带你走通跑起来、改得动、发出去三关完成后你会得到一个能本地联调、能改代码、能提交集市发布的可用插件。第一关 · 跑起来最小运行命令与启动验证前置条件只有一个Node 加 pnpm。pnpm 版本别凭感觉选以 app/package.json 中packageManager字段声明的pnpm11.12.0为准装错版本装依赖时会反复踩坑。git clone https://gitcode.com/GitHub_Trending/si/siyuan cd app pnpm install pnpm run devpnpm run dev只负责 webpack 开发态构建窗口不会自己弹出来。再开一个终端在app/目录执行pnpm run start拉起 Electron 主程序。跑通后第一个可验证的信号设置页里的插件标签能打开且渲染进程控制台没有以plugin开头的红色报错——此时把你自己写的插件文件夹丢进当前工作区plugins/目录重启后应出现在插件列表里。工作区里plugins/等保留目录的约定在 docs/WORKSPACE.zh-CN.md 中有完整定义目录放错位置是新手最高频的失败原因。排错速查五种加载失败报错对照加载器把常见坑都打成了带插件名的控制台日志按关键词对号入座即可日志关键词原因处理run error入口 JS 在沙箱执行时抛异常检查语法确认依赖全部打进了 bundle 而不是运行时才requirehas no export模块没有导出任何内容用default导出插件类而不是导出零散函数does not extends Plugin导出类未继承基类类先extends Plugin再导出onload error入口能加载但onload()内部抛错看堆栈定位初始化逻辑里的具体行onLayoutReady error布局就绪回调里出错检查图标挂载、DOM 操作等与布局相关的代码看日志时优先打开渲染进程窗口Electron 里 F12的控制台上面这些报错全部出自前端加载器主进程日志只有进程级信息排查插件问题基本用不上。第二关 · 改得动先读清主链路再动代码主链路五个节点一句话走完插件文件夹放进工作区plugins/目录这是唯一的安装位置内核按目录逐个读取plugin.json解析版本与兼容性kernel/bazaar/plugin.go 的ParseInstalledPlugin前端向/api/petal/loadPetals发起请求拿到插件清单加载器用window.eval包成require/module/exports沙箱执行入口 JS导出类通过校验后实例化依次调用onload()和kernel.init()afterLoadPlugin把顶栏图标、状态栏图标、dock 面板挂到界面对应位置。改代码前把这三个入口各读一遍app/src/plugin/index.tsPlugin基类本体。topBarIcons、statusBarIcons、commands、setting、protyleSlash、customBlockRenders这些注册点全在这里声明读它才知道一个插件能往思源笔记里挂哪些东西app/src/plugin/loader.ts加载器全流程——执行、导出校验、onload调用、CSS 注入。上面排错表里的每个日志关键词都产自这个文件排障时它就是答案之书docs/API.zh-CN.mdHTTP API 手册。/api/filetree/createDocWithMd建文档、/api/block/insertBlock插块这类能力插件内通过siyuan命名空间或直接发请求都能调。第三关 · 发出去包结构自查与两个进阶方向集市的安装、更新、卸载逻辑集中在kernel/bazaar/目录字段标准以 kernel/bazaar/package.go 中Package结构体为准。提交集市前逐项核对解析规则version、displayName、description必填后两者是按语种索引的表key 为default、zh_CN这类语种码不是单一字符串minAppVersion高于当前应用版本时直接拒装这是已安装却显示不可用的头号原因backends、frontends缺失时按全平台支持处理而kernels为空则表示内核侧插件不会启动disabledInPublish为 true 时发布站模式下插件被禁用。两个值得深入的进阶方向HTTP API 深对接API 手册里的接口同样面向外部程序剪藏类扩展就是纯 HTTP 调内核你的插件可以直接复用这条通道做批量文档操作自定义块与斜杠命令基类预留了customBlockRenders和protyleSlash两个钩子做自定义块渲染或编辑器斜杠菜单时直接注册到这两个数组上无需碰内核。收尾 · 行动清单在插件onload()里调用createDocWithMd接口创建一篇文档以新文档出现在工作区为验证点确认 HTTP 通道打通写最小plugin.json只留name、version、displayName放进工作区plugins/目录后重启验证插件列表出现且控制台无run error加一个顶栏图标和一条命令分别覆盖topBarIcons与commands两个注册点验证图标显示在顶栏、命令可从命令面板触发在app/目录执行pnpm run lint验证输出无风格违规保证代码与仓库规范一致对照kernel/bazaar/package.go的Package结构体逐字段自查打包产物确认minAppVersion、frontends、kernels与目标环境全部匹配后再提交集市。【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考