Obsidian Hexo Next 插件开发

发表于 分类于 评论： 字数： 3.3k

最近借助 AI 开发了一个用于在 Obsidian 阅读模式预览 Hexo Next 渲染效果的插件。同时也支持启动服务，提交部署，几乎满足了我的使用场景。

前情提要：我的博客使用 Hexo + Next 主题，Github 做仓库，Cloudflare Pages 部署，所以只需要提交文件到 Github 上就可以自动部署了。所以插件目前应该只适用于符合以上配置的博客。

前言

之前一直想用 Obsidian 来写 Hexo 博客，但奈何原生的 Obsidian 对 Hexo 的一些 Tag 标签不能做到所见即所得，不能快速预览效果，例如开头的 Center Quote。于是还是选择继续用 VS Code 来写文章，启动服务查看效果。

但最近心血来潮，不知为何，又想用 Obsidian 来写博客。一开始想着，如果在 Obsidian 也能使用终端，能够使用 Git-Bash 来启动服务，提交代码就好了。下载了一个终端插件，但实际使用下来好像没那么好用。

于是，误打误撞，莫名其妙地产生了写插件的想法。其实好久好久之前就想学习 Obsidian 插件开发了，但是之前的资料好少，教程也好难看懂，于是就一直耽搁着。到现在，AI 编程越来越方便了，这次跟着 AI 的教学做起来，其实很简单，因为代码都交给 AI 来完成了，我在其中的角色只能算是个产品和测试！

插件功能

先看看插件设置界面：

插件设置界面
插件设置界面

主要有以下功能：

  • 支持渲染 Hexo Next 的标签系统：目前仅设置了我常用的 Center Quote、Group Pictures 以及我自定义的标签 Fancybox。Next 的标签详情请看
  • 借助 Pangu 自动为英文数字和中文之间添加空格
  • 唤起 Git-Bash 或者终端启动和停止 Hexo 服务
  • 提交到 Github 进行部署
  • 给状态栏添加了一个快捷按钮
  • 右键菜单快捷添加 Tag 标签（使用到的图标库：Lucide 图标库）
  • 设置了一个可以弹出已配置命令的命令（选择并执行已配置命令）
状态栏的快捷按钮
状态栏的快捷按钮
右键菜单快速添加Tag标签
右键菜单快速添加 Tag 标签
可以设置一个快捷键来唤起这些命令
可以设置一个快捷键来唤起这些命令

关于 AI

先说 AI 的使用情况。使用到的 AI：ChatGPT、Gemini、Claude、VSCode 的 Copilot 插件。

具体使用下来觉得 Claude 是解决问题最利索的，大部分其他 AI 折腾很久都找不到解决方案的时候，Claude 一下就可以解决。其次是 Gemini，里面的 Canvas 很有用，在 Claude 没额度的时候靠的就是 Gemini。然后是 ChatGPT，我的想法是从与 ChatGPT 的对话里获得的，但它解决难题还是差了点意思。Copilot 排到最后，我用它主要是用来解释代码，分析报错和完成一些简单的任务。

我的需求

插件开发围绕了以下需求进行：

  • 让 Obsidian 里的阅读模式能够预览博客运行时的渲染结果
  • 能够在 Obsidian 里启动 Hexo 服务，提交 Github 部署
  • 快捷插入 Hexo Tag 标签

开发环境

  • 开发工具：VScode、Git-Bash
  • 运行环境：Node.js
  • 编程语言：TypeScript、Css

开发流程

因为我没有使用 Obsidian 官方提供的模板，所以可能流程会不一样，甚至比较简陋。

第一步：创建插件目录与文件

在配置好环境之后，在 Obsidian 的插件文件夹里创建插件文件夹，我的文件夹命名为 hexo-helper。之后在文件夹里分别创建最基本的 3 个文件：

  • manifest.json：存储插件基本信息的文件
  • main.ts：插件核心代码文件
  • styles.css：样式文件

但经过开发，我现在认为直接在插件文件夹创建插件项目不太好，因为到后面插件目录看起来好乱，不建议像我一样。为了文件夹美观，但更重要的是代码安全，甚至如果后续想发布插件，还是建议在 Obsidian 仓库之外的文件夹里进行开发，然后通过命令把编译好的文件放进 Obsidian。

例如，可以在磁盘的某个地方创建一个专门用于开发 Obsidian 插件的项目总目录，然后在里面存放各个插件项目进行开发。

乱七八糟的插件文件夹
乱七八糟的插件文件夹

插件身份证 manifest.json

manifest.json文件如下，Obsidian 并不是通过读取文件夹名来识别插件的，而是通过 manifest.json，可以说是插件的身份证：

manifest.json
{
  "id": "hexo-helper",
  "name": "Hexo Helper",
  "version": "1.0.0",
  "minAppVersion": "1.4.0",
  "description": "插件文字描述",
  "author": "插件作者",
  "main": "main.js"
}

一些参数说明：

  • id：插件的唯一标识符。必须是小写字母、数字或连字符（-）。一旦发布到社区，这个 ID 就不能改了。注意要和 Obsidian 插件文件夹的名称相同
  • main：告诉 Obsidian 编译后的 JavaScript 文件叫什么。通常默认是 main.js

核心逻辑 main.ts

在 main.ts 中，通常需要继承 Plugin 类。这是插件的生命周期起点。总之交给 AI 来完成就行了，我们只需要不停地给 AI 反馈运行情况与错误等直到插件能正常运行即可。

main.ts
import { Plugin } from 'obsidian';

export default class test extends Plugin {
    // 插件加载时触发
    async onload() {
        console.log('Hexo Helper 加载成功！');
    }

    // 插件卸载时触发（清理工作）
    onunload() {
        console.log('插件已卸载');
    }
}

第二步：运行插件

初始化插件

在项目文件夹里打开 Git-Bash，右键菜单里选择 “Git Bash Here”，这时候 Git-Bash 会自动定位到插件文件夹。

打开之后，在 Git-Bash 里执行以下两个命令：

初始化命令
npm init -y
npm install obsidian
  • npm init -y：执行之后，会发现文件夹里多了一个 package.json 文件。记录了项目的名字、版本和它需要哪些依赖。
  • npm install obsidian：执行后，会看到多了一个 node_modules 文件夹。这里面存放了所有开发需要的各种工具模块，供 TypeScript 调用。
创建的文件和文件夹
创建的文件和文件夹

以下是生成的package.json文件：

初始化生成的 package.json
{
  "name": "test",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "description": "",
  "dependencies": {
    "obsidian": "^1.12.3"
  }
}

编译（Build）

由于 Obsidian 基于 Chrome 引擎，不认 TS，读不懂里面的高级语法，只认 JS。所以需要通过编译将 TS 文件转换成 JS 文件，即main.ts → main.js。

Obsidian 插件开发最常用的编译方案是 esbuild，也是最简单、最快速的方案。通过以下命令安装 esbuild 依赖：

安装 esbuild 依赖
npm install esbuild

默认情况下，esbuild 的 watch 模式只盯着 Entry Point（即 main.ts）以及它通过 import 引入的文件。由于 manifest.json 和 styles.css 并没有被 import 到 TS 代码里，esbuild 感知不到它们的变动。

所以还需要另外添加一个专门的文件监听器，这里使用 chokidar，运行以下命令即可安装依赖：

安装 chokidar 依赖
npm install chokidar -D

创建用于构建的脚本build.js如下，直接复制，记得把 VAULT_PATH 里的路径改为电脑上真实的路径。如果是在 Windows 上，路径里的反斜杠要写成双斜杠 \\ 或者直接用正斜杠 /。出错就找 AI 就行了。

build.js 构建脚本
const esbuild = require("esbuild");
const fs = require("fs");
const path = require("path");
const chokidar = require("chokidar"); // 引入监听工具

const isWatch = process.argv.includes("--watch");
const VAULT_PATH = "D:/MyNotes/.obsidian/plugins/hexo-tag-preview"; // 记得改路径

// 统一的拷贝函数
function copyFile(fileName) {
  if (fs.existsSync(fileName)) {
    fs.copyFileSync(fileName, path.join(VAULT_PATH, fileName));
    console.log(`✨ 已同步: ${fileName} -> ${new Date().toLocaleTimeString()}`);
  }
}

async function build() {
  const ctx = await esbuild.context({
    entryPoints: ["main.ts"],
    bundle: true,
    outfile: path.join(VAULT_PATH, "main.js"),
    format: "cjs",
    target: "es2018",
    platform: 'node',
    external: ["obsidian", "child_process", "electron"],
    sourcemap: true,
    logLevel: "info",
  });

  if (isWatch) {
    console.log("🚀 监听模式已开启（支持 TS, CSS, JSON）...");
    
    // 1. 让 esbuild 盯着 TS 编译
    await ctx.watch();

    // 2. 让 chokidar 盯着静态文件
    // 监听当前目录下的 manifest.json 和 styles.css
    const watcher = chokidar.watch(["manifest.json", "styles.css"], {
      persistent: true,
    });

    // 当文件发生变化或新增时，执行拷贝
    watcher.on("change", (filePath) => copyFile(filePath));
    watcher.on("add", (filePath) => copyFile(filePath));

    // 初始运行先同步一遍
    copyFile("manifest.json");
    copyFile("styles.css");

  } else {
    await ctx.rebuild();
    copyFile("manifest.json");
    copyFile("styles.css");
    await ctx.dispose();
  }
}

build().catch((err) => {
  console.error(err);
  process.exit(1);
});

接下来修改 package.json，添加命令如下：

添加 build 和 dev 命令到 package.json
"scripts": {
  "build": "node build.js",  
  "dev": "node build.js --watch"
}

添加完命令后，就可以在命令行中任意执行以下两个命令来构建编译代码，我一直用的是 dev 命令，有自动不用手动：

命令行的构建命令
npm run build   //执行构建命令
npm run dev     //执行监听自动构建命令
启动构建和监听，一旦文件有改动就会编译，并把相关文件复制到Obsidian插件目录
启动构建和监听，一旦文件有改动就会编译，并把相关文件复制到 Obsidian 插件目录

这样，Obsidian 的插件目录里就只剩插件运行必备的文件了。

一下子就干净了许多
一下子就干净了许多

而我们真正进行开发的项目文件夹里是这样的：

在这里开发插件，启用监听后，会自动把必备文件输送到Obsidian插件目录
在这里开发插件，启用监听后，会自动把必备文件输送到 Obsidian 插件目录

启用插件

以上步骤做完，进入 Obsidian 设置中的第三方插件（记得关闭安全模式），刷新一下就可以在 Obsidian 中看到我们准备进行开发的插件啦！！！

用于测试的插件
用于测试的插件

第三步：借助 AI 开发插件

终于能进行真真正正的插件功能开发阶段了！现在，可以自己或者通过 AI，不断编写main.ts和styles.css来不断开发完善自己的插件了。

记得每次更改代码保存回到 Obsidian 后，按下快捷键Ctrl+R重新加载 Obsidian，让修改生效。不过似乎有一款插件可以实现热更新，：Hot-Reload Plugin for Obsidian.md Plugins。不过我还没使用，不知道效果怎么样。

这里想提个建议，开发的时候要善用 Debug 来测试功能是否正常运行，可以让 AI 帮忙添加 Debug 的代码。然后在 Obsidian 中，就可以按下快捷键Ctrl+Shift+I来开启开发者工具。在开发者工具中，可以看到 Obsidian 整个界面的 HTML 代码，进入控制台就可以看到 Debug 的输出，如果看不懂，可以右键把控制台日志另存下来发给 AI 自行分析（反正我是这样哈哈哈）。

对我来说，在这次插件开发过程中，我并没有写过什么代码，即使有也是从 AI 写完的代码中，复制粘贴下来修改，添加通用的功能。我只是不断测试 AI 给我提供的代码是否能正常运行，是否能够按照我的想法实现我想要的功能，然后再给 AI 反馈，如此往复，经过日日夜夜的开发，才得到我想要的插件！

至于和 AI 的合作，我想我没有什么可以分享的，因为我没有用到任何 Prompt 模板，只是用自然语言和 AI 进行交流，哪个 AI 的回答我觉得不好我就换另一个，或者开新的对话。基本上我会和 AI 对话到窗口卡顿，然后不得已开新对话。

总之，就是先跟 AI 提需求，然后让 AI 提供完整的代码，复制粘贴，看有没有报错。有就反馈给 AI，同样的，解决不了就换一个。如果没问题就保存编译去到 Obsidian 测试结果，成功就下一步，结果有问题就反馈给 AI 进行修改。

我推荐使用 Claude 和 Gemini 的 Canvas，这两个都可以直接提供完整的代码文件，直接复制粘贴到 TS 文件里就可以了。也可以将代码文件或者 log 文件拖到对话框让它们分析错误这些，然后提供完整的修改后的代码。不过现在已经有许多 AI 自动化工具了，我使用的这些反而有些落后了哈哈哈，后续我也会学习看看！

最后希望大家与 AI 合作愉快！

写在最后

这是我第一次开发 Obsidian 插件，通过 AI 的帮助，我顺利完成了！写下这篇文章，一方面是想通过这次的开发，总结 Obsidian 插件的开发流程，为自己下次的插件开发之旅做准备，这样在开发的初始阶段就不用处处询问 AI 了。另一方面呢，嘿！我好像完成了一件非常了不起的事耶，当然要记录一下啦！当然啦，也想通过分享这篇文章，给大家提供一些经验！希望大家在开发 Obsidian 插件时，能够顺顺利利，开开心心！

最后，给大家看看我现在的 Obsidian 的 Hexo 博客写作环境：

我的Obsidian
我的 Obsidian