思源笔记插件开发上手：30分钟从三个文件走到插件跑起来

思源笔记插件开发上手30分钟从三个文件走到插件跑起来【免费下载链接】siyuanAn open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间让人与智能体在此协作项目地址: https://gitcode.com/GitHub_Trending/si/siyuan有天我想在笔记里加一个字数统计按钮发现现成插件没有这个功能就自己动手写了。这篇思源笔记插件开发教程按新手视角写读完你能搭好思源笔记开发环境在自己的思源笔记里跑起一个最小插件并搞清楚插件发布的路径。 动手前的准备三步搭好思源笔记开发环境写插件不要求你写 Go需要的是Git克隆思源源码git clone https://gitcode.com/GitHub_Trending/si/siyuan也用它管理你自己的插件仓库Node.js pnpm前端TypeScript构建依赖 pnpm仓库锁定pnpm11.12.0执行corepack enable后跑pnpm install即可Go 1.26只有想改内核时才用得上纯前端插件不装也能开发。另外装一个最新版思源笔记它是你测试插件的地方。五分钟跑通插件模板首个思源笔记插件教程的三步在思源数据目录的workspace/plugins下新建一个文件夹放三个文件plugin.json声明插件 ID、名称、版本和minAppVersion兼容版本index.js是前端逻辑入口style.css可以为空。重启思源笔记打开设置 → 定制 → 插件新插件会出现在列表里点启用。在index.js里加一个按钮、点击后在光标处插入一段文本再禁用、启用一次验证生效。之后每次改完代码都靠禁用 启用看效果。看懂插件的运行机制前后端分工一句话讲清思源架构分得很清楚前端TypeScript在app/下管店面——按钮、弹窗、菜单后端Go在kernel/下管仓库——块、数据库、搜索、同步。插件大多是挂在店面上的货架主要调前端接口要深度操作数据时通过 HTTP 请求打到内核。思源的插件系统叫Petal花瓣Petal 插件系统源码 实现了内核侧加载插件列表、逐个启停的逻辑每个插件就是一朵挂到主程序上的花瓣。读 思源 API 文档 的方法文档按笔记本、文档、块、属性、数据库、搜索分节每个端点都写清参数和返回值。开发时先确定这个功能归哪一节查到对应条目再去前端 API 声明里找同名方法。比如插件要搜索块效果就是下面这样让开发效率翻倍的 4 个做法写码前先把思源笔记插件 API 查一遍动手前先翻 API 文档确认请求和返回结构再查一遍前端声明里同名方法的参数。大多数Bug其实是字段名抄错了提前确认能省掉整个调试环节。把日志打到思源日志文件别靠弹窗调试前端插件报的错会落到内核data/log目录的日志里外部调用出问题也查这个文件。用alert调试主应用只会干扰自己。如实声明 minAppVersion在plugin.json里写清插件依赖的最低思源版本。内核加载时会检查这个字段不兼容的插件直接不启动避免升级后的用户批量报错。插件文件夹单独建仓把插件目录当独立项目用自己的 git 管理版本和提交历史。后续做思源笔记插件发布时直接打包这个文件夹不用从杂乱的工程里往外抠。新手最常踩的 3 个坑现象插件启用了但没有任何效果。原因文件夹名与plugin.json的 ID 不一致或入口文件名没叫index.js。解决核对文件夹名、ID、入口文件名三处一致再看日志确认内核是否加载成功。现象脚本里直接调内核接口总是报错。原因思源的 API 需要鉴权前端插件自带会话外部调用必须携带令牌。解决从设置 → 系统里拿令牌按文档要求放入请求。现象用户升级思源后插件崩了。原因没设minAppVersion或用了旧接口。解决发布前在最新版本地完整跑一遍主流程。文档与社区资源导航思源 API 文档全部内核接口的请求与返回值说明写插件时第一查询地Bazaar 集市源码插件发布的包结构、下载与安装流程都在这里准备发布前先读它思源官方论坛与社区和其他插件作者交流、遇到拿不准的问题去提问的地方。整条路径其实就四步备好环境、写三个模板文件、查 API 文档、在自己的思源里启用验证。第一个插件建议做得越小越好比如给编辑器加一个显示当前文档字数的按钮——跑通它后面的功能都是在这上面叠加而已。【免费下载链接】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），仅供参考