Hexo插件开发步骤

作者: 時光
来源: 時光的博客园子
原文: https://blog.shiguang666.eu.org/2024/06/22/9633525b3409/

Hexo插件开发步骤

Hexo的插件嵌入有两种方式，一种是通过脚本（Scripts）的方式引入，一种是通过插件（Packages）的方式将自定义的插件内容发布到npm上。本文主要介绍第二种，如果您的代码很简单，建议您编写脚本，您只需要把 JavaScript 文件放到主题目录的 scripts 文件夹，在启动时就会自动加载。具体操作可参考 Hexo 博客每天自动生成每日早报文章中2.2相关介绍。

下面是引用官方的一段话，开发Hexo插件至少要包含 2 个文件：一个是主程序index.js，另一个是 package.json，描述插件的用途和所依赖的插件。package.json 中至少要包含 name, version, main 属性。

链接直达：https://hexo.io/zh-cn/docs/plugins

如果您的代码较复杂，或是您想要发布到 NPM 上，建议您编写插件。首先，在 node_modules 文件夹中建立文件夹，文件夹名称开头必须为 hexo-，如此一来 Hexo 才会在启动时加载；否则 Hexo 将会忽略它。

文件夹内至少要包含 2 个文件：一个是主程序，另一个是 package.json，描述插件的用途和所依赖的插件。
.
├── index.js
└── package.json
package.json 中至少要包含 name, version, main 属性，例如：
package.json{
"name": "hexo-my-plugin",
"version": "0.0.1",
"main": "index"
}

一、创建插件项目

创建一个新的目录来存放你的插件项目，文件夹名称开头必须为 hexo-，例如 hexo-footer-plugin

可在任意目录创建,为方便测试也可直接在Hexo项目的node_modules目录下创建

mkdir hexo-footer-plugin

进入该目录

cd hexo-footer-plugin

初始化一个新的 npm 项目

npm init

使用npm init初始化有操作向导，会引导你一步步输入package.json文件的不同参数。

也可使用npm init -y 初始化一个仅包含默认参数的package.json文件

{
  "name": "hexo-footer-plugin",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

然后自行修改，例如

{
  "name": "hexo-footer-plugin",
  "version": "1.0.0",
  "description": "A Hexo plugin to add a custom footer with copyright information to posts.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "hexo",
    "plugin",
    "footer",
    "copyright"
  ],
  "author": {
    "name": "Shiguang-coding",
    "email": "an_shiguang@163.com",
    "url": "https://blog.shiguang666.eu.org"
  },
  "license": "MIT",
  "dependencies": {
    "hexo": "^5.0.0"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/Shiguang-coding/hexo-footer-plugin.git"
  },
  "bugs": {
    "url": "https://github.com/Shiguang-coding/hexo-footer-plugin/issues"
  },
  "homepage": "https://github.com/Shiguang-coding/hexo-footer-plugin#readme"
}

在发布npm包时，仓库信息（repository）是一个可选字段，但建议填写。仓库信息可以帮助其他开发者更容易地找到和贡献代码。如果你不想填写仓库信息，可以省略这个字段。

二、编写插件代码

2.1、介绍

可参考官方文档进行开发

Hexo API

Hexo插件文档中文版

Hexo插件文档英文版

工具

您可以使用 Hexo 提供的官方工具插件来加速开发：

hexo-fs：文件 IO

hexo-util：工具程式

hexo-i18n：本地化（i18n）

hexo-pagination：生成分页数据

除了辅助函数（Helper），Hexo的插件还可划分为不同类型：控制台 (Console)、部署器 (Deployer)、过滤器 (Filter)、生成器 (Generator)、迁移器 (Migrator)、处理器 (Processor)、渲染引擎 (Renderer)、标签 (Tag)。

Hexo初始化的时候会相应加载插件列表，代码详见 node_modules\hexo\lib\hexo\index.js

// Load internal plugins
require('../plugins/console')(this);
require('../plugins/filter')(this);
require('../plugins/generator')(this);
require('../plugins/helper')(this);
require('../plugins/injector')(this);
require('../plugins/processor')(this);
require('../plugins/renderer')(this);
require('../plugins/tag')(this);

// Load config
return Promise.each([
    'update_package', // Update package.json
    'load_config', // Load config
    'load_theme_config', // Load alternate theme config
    'load_plugins' // Load external plugins & scripts
], name => require(`./${name}`)(this)).then(() => this.execFilter('after_init', null, { context: this })).then(() => {
    // Ready to go!
    this.emit('ready');
});
}

插件加载依托于load_plugins.js，其主要函数有loadModules、loadScripts

loadModules : 调用loadModuleList读取package.json，从而进一步加载插件列表(自带&第三方插件)
loadScripts : 加载脚本类插件(自带&主题scripts下的脚本)

module.exports = ctx => {
  if (!ctx.env.init || ctx.env.safe) return;
  return loadModules(ctx).then(() => loadScripts(ctx));
};

部分插件如果存在编译错误则Hexo会无法正常启动且输出错误日志，根据日志检查错误相应调整即可。

2.2、开发示例

在你的插件目录中创建一个 index.js 文件，并编写你的插件代码。例如：

想要了解更多过滤器及执行顺序可参考过滤器列表，事件

hexo.extend.filter.register('after_post_render', function(data){
  // 你的插件逻辑
});

hexo.extend.filter.register('after_post_render', function(data){
    // 添加调试信息，打印当前时间戳和消息
    console.log("Debug: hexo-footer-plugin is running at", new Date().toISOString());
  
    const { config } = hexo;

    const isEnabled = config['hexo-footer-plugin']?.enable;

    if(!isEnabled){
      console.warn("hexo-footer-plugin 插件尚未启用!!");
      return;
    }
    const copyrightOwner = config['hexo-footer-plugin']?.copyright_owner;
  
    if (!copyrightOwner) {
      console.warn("Warning: copyright_owner is not set in the configuration.");
      return data;
    }
  
    console.log("copyrightOwner:", copyrightOwner);
  
    // 构建版权声明字符串
    var footer = "\n<div id='custom-footer'>© " + new Date().getFullYear() + " " + copyrightOwner + "</div>";
  
    // 将版权声明添加到文章内容的末尾
    data.content += footer;
  
    // 再次添加调试信息，确认版权声明已被添加
    console.log("Debug: footer added to post content");
  
    // 返回修改后的内容
    return data;
  });

const { config } = hexo;

// 获取 hexo-footer-plugin 下的 copyright_owner 配置
const copyrightOwner = config['hexo-footer-plugin']?.copyright_owner;

console.log(copyrightOwner);

在这段代码中，我们首先从 hexo 实例中获取配置对象 config。然后，我们通过点符号访问嵌套的配置项。注意，我们使用了可选链 ?. 来避免在配置项不存在时抛出错误。

如果 hexo-footer-plugin 或 copyright_owner 在配置文件中不存在，copyrightOwner 将保持未定义状态，而不会引发错误。

2.3、本地测试

2.3.1、初始化Hexo项目

我们重新初始化一个Hexo项目

hexo init blog
cd blog

初始化好后可以先执行三连命令运行看下效果

hexo clean && hexo g && hexo s

2.3.2、安装插件依赖

1、通过 `npm install` 安装

在你的 Hexo 项目目录中，使用以下命令将本地插件链接到你的 Hexo 项目：

npm install /path/to/your/hexo-footer-plugin

例如我Hexo项目目录为 D:\hexo\test\blog，插件存放目录为 D:\hexo\plugins\hexo-footer-plugin

执行安装命令，由于npm安装较慢，我使用的cnpm进行安装

cnpm install ../../plugins/hexo-footer-plugin

可以看到控制台提示成功添加一个依赖，插件名称 hexo-footer-plugin 版本号 ^1.0.0

我们到Hexo项目node_modules检查一下

再检查下Hexo项目根目录下package.json引入的依赖 dependencies

或者通过命令 npm ls 查看引入的依赖

2、通过 `npm link` 安装

或者，你也可以使用 npm link 命令来创建一个全局链接，然后在 Hexo 项目中使用这个链接：

以管理员权限执行命令，否则会出现 npm ERR! errno -4048 错误

cd /path/to/your/hexo-footer-plugin
npm link
cd /path/to/your/hexo-project
npm link hexo-footer-plugin

更多关于 npm link命令的内容详见 npm link 基本使用

执行npm ls 查看link是否创建成功

检查Hexo项目根目录 package.json文件，如果没有 dependencies 部分，可以手动创建一个。然后，添加你链接的包的名称和版本。例如，如果你链接的包名为 my-package，你可以这样添加：

{
  "dependencies": {
    "my-package": "file:../path/to/my-package"
  }
}

例如此处我需要修改为

{
  "dependencies": {
    "hexo-footer-plugin": "file:./../../plugins/hexo-footer-plugin"
  }
}

3、手动引入依赖

直接复制插件目录 hexo-footer-plugin 到Hexo项目 node_modules文件夹内

修改Hexo项目根目录 package.json文件，在dependencies 部分添加插件依赖

{
  "dependencies": {
    "hexo-footer-plugin": "^1.0.0"
  }
}

2.3.3、修改配置文件

在Hexo主配置文件 _config.yml 中添加插件的配置，注意不是主题的_config.yml

hexo-footer-plugin:
  enable: true
  copyright_owner: Your Name

也有说需要添加下面这条配置的，我不添加也是可以的
plugins:
  - hexo-footer-plugin
这段代码是 Hexo 配置文件_config.yml 中的一部分，用于指定 Hexo 博客项目所使用的插件。具体来说，这段代码的含义和作用如下：

含义：

plugins：这是一个配置项，用于列出当前 Hexo 项目所使用的所有插件。

- hexo-footer-plugin：这是插件列表中的一个条目，表示当前项目使用了名为 hexo-footer-plugin 的插件。

作用：

插件管理：通过在 _config.yml 文件中列出插件，Hexo 在启动时会自动加载这些插件，并执行插件中定义的各种功能。

功能扩展：hexo-footer-plugin 是一个自定义插件，通过在 _config.yml 中声明它，Hexo 会在生成博客内容时调用该插件，从而实现特定的功能扩展。例如，在你的例子中，hexo-footer-plugin 可能用于在每篇文章的末尾添加版权声明。

总结来说，这段代码的作用是告诉 Hexo 在生成博客内容时要加载并使用 hexo-footer-plugin 插件，以便实现该插件所提供的功能。

2.3.4、重新运行并测试插件

hexo clean && hexo g && hexo s

注意：此处每次运行一定要执行 hexo clean 插件才会执行生效

控制台也会有相应日志输出

三、发布到 NPM

确保你的插件目录中包含 index.js 文件，这是插件的入口文件。

添加 README.md 文件，提供插件的详细说明、安装方法和使用示例。

添加 LICENSE 文件，声明你的插件使用的开源许可证。

如果你还没有 npm 账号，需要先注册一个：

npm adduser

如果你已经有账号，直接登录：

npm login

提示回车打开浏览器访问页面，无论注册或登录都需要获取一次性密码(One-time Password)，即邮箱验证码

发布你的插件：

npm publish

控制台提示如下信息即代表发布成功

发布成功后可直接在NPM官网查询

如果要更新插件的话，改下版本号重新发布即可。

四、安装并使用插件

4.1、安装插件

安装前先将Hexo根目录下node_modules目录以及package.json刚才引入的依赖移除重新执行项目确保原配置已失效，或者重新初始化个Hexo项目。

在你的 Hexo 项目目录中，使用以下命令安装你的插件：

npm install hexo-footer-plugin --save

或者

cnpm install hexo-footer-plugin --save

如下

4.2、修改配置文件

在你的 Hexo 项目配置文件 _config.yml 中添加插件的配置：

hexo-footer-plugin:
  enable: true
  copyright_owner: Your Name

4.3、重新运行并测试插件

hexo clean && hexo g && hexo s

注意：此处每次运行一定要执行 hexo clean 插件才会执行生效

五、文档和宣传

在 GitHub 上创建一个仓库，并将你的插件代码推送到这个仓库。

在 README 文件中提供详细的安装和使用说明。

在 Hexo 社区或其他相关论坛宣传你的插件。

六、提交插件到 Hexo 插件列表

打开 Hexo 官方插件列表的 GitHub 仓库：hexojs/site。

点击右上角的 "Fork" 按钮，将仓库 fork 到你自己的 GitHub 账户。

克隆你 fork 的仓库到本地：

git clone https://github.com/YOUR_GITHUB_USERNAME/site.git

进入 source/_data/plugins 目录并创建your-plugin-name.yml文件，添加你的插件信息。例如：

description: A Hexo plugin to add a custom footer with copyright information to posts.
link: https://github.com/Shiguang-coding/hexo-footer-plugin
tags:
  - plugin
  - footer
  - copyright

提交并推送你的更改：

git add source/_data/plugins/your-plugin-name.yml
git commit -m "Add my Hexo plugin"
git push origin master

在你的 GitHub 仓库页面中，点击 "New pull request" 按钮，提交你的更改给 Hexo 官方插件列表。

提交 pull request 后，Hexo 团队会审核你的插件。一旦审核通过，你的插件就会被添加到 Hexo 官方插件列表中。

参考

Hexo API

Hexo 贡献

Hexo Plugins

hexo-butterfly-npm标签插件开发

Hexo + Typora + 开发Hexo插件解决图片路径不一致

posted @ 2024-06-26 14:59 時光心向阳阅读(81) 评论(0) 编辑收藏举报

刷新页面返回顶部

時光

Hexo插件开发步骤

Hexo插件开发步骤

一、创建插件项目

二、编写插件代码

2.1、介绍

工具

2.2、开发示例

2.3、本地测试

2.3.1、初始化Hexo项目

2.3.2、安装插件依赖

1、通过 npm install 安装

2、通过 npm link 安装

3、手动引入依赖

2.3.3、修改配置文件

2.3.4、重新运行并测试插件

三、发布到 NPM

四、安装并使用插件

4.1、安装插件

4.2、修改配置文件

4.3、重新运行并测试插件

五、文档和宣传

六、提交插件到 Hexo 插件列表

公告

1、通过 `npm install` 安装

2、通过 `npm link` 安装