扫盲贴｜如何创建自己的思源笔记插件

If you are looking for English guidance, please use the browser translation plugin.

前言

本篇文章用于指导开发如何通过插件模板，快速创建自己的思源笔记插件，但不会详细指导思源笔记插件开发中的细节。

更多有关于思源笔记开发的经验，可自行学习或关注后续内容。

0、准备工作

在开始以前，你可能还需要提前在你的电脑上准备以下内容：

1. Node.js - 最好是 20+ 版本，不过现在安装一般是 v22+ 版本了
2. PNPM - 除了用于插件开发，也可以用于开发思源本体代码
3. Git - 插件上架到集市等场景下，必须要用到
4. Cursor 或 VS Code 或 WebStorm 等任意一个用于编写代码的工具 - 用于编写代码

你可能需要提前了解以下内容：

1. 豆包回答 · 如何在 windows 或 macOS 上运行命令
2. GitHub 文档 · 克隆仓库
3. CSDN · 如何在 GitHub 上克隆项目(超详细的图文并解)
4. 豆包回答 · 如何用 Cursor 打开一个 GitHub 项目

1、挑选插件模板

思源官方和社区提供了一些快速创建插件的模板项目（详见：SiYuan community bazaar - Dev bazaar package and listing）：

• SiYuan plugin sample - 官方模板
• SiYuan plugin sample (Vite & Svelte) - 基于 Vite 和 Svelte 的模板，由 @Frostime 主要维护
• SiYuan plugin sample (Vite & Vue3) - 基于 Vite 和 Vue3 的模板，由本文作者主要维护

你可以在其中挑选一个，用于创建你自己的插件。

由于本篇是扫盲贴，面向的是没经验的小白，因此推荐首选 plugin-sample-vite-vue​ 这个模板，次选 plugin-sample-vite-svelte 这个模板。

推荐理由：

Vue 模板，用的是相对主流，并且约等于你只需要学习 HTML、CSS、JS 就能开发思源笔记插件的技术。

Svelte 模板，则是一个与 Vue 模板类似，但是相比前面 Vue 模板，稍微多了一点差异。基于本文作者前端开发从业者的经验，截止目前（2025.10） Svelte 并非各大公司主流开发技术。

因此作者更推荐 Vue 模板，当你通过思源笔记熟悉了“前端开发”以后，你可以进一步扩展到其他领域，减少学习成本。

不过目前思源集市里，通过 Svelte 创建的插件数量更多一点，在学习相关开发细节时，可以有更多的参考，你可以自行按需选择两个模板。

PS：如果你是有经验、更喜欢 React 的前端开发，也可以基于上述三个模板，自行维护 React 版本。

2、具体步骤

本小节主要是给不懂使用 GitHub 等技术的小白，进一步解释 siyuan-note/plugin-sample-vite-vue - README_zh_CN#开始 中的操作。

2.1、创建项目

只是你自己使用的插件，完全不需要上架集市就能正常开发和使用。

如果你不准备上架思源集市，可以不需要通过 Git、GitHub 等内容创建项目，通过图片中的步骤，下载示例项目的代码到你电脑上即可。

⚠️ 当你下载好项目以后，不要进行任何修改！先按照后续流程，保证能在思源中看到示例插件以后，再进行调整。

2.2、运行示例项目

1️⃣ 通过命令行，在你的项目根目录下运行 pnpm install，安装所需要的“依赖”。

如何确认根目录：

macOS 或 linux 运行 ls​ 命令，windows 运行 dir​ 命令，能看到 src 这个文件夹，就是在根目录。

2️⃣ 复制 .env.example​ 文件并取名为 .env​，修改其中的 VITE_SIYUAN_WORKSPACE_PATH 为你的思源工作空间。

这一步主要是设置生成的代码放到哪里，项目里的脚本，会自动将生成的代码放到 VITE_SIYUAN_WORKSPACE_PATH/data/plugins 目录下。

💬 这里我建议直接生成到思源的工作空间里，利用思源自带的同步机制，可以直接同步你的插件到其他设备上，也就是前面说不用上架集市的原因。

3️⃣ 使用 pnpm dev 启动项目，看到类似下面的内容，则表示构建成功：

> plugin-sample-vite-vue@0.0.1 dev /path/to/your/plugin-sample-vite-vue
> vite build --watch

mode=> production
env=> {
  VITE_SIYUAN_WORKSPACE_PATH: '/path/to/siyuan/workspace',
}

Siyuan workspace path is set:
/path/to/siyuan/workspace

Plugin will build to:
# ✅ 插件将会构建至下面的位置
/path/to/siyuan/workspace/data/plugins/plugin-sample-vite-vue

isWatch=> true
distDir=> /path/to/siyuan/workspace/data/plugins/plugin-sample-vite-vue
vite v6.3.5 building for production...

watching for file changes...

build started...
✓ 26 modules transformed.
rendering chunks (1)...LiveReload enabled
../../Siyuan-plugin/data/plugins/plugin-sample-vite-vue/index.css    1.08 kB │ gzip:  0.41 kB
../../Siyuan-plugin/data/plugins/plugin-sample-vite-vue/index.js   198.60 kB │ gzip: 46.59 kB
[vite-plugin-static-copy] Copied 7 items.
built in 502ms.

4、打开 思源 - 设置 - 集市​ 中，即可看到名为 plugin-sample-vite-vue 的插件。

📌 如果启动项目时，已经打开了思源的设置，重新开关一下思源的设置页面

至此，该示例项目就启动成功了。

3、后续行动

当你通过上面的步骤，在思源中成功运行了示例项目以后，你就可以进一步完成自己想要的功能了。例如：

1️⃣ 通过 Cursor/VS Code 的全局搜索，替换你的插件名称。

2️⃣ 查看 src/App.vue 文件，借助 Cursor 等 AI 工具，了解和学习基本的代码。

你也可以进一步学习 HTML、CSS、JavaScript、Vue 等技术。

4、补充说明

1️⃣ 为了方便展示功能，本示例插件默认会创建下图中的弹窗。了解完功能以后，你可以随意删除。

2️⃣ 插件提供了 usePlugin​ 方法，你可以在代码中的任意位置，通过使用 const plugin = usePlugin()​ 获取思源插件的对象，然后调用思源提供的方法。例如 addTopBar​、addCommand 等方法。

简单来说，思源官方示例 siyuan/plugin-sample/src/index.ts 中，所有使用 this.xxx 的地方，你都可以替换成上面两步。

并且提供了下面这些属性，用于判断思源当前的运行环境。例如通过 if (plugin.isElectron) 即可判断插件目前运行在思源的桌面端（电脑软件）中。

// Run as mobile
public isMobile: boolean
// Run in browser
public isBrowser: boolean
// Run as local
public isLocal: boolean
// Run in Electron
public isElectron: boolean
// Run in window
public isInWindow: boolean
public platform: SyFrontendTypes
public readonly version = version

3️⃣ 本示例项目已经做好了 TS 和 Eslint 等相关规则，用于更好的编写代码。

你可以进一步了解这两个技术的使用。如果不想了解，也不会影响你的正常开发。

4️⃣ 本示例项目，已经处理了 Vue 项目的初始化和卸载逻辑。

简单来说，你只需要在 App.vue 文件里，按照正常编写 Vue 代码的逻辑，即可完成所有功能的开发。

你可以通过下面的示例代码，在思源界面中插入你的 Vue 组件内容的同时，拥有 Vue 响应式编写体验。

下面代码的作用，找到思源界面中的状态栏（右边的代码），然后向其中插入一个自定义的图标（左边的代码）

否则，你需要按示例项目中的下面代码，才能创建一个图标到思源的状态栏中。

每次更新页面上的内容，你还需要通过 JS 重新操作 DOM 元素。做不到“数据更新了，页面就更新了”。

其中的细节，只有你自己尝试过才能体会。

5️⃣ 在叶归插件中，已经封装或正在封装一些通用组件，未来可能会考虑全都加入到模板项目中。

例如，叶归插件代码中，封装了 EnProtyle​ 这个组件，你只需要更新组件的 blockId 即可渲染对应的块内容。

封装组件前，如果你需要重新渲染一个可以编辑的思源块，你需要用类似下面的代码：

const newBlockId = someFuncToGetNewId();
const targetDiv = body.getElementById('quick-note-protyle-area')
if (targetDiv) {
  targetDiv.innerHtml = ''
  new Protyle(
    plugin.app,
    targetDiv,
    {
      blockId: newBlockId,
      action: ['cb-get-focus'],
      render: {
        breadcrumb: false,
      },
    },
  )
}

封装组件后：

currentBlockId.value = someFuncToGetNewId();

结语

理论上，按照上面的流程正常就能启动一个思源示例插件，也补充了部分细节。

毕竟这不是一篇手把手从零教开发思源插件的内容，只能说是在“有经验的开发者使用示例项目”的层次上，更贴近了一点小白用户。

如果使用过程中有什么疑问，或遇到了什么问题，可以反馈，未来再继续补充了。