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

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

【免费下载链接】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字段声明的pnpm@11.12.0为准，装错版本装依赖时会反复踩坑。

git clone https://gitcode.com/GitHub_Trending/si/siyuan cd app && pnpm install pnpm run dev

pnpm run dev只负责 webpack 开发态构建，窗口不会自己弹出来。再开一个终端，在app/目录执行pnpm run start拉起 Electron 主程序。跑通后第一个可验证的信号：设置页里的"插件"标签能打开，且渲染进程控制台没有以plugin开头的红色报错——此时把你自己写的插件文件夹丢进当前工作区plugins/目录，重启后应出现在插件列表里。工作区里plugins/等保留目录的约定，在 docs/WORKSPACE.zh-CN.md 中有完整定义，目录放错位置是新手最高频的失败原因。

排错速查：五种加载失败报错对照

加载器把常见坑都打成了带插件名的控制台日志，按关键词对号入座即可：

日志关键词	原因	处理
`run error`	入口 JS 在沙箱执行时抛异常	检查语法，确认依赖全部打进了 bundle 而不是运行时才`require`
`has 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.ts：Plugin基类本体。topBarIcons、statusBarIcons、commands、setting、protyleSlash、customBlockRenders这些注册点全在这里声明，读它才知道一个插件能往思源笔记里挂哪些东西；
app/src/plugin/loader.ts：加载器全流程——执行、导出校验、onload调用、CSS 注入。上面排错表里的每个日志关键词都产自这个文件，排障时它就是"答案之书"；
docs/API.zh-CN.md：HTTP 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与目标环境全部匹配后再提交集市。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析