企业官网建设流程全解析

思源笔记插件开发从零到上线：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基类的哪个钩子就一目了然：

这些属性都是基类里预声明好的容器，onload()里往里塞条目即可，前端会自动把它们挂到对应界面位置。基类定义在 app/src/plugin/index.ts，读一遍它比查散落的文档更快建立整体感。

🚀 十分钟搭建本地开发环境

需要 Node + pnpm 工具链，版本以 app/package.json 中packageManager字段为准（pnpm@11.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填写完整，集市要求的字段没有缺失。

接下来可以做的四件事

1. 打开 docs/API.zh-CN.md，挑"通过 Markdown 创建文档"这一个接口，在onload()里调通，验证内核 API 链路；
2. 给topBarIcons加一个图标、给commands加一条命令，一次覆盖两个注册点；
3. 在app/目录执行pnpm run lint，保持代码风格与仓库一致；
4. 想加斜杠命令时，往protyleSlash推一条配置，在编辑器里输入/查看效果。

【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间，让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan