Hexo 插件开发基础教程

Hexo 教程 插件开发
Hexo
文章字数:   2k
阅读时长:   7 分

哈喽，大家好！今天我们来聊一聊如何为 Hexo 开发自己的插件。如果你正在使用 Hexo 并且觉得有些功能无法满足你，那么开发一个自定义插件就是最好的解决办法。这篇文章会从零开始，带你一步步创建、开发并发布一个属于你自己的 NPM 插件。

两种插件的引入方式

在 Hexo 中，有两种主要的方式来嵌入自定义功能：

  1. **脚本 (Scripts)**：这种方式比较简单，适合一些轻量级的功能。你只需要在 Hexo 项目的 scripts 目录下创建 JavaScript 文件，Hexo 启动时就会自动加载它们。
  2. **NPM 包 (Packages)**：这是更标准、更强大的方式。你可以将你的插件发布到 NPM 上，这样不仅你自己可以方便地在不同项目中使用，也可以分享给社区里的其他开发者。

我们今天的重点就是第二种方式：如何开发并发布一个 NPM 插件。

Hexo 插件的类型

在动手之前，我们先了解一下 Hexo 插件可以做什么。Hexo 的插件生态非常丰富，官方定义了多种插件类型，比如：

  • **Console (控制台)**：添加新的 hexo 命令，例如 hexo clean。
  • **Deployer (部署器)**：实现一键部署到不同的平台，例如 hexo-deployer-git。
  • **Filter (过滤器)**：在 Hexo 处理文件的特定阶段修改内容。
  • **Generator (生成器)**：用于创建网站的页面或数据。
  • **Tag (标签)**：让你在 Markdown 文章中可以方便地嵌入特定格式的内容，比如 {% post_link hello-world %}。

Hexo 是如何加载插件的？

简单来说，当我们运行 hexo 命令时，它会初始化并加载所有插件。这个过程主要依赖于 load_plugins.js 脚本，它会做两件重要的事情：

  1. loadModules：读取 package.json 文件，加载所有 Hexo 自带的以及你通过 npm install 安装的第三方插件。
  2. loadScripts：加载 scripts 目录下的脚本文件。
// Hexo 加载插件的核心逻辑
module.exports = ctx => {
  if (!ctx.env.init || ctx.env.safe) return;
  return loadModules(ctx).then(() => loadScripts(ctx));
};

如果你的插件代码有错误，Hexo 在启动时通常会报错并停止运行。所以，开发时记得多留意控制台的错误日志。

从零开始开发一个 NPM 插件

接下来，我们进入实战环节，一步步创建一个简单的“标签”插件。

第 1 步：初始化项目

首先，创建一个新的文件夹来存放你的插件代码，然后进入这个文件夹，运行 npm init 命令来初始化项目。

mkdir my-hexo-plugin
cd my-hexo-plugin
npm init

npm init 会引导你填写一些项目信息，这些信息最终会生成 package.json 文件。

  • **package name (插件名)**：这个名字将是别人 npm install 时的包名，所以要确保在 NPM 上是唯一的。
  • **version (版本号)**：通常从 1.0.0 开始。
  • **description (描述)**：简单介绍一下你的插件是做什么的。
  • **entry point (入口文件)**：插件的主程序文件，默认是 index.js。
  • **git repository (Git 仓库)**：你的代码仓库地址，方便别人查看源码。
  • **keywords (关键词)**：方便别人在 NPM 上搜索到你的插件，建议包含 hexo。
  • **author (作者)**：你的大名。
  • **license (许可证)**：默认是 ISC。

第 2 步：编写插件核心代码

初始化完成后，你会看到一个 package.json 文件。现在，我们来创建入口文件 index.js，并编写插件的核心逻辑。

我们的目标是创建一个 showText 标签，它可以在文章中输出一行标题。

// index.js

// 1. 定义插件的核心函数
// args 是标签的参数数组，content 是标签包裹的内容 (我们这个插件用不到)
function showText (args, content) {
  // 从参数中获取要显示的文本，如果没有提供，就用 'non' 作为默认值
  const text = args[0] || 'non';

  // 在控制台打印日志，方便调试
  console.log("showText Plugin is running!");

  // 返回最终要渲染到 HTML 里的内容
  return `<h1>${text}</h1>`;
}

// 2. 向 Hexo 注册这个标签
// hexo.extend.tag.register(标签名, 核心函数, { ends: false });
// ends: false 表示这个标签是单闭合的，例如 {% showText "Hello World" %}
hexo.extend.tag.register('showText', showText, { ends: false });

第 3 步：发布到 NPM

代码写完了，现在把它发布出去，让全世界都能用！

  1. 注册和登录 NPM

    • 先去 NPM 官网 注册一个账号。
    • 在命令行中运行 npm login 或 npm adduser 来登录。
    • 输入你的用户名、密码和邮箱，然后去邮箱查收验证码并输入。
    • 登录成功后，可以用 npm whoami 命令来检查当前的登录状态。

  2. 发布！
    直接在你的插件项目根目录下运行：

    npm publish

    如果一切顺利，你的插件就发布成功了！可以去 NPM 官网上搜索你的包名看看。

    注意: 每次发布新版本时，都需要在 package.json 文件中修改 version 字段，版本号必须比上一个高。

第 4 步：完善文档

一个好的插件离不开清晰的文档。强烈建议你在项目根目录下创建一个 README.md 文件，详细说明插件的用途、如何安装、如何配置以及使用示例。

第 5 步：在 Hexo 项目中测试

插件发布成功后，我们来自己的 Hexo 博客里测试一下。

  1. 进入你的 Hexo 项目目录，通过 npm 安装刚刚发布的插件：

    npm install <你的插件名>

  2. 安装完成后，在你的任意一篇 Markdown 文章里使用这个新标签：

    ---
title: Test My Plugin
---

这是一个测试。

{% showText "你好，我的第一个 Hexo 插件！" %}

  3. 运行 hexo g 和 hexo s，然后打开浏览器预览，如果能看到 “你好，我的第一个 Hexo 插件！” 这行 H1 标题，那就说明你的插件成功了！

常见问题与解决方案

开发和发布过程中可能会遇到一些坑，这里列举几个常见的问题：

  • npm login 登录失败？

    • 检查一下你是否配置了代理。运行 npm config list -l 查看配置，如果有名为 https-proxy 的配置项，可以用 npm config delete https-proxy 命令删除它。

  • npm publish 发布失败？

    • 最常见的原因是你的 npm registry 指向了国内的淘宝镜像 (cnpm)。发布需要切换回官方源。
    • 运行 npm config set registry https://registry.npmjs.org/ 切换到官方源，发布成功后再切回来。

  • 网络问题？

    • 如果一直卡在某个步骤，有时候切换网络（比如用手机热点）会有奇效。

版本管理

插件开发是一个持续迭代的过程，良好的版本管理非常重要。

发布测试版

在发布正式版之前，可以先发布一个 beta 测试版，让大家帮你测试。

  1. 在 package.json 中修改版本号，例如 1.0.1-beta.1。
  2. 正常执行 npm publish 发布。
  3. 别人可以通过 npm install <你的插件名>@beta 来安装这个测试版。

包的升级与删除

  • 升级包：当你的插件发布了新版本后，在 Hexo 项目中运行 npm update <你的插件名> 就可以升级到最新版。

  • 删除包：如果你想从 NPM 上删除某个包，需要注意：

    • 只能在发布后的 72小时 内删除。
    • 命令是：npm unpublish <你的插件名> --force。
    • 重要：一旦你删除了某个版本的包，在 24小时 内你将无法再次发布同名同版本的包。如果你急着发布，只能修改包名或者等 24 小时。

希望这篇教程能帮助你打开 Hexo 插件开发的大门！动手试试吧，你会发现为自己的博客添加新功能是一件非常有成就感的事情。

Hexo 教程 插件开发
  目录