思源笔记插件开发从零到上线20 分钟跑通本地环境并让第一个插件加载成功【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan思源笔记是一款开源、隐私优先、自托管的知识工作空间其插件系统允许任何人给它扩展命令、图标与自定义块。这篇思源笔记插件开发与入门教程带你走通按目标选钩子、搭建本地环境、写出最小可加载插件、排查插件加载报错最后把插件发布到集市。 先定目标想做什么就挂哪个注册点写代码前先想清楚要给思源加什么能力对应到Plugin基类的哪个钩子就一目了然想实现的效果注册点基类属性最终出现位置提供快捷键操作commands命令面板顶栏加一个图标按钮topBarIcons编辑器顶栏独立配置页setting设置面板自定义内容块customBlockRenders与protyleSlash正文渲染与斜杠菜单这些属性都是基类里预声明好的容器onload()里往里塞条目即可前端会自动把它们挂到对应界面位置。基类定义在 app/src/plugin/index.ts读一遍它比查散落的文档更快建立整体感。 十分钟搭建本地开发环境需要 Node pnpm 工具链版本以 app/package.json 中packageManager字段为准pnpm11.12.0。三条命令搞定git clone https://gitcode.com/GitHub_Trending/si/siyuan cd siyuan/app pnpm install pnpm run dev pnpm run start第一条启动 webpack 开发模式第二条拉起 Electron 窗口。第一次跑通后先别急着写代码去界面上找两个入口设置面板里的插件列表以及命令面板——后面验证自己的插件就靠这两处。 写出能加载的最小插件一个插件就是工作区plugins/目录下的一个文件夹目录职责在 docs/WORKSPACE.zh-CN.md 有说明plugin.json是身份声明index.js是入口脚本index.css可选放样式。最小plugin.json只留三个字段{ name: hello-siyuan, version: 1.0.0, displayName: Hello SiYuan }入口脚本的三个要点类要继承Plugin、类必须default导出、初始化逻辑全部放进onload()。加载机制其实就是一条能一口气读完的链路文件夹 → 内核解析 plugin.json、读取 JS/CSS → 前端沙箱执行入口并实例化 → 调用onload()并把图标、命令、设置页挂上界面。前端加载器在 app/src/plugin/loader.ts它同时负责 CSS 注入与出错日志内核侧的启停接口在 kernel/api/petal.go进阶时再看。 插件加载报错怎么查加载器把每类失败都打成了明确的控制台日志。记住一个原则先看浏览器控制台而不是主进程日志基本能直接定位插件出现在列表却显示不可用这是最隐蔽的静默失败。多半是plugin.json里的minAppVersion高于当前版本或disabledInPublish在发布站模式把它禁用了。修法核对版本号把兼容性要求降到真实依赖的最低版本。日志出现has no export入口没有可用导出。确认export default导出的是插件类本身。日志出现does not extends Plugin导出的类没继承基类。给类声明补上extends Plugin。日志出现run error或onload error前者是入口 JS 执行阶段就抛异常多为语法错误或依赖没打进 bundle后者说明onload()内部报错。排查 onload 时在第一行打一条日志先确认执行进了函数再二分定位。把插件发布到社区集市两个自查字段功能验证通过后下一步是分发。集市的安装、更新、卸载逻辑集中在 kernel/bazaar/ 目录发布前建议通读一遍install.go和package.go确认包结构与字段解析规则。发布前重点自查两处version已递增且minAppVersion与插件实际依赖的最低版本一致displayName、description填写完整集市要求的字段没有缺失。接下来可以做的四件事打开 docs/API.zh-CN.md挑通过 Markdown 创建文档这一个接口在onload()里调通验证内核 API 链路给topBarIcons加一个图标、给commands加一条命令一次覆盖两个注册点在app/目录执行pnpm run lint保持代码风格与仓库一致想加斜杠命令时往protyleSlash推一条配置在编辑器里输入/查看效果。【免费下载链接】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），仅供参考