插件管理指南

插件系统概述

Hexo 拥有强大的插件系统，可以轻松扩展功能而无需修改核心代码。插件分为两种类型：

类型说明适用场景
Script简单脚本快速添加小功能
Plugin完整插件包复杂功能或发布到 NPM

本项目已安装插件

核心插件

插件版本用途
hexo^8.0.0Hexo 核心
hexo-server^3.0.0本地开发服务器
hexo-renderer-ejs^2.0.0EJS 模板渲染
hexo-renderer-marked^7.0.0Markdown 渲染
hexo-renderer-stylus^3.0.1Stylus 样式渲染

生成器插件

插件版本用途
hexo-generator-index^4.0.0首页生成
hexo-generator-archive^2.0.0归档页生成
hexo-generator-category^2.0.0分类页生成
hexo-generator-tag^2.0.0标签页生成
hexo-generator-sitemap^3.0.1Sitemap 生成
hexo-generator-searchdb^1.5.0本地搜索索引

功能插件

插件版本用途
hexo-abbrlink^2.2.1文章短链接生成
hexo-prism-plugin^2.3.0代码高亮
hexo-deployer-git^4.0.0Git 部署

优化插件

插件版本用途
hexo-clean-css^2.0.0CSS 压缩
hexo-html-minifier^1.0.0HTML 压缩
hexo-uglify^2.0.0JavaScript 压缩

主题

插件版本用途
hexo-theme-butterfly^5.5.4Butterfly 主题
hexo-theme-landscape^1.0.0默认主题

插件操作

安装插件

1
2
3
4
5
6
7
8
# 使用 npm
npm install 插件名称 --save

# 使用 yarn
yarn add 插件名称

# 示例：安装字数统计插件
npm install hexo-wordcount --save

卸载插件

1
2
3
4
5
# 使用 npm
npm uninstall 插件名称 --save

# 使用 yarn
yarn remove 插件名称

更新插件

1
2
3
4
5
6
7
8
# 更新单个插件
npm update hexo-abbrlink

# 更新所有插件
npm update

# 查看可更新的插件
npm outdated

查看已安装插件

1
2
3
4
5
# 列出所有依赖
npm list --depth=0

# 列出 hexo 相关插件
npm list | grep hexo

常用推荐插件

SEO 相关

1
2
3
4
5
6
7
8
# Sitemap（已安装）
npm install hexo-generator-sitemap --save

# RSS 订阅
npm install hexo-generator-feed --save

# Open Graph 标签
npm install hexo-helper-open-graph --save

内容相关

1
2
3
4
5
6
7
8
# 字数统计
npm install hexo-wordcount --save

# 阅读时间
npm install hexo-reading-time --save

# 图片懒加载
npm install hexo-lazyload --save

样式相关

1
2
3
4
5
# 图标
npm install hexo-font-awesome --save

# 数学公式
npm install hexo-renderer-math --save

工具相关

1
2
3
4
5
# 图片压缩
npm install hexo-imagemin --save

# 文件 MD5
npm install hexo-generator-md5 --save

插件配置

1
2
3
4
# _config.yml
abbrlink:
  alg: crc32      # 算法：crc32
  rep: dec        # 进制：dec(十进制) 或 hex(十六进制)

搜索配置

1
2
3
4
5
6
# _config.yml
search:
  path: search.xml
  field: post
  format: html
  limit: 10000

Sitemap 配置

1
2
3
4
# _config.yml
sitemap:
  path: sitemap.xml
  rel: false

代码高亮配置

1
2
3
4
5
6
# _config.yml
syntax_highlighter: prismjs
prismjs:
  preprocess: true
  line_number: true
  tab_replace: ''

插件开发

Script 类型

在 scripts/ 目录下创建 JavaScript 文件：

1
2
3
4
5
6
7
8
// scripts/my-plugin.js
hexo.on('generate:before', function() {
  console.log('开始生成...');
});

hexo.on('generate:after', function() {
  console.log('生成完成！');
});

Plugin 类型

创建独立的 npm 包：

1
2
3
hexo-my-plugin/
├── index.js
└── package.json

package.json 最少需要：

1
2
3
4
5
{
  "name": "hexo-my-plugin",
  "version": "0.0.1",
  "main": "index"
}

可用事件

事件说明
initHexo 初始化
generate:before生成前
generate:after生成后
deploy:before部署前
deploy:after部署后
server服务器启动

插件冲突排查

常见冲突

  1. 多个 Markdown 渲染器

    • 只保留一个：hexo-renderer-marked

  2. 多个代码高亮插件

    • 选择一个：hexo-prism-plugin 或 highlight.js

  3. 多个部署插件

    • 只启用一个：hexo-deployer-git

排查步骤

1
2
3
4
5
6
7
8
9
10
11
# 1. 清除缓存
hexo clean

# 2. 查看详细日志
hexo server --debug

# 3. 临时禁用可疑插件
npm uninstall 插件名称

# 4. 重新测试
hexo server

插件性能影响

构建速度优化

1
2
3
4
5
# _config.yml
ignore:
  - source/**/*.psd
  - source/**/*.ai
  - source/**/*.svg

按需加载

某些插件支持按页面加载：

1
2
3
# 数学公式按需加载
math:
  per_page: false  # 在文章 Front-matter 中设置 math: true

注意事项

  1. Node.js 版本：使用 22，不要使用 24
  2. 插件兼容性：安装前检查是否支持 Hexo 8
  3. 主题兼容性：某些插件需要主题支持
  4. 性能影响：过多插件会影响构建速度
  5. 安全更新：定期更新插件以修复安全漏洞

下一步