思源笔记插件开发入门：一文走通环境搭建、本地联调与上架发布

思源笔记插件开发入门一文走通环境搭建、本地联调与上架发布【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan思源笔记SiYuan是一款开源、隐私优先、自托管的知识工作空间人与 AI 智能体在同一份数据上协作。它面向第三方的扩展机制官方就叫「插件」内核代号 petal。本文按最小形态、本地跑通、能力菜单、故障速查、走向社区五节展开——照着做完你能独立搭好开发环境跑通并上架自己的第一个插件。 最小插件长什么样清单加入口两件套一个能被加载的插件最少就是当前工作区plugins/目录目录结构见 docs/WORKSPACE.zh-CN.md下的一个文件夹里面放两个文件plugin.json声明它是谁入口 JS 声明它做什么。{ name: hello, version: 0.0.1, displayName: Hello }class Hello extends Plugin { async onload() { this.addCommand({langKey: hi, name: Hi, hotkey: , callback: () this.app.toast(hi)}); } } module.exports Hello;规则只有三条入口必须能被取到默认导出module.exports 你的类即可这个类必须继承前端基类 Plugin加载器实例化后会调用onload()。至于入口 JS 具体怎么被执行、CSS 怎么注入都写在 加载器 里初学阶段知道有人替你跑就够了。 三条命令搭好本地开发环境这一节把仓库完整跑起来你的插件会随启动一起被扫描加载。命令共三条git clone https://gitcode.com/GitHub_Trending/si/siyuan cd siyuan/app pnpm install pnpm run dev pnpm run startNode 建议 18 以上pnpm 版本以 package.json 的packageManager字段为准用corepack enable可以一键对齐。pnpm run dev起 webpack 开发构建pnpm run start拉起 Electron 桌面窗口。怎样算加载成功看两处其一设置面板里的插件管理列表出现 Hello开关可以打开其二命令面板里能找到你注册的 Hi 命令。再按 F12 打开 DevTools确认 Console 没有run error之类的红字即通过。加载成功了接下来能挂哪些东西 插件能注册哪些东西三组入口速查这一节把宿主开放给插件的入口按界面挂载、数据读写、事件联动分好组你只需按需求挑每条形码链接可直接点开。界面挂载——插件长什么样、出现在哪topBarIcons往顶栏放图标声明在 index.tscommands命令面板条目可绑全局快捷键addCommand()负责注册docks在左右下停靠区开一个自定义面板页签挂载逻辑在 loader.tscustomBlockRenders自定义块的渲染器见 customBlockRender.ts数据读写——插件能拿什么数据siyuanAPI 对象创建文档、插入块、执行 SQL 的现成封装在 API.ts接口全集见 API.zh-CN.mdkernel插件自有配置的存取跨重启保留实现见 kernel.ts这些封装背后都是对内核 HTTP 端点的调用例如await siyuan.createDocumentByMarkdown(/, 测试, # Hello);事件联动——什么时候该反应eventBus.on()监听全局或跨插件事件见 EventBus.tsonload/onunload/onLayoutReady加载、禁用、布局就绪三个生命周期钩子定义在 index.ts 四条加载报错对出哪条修哪条加载器把最常见的坑都打成了固定文案的控制台日志出处 loader.ts这四条基本覆盖了我见过的大多数加载失败。症状根因修复Console 出现run error入口 JS 执行时抛异常多为语法错或依赖没打进 bundle单独在控制台执行入口代码按报错行修has no export入口没有导出任何内容文件末尾补module.exports 你的类does not extends Plugin导出类没继承基类改成class X extends Plugin再导出onload error初始化逻辑内部异常常因调用了不存在的 API按堆栈行号定位逐个注释onload里的调用做二分插件显示不可用plugin.json的minAppVersion高于当前版本把minAppVersion调到不高于你实际支持的版本日志去哪里看桌面端按 F12 打开 DevTools看渲染进程的 Console 面板。插件相关的红字都从这里出不用去翻主进程日志。 打包自检与集市上架要点这一节能让你对照源码完成一次打包自检。本地跑通了凭什么敢上架答案是集市解析规则完全公开字段逐项可查。集市的安装、更新、卸载逻辑都在kernel/bazaar/目录包结构定义在 package.go。打包产物自检字段name与入口一致version用三段式语义化版本minAppVersion写清兼容下限高于它的应用会直接标记不可用displayName、description支持多语言映射disabledInPublish决定是否在发布站模式禁用提交集市前确认四件事plugin.json能被解析正常字段名别拼错安装流程install.go对包结构的假设没被破坏readme 与图标齐备在app/目录跑一遍pnpm run lint保持代码风格与仓库一致。✅ 上架前逐项打勾你能从零写出一份两文件插件并说清plugin.json与入口各管什么。你能在本地把思源跑起来并从插件列表确认它已挂载。你能说出界面挂载、数据读写、事件联动三组入口分别对应哪些字段。你能凭四条控制台文案定位加载失败的具体环节。你能对照包结构字段完成一次上架前自检。【免费下载链接】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），仅供参考