NexT 主题配置手册

发表于 更新于 分类于

NexT 主题配置手册

本手册严格依据 NexT 官方文档（https://theme-next.js.org/docs/）及官方默认配置文件编写，涵盖从安装、配置到部署、排错的全部内容。 适用版本：NexT v8.29.0+（当前活跃版本，仓库：https://github.com/next-theme/hexo-theme-next）

目录

第零章 NexT 概览

0.1 核心特性

NexT 是 Hexo 的优雅而强大的主题，具备以下特性：

  • 原生 JavaScript：无 jQuery 依赖（v8.29.0 起移除 Anime.js，改用原生 API）
  • 原生暗色模式：支持 prefers-color-scheme 自动切换
  • Pjax：提供快速浏览体验，类似 SPA
  • 数学公式：集成 MathJax（支持 v4）和 KaTeX
  • PDF 与图表：集成 PDF.js、Mermaid、WaveDrom
  • 评论系统：支持 Disqus、DisqusJS、LiveRe、Gitalk、Utterances、Isso，可多系统共存
  • 统计服务：支持 Google Analytics、百度统计、Cloudflare、Microsoft Clarity、Matomo、Umami、Plausible、Firebase、不蒜子等
  • CDN 切换：轻松切换 jsDelivr、UNPKG、CDNJS 或自定义 CDN
  • 易于定制：自定义文件、注入点、Stylus 变量覆盖

0.2 四种 Scheme

Scheme 说明
Muse 默认方案，黑白基调，简洁（单栏）
Mist Muse 的紧凑版，整洁单栏视图
Pisces 双栏方案，清新
Gemini 类似 Pisces，但列块带阴影，更具层次感

几乎所有配置选项在四种 Scheme 中通用。

0.3 多语言支持

NexT 支持 20+ 种语言，包括简体中文、繁体中文、英语、日语、韩语等。

0.4 代码高亮

NexT 使用 Highlight.js 和 Prism 提供 300+ 代码高亮主题，支持明暗双主题。

0.5 浏览器兼容性

浏览器 最低版本 发布日期
Chrome 80+ 2020-02-05
Firefox 74+ 2020-03-10
Opera 67+ 2020-03-12
Safari 13.1+ 2020-03-24
Edge 80+ 2020-02-07
IE 不支持 —

核心功能和样式在以上浏览器正常工作（不含第三方插件）。NexT 使用了 CSS 变量、IntersectionObserver、prefers-color-scheme 等现代 Web API。

第一章 入门指南

1.1 环境准备（Windows 10/11）

以下为 2026 年推荐的软件版本，过低可能导致插件不兼容，过高（如 Node.js 22）可能引发部分 Hexo 插件异常。

软件 推荐版本 说明
Node.js v20.x LTS 不要用 22（部分插件兼容性差），不要低于 18
Git 2.45+ 版本管理与主题克隆
Hexo 7.3+ 博客框架
hexo-theme-next v8.21.x+ 当前活跃版本

1.1.1 安装 Node.js

  1. 下载地址：https://nodejs.org/ ，选择 LTS 长期支持版（v20.x）。
  2. 安装时全部默认下一步，务必勾选 Add to PATH（添加到系统环境变量）。
  3. 安装完成后，新开 cmd 或 PowerShell 窗口验证：
1
2
node -v
npm -v

能输出版本号即成功。若提示”不是内部或外部命令”，请重启终端或检查环境变量。

  1. （可选，强烈建议）npm 国内镜像加速：
1
npm config set registry https://registry.npmmirror.com

1.1.2 安装 Git

  1. 下载地址：https://git-scm.com/download/win
  2. 全部默认安装，安装后桌面右键应出现 Git Bash Here。
  3. 打开 cmd 验证：
1
git --version
  1. 配置用户名和邮箱（用于提交代码）：
1
2
git config --global user.name "你的用户名"
git config --global user.email "你的GitHub邮箱"

1.2 安装 Hexo 并初始化站点

  1. 全局安装 Hexo CLI：
1
npm i -g hexo-cli
  1. 初始化 Hexo 站点：
1
hexo init hexo-site

可将 hexo-site 替换为任意路径名，本手册统一以 hexo-site 为例，称为站点根目录。

  1. 安装依赖并验证：
1
2
3
cd hexo-site
npm install
hexo s

安装成功后，站点根目录应包含 package.json、source、themes 等目录：

1
_config.yml  node_modules  package-lock.json  package.json  scaffolds  source  themes

1.3 NexT 安装

NexT 提供两种安装方式，任选其一：

方式一：通过 npm（推荐，需 Hexo 5.0+）

1
2
cd hexo-site
npm install hexo-theme-next

安装指定版本： 

1
npm install hexo-theme-next@8.0.0

安装最新发布版： 

1
npm install hexo-theme-next@latest

方式二：通过 Git

1
2
cd hexo-site
git clone https://github.com/next-theme/hexo-theme-next themes/next

若遇网络问题，可设置代理： 

1
git config --global http.proxy http://proxy-server:port

克隆后可切换到指定版本： 

1
2
3
4
cd themes/next
git tag -l                          # 列出所有版本标签
git checkout tags/v8.0.0            # 切换到 v8.0.0
git checkout master                 # 切回 master 分支

注意：不建议从 GitHub 下载 zip 压缩包安装，因为难以管理和升级。

1.4 配置文件

NexT 使用两类配置文件：

配置文件 位置 说明
Hexo 配置文件 站点根目录 _config.yml Hexo 本身的配置
NexT 配置文件 站点根目录 _config.next.yml NexT 主题的配置（需自行创建）

首次安装后，执行以下命令复制默认配置：

1
2
3
4
5
# npm 安装方式
cp node_modules/hexo-theme-next/_config.yml _config.next.yml

# Git 安装方式
cp themes/next/_config.yml _config.next.yml

重要：请勿直接修改 themes/next/_config.yml 或 node_modules/hexo-theme-next/_config.yml，升级时这些文件会被覆盖。所有自定义配置均应写在 _config.next.yml 中。

另一种方式是在 Hexo 配置文件中使用 theme_config: 节点，将 NexT 配置缩进两格后写入，但推荐使用独立的 _config.next.yml 文件。

旧版 /source/_data/next.yml 方式已废弃，请迁移至 _config.next.yml。

1.5 Hexo 基础配置

编辑 Hexo 配置文件 _config.yml：

1
2
3
4
5
6
# 站点
author: 你的昵称
description: 站点描述

# 启用 NexT 主题
theme: next

1.6 验证安装

1
2
hexo clean
hexo s --debug

当看到 INFO Hexo is running at http://localhost:4000/ 时，在浏览器打开 http://localhost:4000，若看到默认的 Muse 方案页面即安装成功。

第二章 主题快速设置

以下配置均在 NexT 配置文件 _config.next.yml 中修改，除非特别说明。 标注 [默认] 的值为官方默认配置。

2.1 缓存与压缩

1
2
3
4
5
6
# 允许缓存内容生成，提升构建速度 [默认: true]
cache:
  enable: true

# hexo generate 后移除不必要的文件 [默认: false]
minify: false

2.2 选择 Scheme

NexT 提供四种 Scheme，取消注释其中一行即可切换：

1
2
3
4
scheme: Muse       # [默认] 黑白基调，简洁单栏
#scheme: Mist     # Muse 的紧凑版，单栏
#scheme: Pisces   # 双栏，清新
#scheme: Gemini   # 双栏，列块带阴影

2.3 暗色模式

NexT 会根据操作系统的 prefers-color-scheme 设置自动切换暗色模式。

1
2
# 自 v8.27.0 起默认启用暗色模式 [默认: true]
darkmode: true

更精细的明暗模式控制：

1
2
3
4
lightdark:
  enable: false
  # 添加 @supports (color: light-dark(red, red)) 检查
  check_supports: true

2.4 Favicon 配置

将图标文件放入 source/images/ 目录，然后修改：

1
2
3
4
5
6
favicon:
  small: /images/favicon-16x16-next.png
  medium: /images/favicon-32x32-next.png
  apple_touch_icon: /images/apple-touch-icon-next.png
  safari_pinned_tab: /images/logo.svg
  #android_manifest: /manifest.json

若将 favicon 放在 source/ 根目录，需去掉路径中的 /images 前缀。

1
custom_logo: /uploads/custom-logo.jpg

注意：Mist 方案不支持自定义 Logo。

2.6 知识共享协议

NexT 支持 Creative Commons 4.0 国际许可协议：

1
2
3
4
5
6
7
8
9
creative_commons:
  # 可选值：by | by-nc | by-nc-nd | by-nc-sa | by-nd | by-sa | cc-zero
  license: by-nc-sa
  # 可选值：big | small
  size: small
  sidebar: false   # [默认] 在侧边栏显示
  post: false      # [默认] 在文章末尾显示
  # 协议语言，如 deed.zh 为中文版
  language:

2.7 Open Graph

1
2
3
4
5
6
7
8
9
10
open_graph:
  enable: true
  options:
    type: blog
    #twitter_card: <twitter:card>
    #twitter_id: <twitter:creator>
    #twitter_site: <twitter:site>
    #twitter_image: <twitter:image>
    #fb_admins: <fb:admin_id>
    #fb_app_id: <fb:app_id>

2.8 菜单项配置

菜单项格式为 Key: /link/ || icon，包含三个值：

  • Key：菜单项名称（区分大小写），若语言文件中有对应翻译则自动加载
  • link：|| 之前的部分，站内相对链接；外部链接需以 http:// 或 https:// 开头
  • icon：|| 之后的部分，Font Awesome 图标名称
1
2
3
4
5
6
7
8
9
menu:
  #home: / || fa fa-home
  #about: /about/ || fa fa-user
  #tags: /tags/ || fa fa-tags
  #categories: /categories/ || fa fa-th
  #archives: /archives/ || fa fa-archive
  #schedule: /schedule/ || fa fa-calendar
  #sitemap: /sitemap.xml || fa fa-sitemap
  #commonweal: /404/ || fa fa-heartbeat

除 home 和 archives 外，所有自定义页面需手动创建，见第六章。 sitemap 需要安装 hexo-generator-sitemap 插件。

多级子菜单

支持层级子菜单，每个子菜单需包含 default 项：

1
2
3
4
5
6
7
8
9
10
menu:
  home: / || fa fa-home
  archives: /archives/ || fa fa-archive
  Docs:
    default: /docs/ || fa fa-book
    Getting Started:
      default: /getting-started/ || fa fa-flag
      Installation: /installation.html || fa fa-download
    Third Party Plugins:
      default: /third-party-services/ || fa fa-puzzle-piece

菜单设置

1
2
3
menu_settings:
  icons: true    # [默认] 显示菜单图标
  badges: false  # [默认] 显示文章/分类/标签数量徽标

第三章 侧边栏设置

3.1 侧边栏样式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
sidebar:
  # 位置：left [默认] | right
  position: left

  # Muse/Mist 方案及 Pisces/Gemini 移动端的侧边栏宽度（像素）[默认: 320]
  width_expanded: 320

  # Pisces/Gemini 桌面端双栏宽度（像素）[默认: 240]
  width_dual_column: 240

  # 显示条件：
  #   post   [默认] 仅在有目录的文章页显示
  #   always 所有页面显示
  #   hide   隐藏（用户可手动打开）
  #   remove 完全移除
  display: post

  # 内边距（像素）[默认: 18]
  padding: 18

  # 距顶部菜单栏的偏移量（像素），仅 Pisces/Gemini [默认: 12]
  offset: 12

3.2 头像

1
2
3
4
5
6
7
avatar:
  # 头像 URL，可使用本地路径或外部绝对 URL [默认: 注释，使用主题默认头像]
  url: #/images/avatar.gif
  # 圆形头像 [默认: false]
  rounded: false
  # 鼠标悬停时旋转 [默认: false]
  rotated: false

本地头像放在 source/images/ 目录下。

3.3 站点状态

1
2
# 在侧边栏显示文章/分类/标签数量 [默认: true]
site_state: true

3.4 社交链接

1
2
3
4
5
6
7
8
9
10
social:
  #GitHub: https://github.com/yourname || fab fa-github
  #E-Mail: mailto:yourname@gmail.com || fa fa-envelope
  #Weibo: https://weibo.com/yourname || fab fa-weibo
  #Twitter: https://twitter.com/yourname || fab fa-twitter
  #FB Page: https://www.facebook.com/yourname || fab fa-facebook
  #StackOverflow: https://stackoverflow.com/yourname || fab fa-stack-overflow
  #YouTube: https://youtube.com/yourname || fab fa-youtube
  #Instagram: https://instagram.com/yourname || fab fa-instagram
  #Skype: skype:yourname?call|chat || fab fa-skype

社交图标设置：

1
2
3
4
social_icons:
  enable: true       # [默认] 启用图标
  icons_only: false  # [默认] 仅显示图标，不显示文字
  transition: false  # [默认] 启用过渡动画

3.5 友情链接

1
2
3
4
5
6
links_settings:
  icon: fa fa-globe  # [默认] 链接前的图标
  layout: block      # [默认] block（块级）或 inline（行内）

links:
  #Title: https://example.com

3.6 文章目录（TOC）

1
2
3
4
5
6
toc:
  enable: true       # [默认] 启用目录
  number: true       # [默认] 自动添加列表编号
  wrap: false        # [默认] 长标题换行
  expand_all: false  # [默认] 展开所有层级（默认仅展开激活部分）
  max_depth: 6       # [默认] 最大标题深度

第四章 页脚设置

4.1 版权起始年份

1
2
3
footer:
  # 站点起始年份，显示为 © 2020 - 2026；不设置则仅显示当前年份
  #since: 2021

4.2 页脚图标

1
2
3
4
5
footer:
  icon:
    name: fa fa-heart   # [默认] Font Awesome 图标名
    animated: false     # [默认] 开启动画
    color: "#ff0000"    # [默认] 图标颜色（十六进制）

4.3 版权名称

1
2
3
footer:
  # 默认使用 Hexo 配置中的 author；设为 false 可完全隐藏版权声明
  copyright:

4.4 平台信息

1
2
3
footer:
  # [默认: true] 显示 "Powered by Hexo & NexT.Muse"
  powered: true

4.5 备案信息（中国用户）

1
2
3
4
5
6
7
footer:
  beian:
    enable: false       # [默认]
    icp:                # ICP 备案号
    gongan_id:          # 公安备案数字 ID
    gongan_num:         # 公安备案完整编号
    gongan_icon_url:    # 公安备案图标 URL

4.6 多语言切换器

1
2
# 在页脚显示多语言切换器 [默认: false]
language_switcher: false

第五章 文章设置

5.1 文章摘要

NexT 提供两种方式控制首页文章摘要显示：

  1. <!-- more --> 标签（推荐）：在文章中手动截断
  2. front-matter 中的 description：自动提取为摘要
1
2
3
4
5
# 启用 description 摘要 [默认: true]
excerpt_description: true

# 显示"阅读更多"按钮 [默认: true]
read_more_btn: true

推荐使用 <!-- more -->，控制更精确，且兼容 Hexo 插件。

5.2 文章元信息

1
2
3
4
5
6
7
8
9
post_meta:
  item_text: true     # [默认] 显示元信息描述文字
  created_at: true    # [默认] 显示创建日期
  categories: true    # [默认] 显示分类

  updated_at:
    enable: true      # [默认] 显示更新日期
    # [默认: true] 仅当更新日期与创建日期不同时显示更新标签
    another_day: true

updated_at 需正确配置 Hexo 的 use_date_for_updated 和 updated_option。

5.3 字数统计

需先安装插件：

1
2
npm install hexo-word-counter
hexo clean

在 Hexo 配置文件中配置：

1
2
3
4
5
6
7
symbols_count_time:
  symbols: true        # 文章字数
  time: true           # 阅读时长
  total_symbols: true  # 全站总字数（页脚）
  total_time: true     # 全站总阅读时长（页脚）
  awl: 4               # 平均词长
  wpm: 275             # 每分钟阅读字数

在 NexT 配置文件中调整显示：

1
2
3
symbols_count_time:
  separated_meta: true    # [默认] 字数和时长分两行显示
  item_text_total: false  # [默认] 页脚显示文字描述

5.4 标签图标

1
2
# 文章底部标签使用图标代替 # 号 [默认: false]
tag_icon: false

5.5 打赏设置

将收款二维码图片放入 source/images/ 或上传到图床：

1
2
3
4
5
6
7
8
9
reward_settings:
  enable: false    # [默认] 每篇文章默认显示打赏按钮
  animation: false # [默认] 打赏动画

reward:
  #wechatpay: /images/wechatpay.png
  #alipay: /images/alipay.png
  #paypal: /images/paypal.png
  #bitcoin: /images/bitcoin.png

5.6 关注我

1
2
3
4
5
follow_me:
  #Twitter: https://twitter.com/username || fab fa-twitter
  #Telegram: https://t.me/channel_name || fab fa-telegram
  #WeChat: /images/wechat_channel.png || fab fa-weixin
  #RSS: /atom.xml || fa fa-rss

可添加任意平台，如知乎：Zhihu: https://www.zhihu.com/people/username || fab fa-zhihu

5.7 相关文章

需安装插件（二选一）：

1
2
3
4
npm install hexo-related-posts
# 或
npm install hexo-posts-embedding
hexo clean

在 Hexo 配置文件中启用：

1
2
related_posts:
  enable: true

在 NexT 配置文件中启用：

1
2
3
related_posts:
  enable: false   # [默认]
  icon: fa fa-signs-post  # [默认] 相关文章图标

注意：需在 Hexo 和 NexT 配置文件中同时设置 enable: true。

5.8 文章编辑链接

1
2
3
4
5
6
post_edit:
  enable: false   # [默认]
  # 查看源码链接
  url: https://github.com/user-name/repo-name/tree/branch-name/subdirectory-name/
  # 编辑链接（取消注释使用）
  #url: https://github.com/user-name/repo-name/edit/branch-name/subdirectory-name/

5.9 文章导航

1
2
3
# 文章底部显示上一篇/下一篇 [默认: left]
# 可选值：left | right | false
post_navigation: left

第六章 自定义页面

6.1 添加自定义页面

1
2
cd hexo-site
hexo new page custom-name

编辑 source/custom-name/index.md 的 front-matter：

1
2
3
4
---
title: custom-name
date: 2014-12-22 12:39:04
---

在 NexT 配置文件的 menu 中添加链接：

1
2
3
4
menu:
  home: / || fa fa-home
  archives: /archives/ || fa fa-archive
  about: /about/ || fa fa-user

6.2 使用归档页作为首页

在 Hexo 配置文件中：

1
2
3
4
5
6
archive_dir: /

index_generator:
  path: archives
  per_page: 10
  order_by: -date

6.3 标签页

1
hexo new page tags

编辑 source/tags/index.md：

1
2
3
4
5
---
title: Tags
date: 2014-12-22 12:39:04
type: tags
---

在菜单中添加：

1
2
menu:
  tags: /tags/ || fa fa-tags

在 Hexo 配置文件中禁用冲突项：

1
2
tag_generator:
  enable_index_page: false

标签云设置

1
2
3
4
5
6
tagcloud:
  min: 12       # [默认] 最小字体（px）
  max: 30       # [默认] 最大字体（px）
  amount: 200   # [默认] 标签总数
  orderby: name # [默认] 排序方式
  order: 1      # [默认] 排序顺序

若不希望标签页显示评论，在该页面 front-matter 中添加 comments: false。

6.4 分类页

与标签页类似，将 tags 替换为 categories：

1
hexo new page categories
1
2
3
4
5
---
title: Categories
date: 2014-12-22 12:39:04
type: categories
---
1
2
menu:
  categories: /categories/ || fa fa-th

6.5 Google 日历页面

  1. 确保 Google 日历设为公开
  2. 获取 Calendar ID 和 API Key（Google Developers 控制台启用 Google Calendar API）
1
hexo new page schedule
1
2
3
4
5
---
title: Schedule
date: 2014-12-22 12:39:04
type: schedule
---
1
2
3
4
5
6
7
8
9
10
calendar:
  calendar_id: <必填>
  api_key: <必填>
  orderBy: startTime
  showLocation: false
  offsetMax: 72
  offsetMin: 4
  showDeleted: false
  singleEvents: true
  maxResults: 250
1
2
menu:
  schedule: /schedule/ || fa fa-calendar

6.6 自定义 404 页面

1
hexo new page 404

在 Hexo 配置文件中确保：

1
relative_link: false

能否跳转到 404 页面取决于托管服务或 Web 服务器配置（如 Nginx 需在 nginx.conf 中配置）。

腾讯公益 404

编辑 source/404/index.md：

1
2
3
4
5
6
7
8
9
---
title: '404'
date: 2014-12-22 12:39:04
comments: false
---

<script src="//qzonestyle.gtimg.cn/qzone/hybrid/app/404/search_children.js"
        charset="utf-8" homePageUrl="/" homePageName="Back to home">
</script>
1
2
menu:
  commonweal: /404/ || fa fa-heartbeat

第七章 杂项主题设置

7.1 预连接

1
2
# 预连接字体和插件 CDN [默认: false]
preconnect: false

7.2 文本对齐

1
2
3
4
text_align:
  # 可选值：start | end | left | right | center | justify | justify-all | match-parent
  desktop: justify  # [默认]
  mobile: justify   # [默认]

7.3 移动端适配

1
2
# 减少窄屏设备上的内边距/外边距 [默认: false]
mobile_layout_economy: false

7.4 浏览器主题色

1
2
3
theme_color:
  light: "#222"  # [默认]
  dark: "#222"   # [默认]

7.5 滚动条

1
2
3
4
body_scrollbar:
  # 滚动条覆盖在内容上方 [默认: false]
  overlay: false
  # 注意：stable 选项自 v8.29.0 起已废弃

7.6 代码块样式

需先在 Hexo 配置文件中启用 highlight 或 prism。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
codeblock:
  # Highlight.js 主题
  theme:
    light: default           # [默认]
    dark: stackoverflow-dark # [默认]
  # Prism 主题
  prism:
    light: prism      # [默认]
    dark: prism-dark  # [默认]

  # 复制按钮
  copy_button:
    enable: false     # [默认]
    style:            # 可选：default | flat | mac

  # 代码折叠
  fold:
    enable: false     # [默认]
    height: 500       # [默认] 折叠高度（px）

  # 显示语言名称 [默认: false]
  language: false

所有可用高亮主题预览：https://theme-next.js.org/highlight/ Prism 额外主题需安装：npm install prism-themes

7.7 返回顶部

1
2
3
4
back2top:
  enable: true          # [默认]
  sidebar: false        # [默认] 放在侧边栏中
  scrollpercent: false  # [默认] 显示滚动百分比

7.8 阅读进度条

1
2
3
4
5
6
7
reading_progress:
  enable: false   # [默认]
  start_at: left  # [默认] 可选：left | right
  position: top   # [默认] 可选：top | bottom
  reversed: false
  color: "#37c6c0"  # [默认]
  height: 3px       # [默认]

7.9 书签

1
2
3
4
bookmark:
  enable: false   # [默认]
  color: "#222"   # [默认]
  save: auto      # [默认] auto（关闭页面或点击图标保存）| manual（仅点击保存）

7.10 GitHub 角标

1
2
3
github_banner:
  enable: false   # [默认]
  permalink: https://github.com/yourname

7.11 字体自定义

NexT 提供 5 类字体设置：全局字体、标题字体、标题（h1-h6）字体、正文字体、代码字体。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
font:
  enable: false   # [默认]
  # 字体库 CDN 地址，默认 Google Fonts
  host:

  global:
    external: true
    family: Lato   # [默认]
    size:          # 单位 em，默认 1（16px）

  title:
    external: true
    family:
    size:

  headings:
    external: true
    family:
    size:

  posts:
    external: true
    family:

  codes:
    external: true
    family:

可指定多个字体族（中英文混排时有用）：

1
2
3
4
5
font:
  title:
    external: true
    family: Roboto Slab, Noto Serif SC
    size:

external: true 表示从 CDN 加载字体；设为 false 则使用系统已安装字体。 非代码字体回退："PingFang SC", "Microsoft YaHei", sans-serif 代码字体回退：consolas, Menlo, "PingFang SC", "Microsoft YaHei", monospace 设置过多字体会拖慢页面加载速度。

如需更深度自定义，可创建 source/_data/variables.styl：

1
2
3
4
5
$font-family-headings = Georgia, sans
$font-family-base = "Microsoft YaHei", Verdana, sans-serif
$code-font-family = "Input Mono", "PT Mono", Consolas, Monaco, Menlo, monospace
$font-size-base = 16px
$table-font-size = 13px

然后在 NexT 配置中取消注释：

1
2
custom_file_path:
  variable: source/_data/variables.styl

第八章 SEO 设置

8.1 基础 SEO

在 Hexo 配置文件中正确设置 url：

1
url: http://example.com

在 NexT 配置中：

1
2
# 首页标题附加 subtitle [默认: false]
index_with_subtitle: false

8.2 ExtURL（外链加密）

将外部链接的 <a> 标签替换为 <span>，使用 BASE64 加密解密，防止搜索引擎追踪外链权重。

1
2
exturl: false       # [默认]
exturl_icon: true   # [默认] 显示外链图标

启用后需执行：

1
hexo clean

8.3 站长工具验证

1
2
3
4
google_site_verification:   # Google
bing_site_verification:     # Bing
yandex_site_verification:   # Yandex
baidu_site_verification:    # 百度

在各站长平台选择「HTML 标签」验证方式，复制 content 值填入。

第九章 国际化

9.1 选择语言

在 Hexo 配置文件中：

1
language: zh-CN

NexT 支持 20+ 种语言，常用代码：

语言 代码
简体中文 zh-CN
繁体中文 zh-TW
香港繁体 zh-HK
英语 en
日语 ja
韩语 ko
法语 fr
德语 de
俄语 ru
西班牙语 es
阿拉伯语 ar
葡萄牙语 pt / pt-BR

9.2 多语言切换器

1
2
3
4
# Hexo 配置文件
language:
  - zh-CN
  - en
1
2
# NexT 配置文件
language_switcher: true

9.3 覆盖默认翻译

创建 source/_data/languages.yml：

1
2
3
4
5
6
7
zh-CN:
  post:
    copyright:
      author: 本文博主
en:
  menu:
    schedule: Calendar

第十章 标签插件

以下标签插件仅在 NexT 主题中可用，切换到其他 Hexo 主题可能导致渲染错误。

10.1 居中引用

1
{% centerquote %}内容{% endcenterquote %}

或简写： 

1
{% cq %}内容{% endcq %}

10.2 视频

1
{% video url %}

示例： 

1
2
{% video https://example.com/sample.mp4 %}
{% video /path/to/your/video.mp4 %}

10.3 按钮

1
{% button url, text, icon [class], [title] %}

或简写： 

1
{% btn url, text, icon [class], [title] %}

参数： - url：链接地址（绝对或相对路径） - text：按钮文字（无图标时必填） - icon：Font Awesome 图标名（无文字时必填） - [class]：可选，图标尺寸类：fa-fw | fa-lg | fa-2x | fa-3x | fa-4x | fa-5x - [title]：可选，鼠标悬停提示

示例： 

1
2
3
4
{% btn #, Text %}
{% btn #, Text & Title,, Title %}
{% btn #,, home fa-5x %}
{% btn https://github.com, GitHub, fab fa-github fa-fw fa-lg, GitHub %}

10.4 Caniuse

1
{% caniuse feature @ [periods] %}

或简写： 

1
{% can feature @ [periods] %}

  • feature：在 caniuse.com 搜索功能，点击标题左侧 # 号获取唯一名称
  • [periods]：可选，浏览器版本范围：past_1 ~ past_5、current、future_1 ~ future_3

示例： 

1
2
3
{% caniuse fetch %}
{% caniuse sharedarraybuffer @ current %}
{% caniuse loading-lazy-attr @ future_3,future_2,future_1 %}

10.5 组图

1
2
3
{% grouppicture [number]-[layout] %}
![](/images/image1.png)
{% endgrouppicture %}

或简写： 

1
2
3
{% gp [number]-[layout] %}
...
{% endgp %}

  • [number]：图片总数
  • [layout]：布局编号（2~10 张图片各有多种布局，参见官方文档布局图）

示例： 

1
2
3
4
5
{% grouppicture 3-3 %}
![](/images/next.png)
![](/images/next.png)
![](/images/next.png)
{% endgrouppicture %}

建议配合 Fancybox 使用；组图内请使用绝对路径。

10.6 标签

1
{% label [class]@text %}
  • [class]：可选，default | primary | success | info | warning | danger
  • @ 前后空格可有可无

示例： 

1
Lorem {% label @ipsum %} {% label primary@dolor sit %} amet

10.7 链接网格

1
2
3
{% linkgrid [image] [delimiter] [comment] %}
标题 | 链接 | 描述 | 图片
{% endlinkgrid %}

或简写： 

1
2
3
{% lg [image] [delimiter] [comment] %}
...
{% endlg %}

  • [image]：默认图片 URL
  • [delimiter]：分隔符，默认 |
  • [comment]：注释符，默认 %

示例： 

1
2
3
4
{% linkgrid %}
Theme NexT | https://theme-next.js.org/ | Stay Simple. Stay NexT. | /images/apple-touch-icon-next.png
% 这行被注释
{% endlinkgrid %}

10.8 Mermaid 图表

1
2
3
4
5
6
mermaid:
  enable: false   # [默认]
  # 可选主题：default | dark | forest | neutral
  theme:
    light: default   # [默认]
    dark: dark       # [默认]

需在 Hexo 配置文件中排除 mermaid 语言的高亮：

1
2
3
highlight:
  exclude_languages:
    - mermaid

用法： 

1
2
3
4
5
6
{% mermaid graph TD %}
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]
{% endmermaid %}

也可使用代码块： 

1
2
3
4
```mermaid
graph TD
A[Hard] -->|Text| B(Round)
```

支持流程图、时序图、甘特图、类图、状态图、饼图等。

10.9 Note 提示块

1
2
3
4
5
6
note:
  # 样式：simple [默认] | modern | flat | disabled
  style: simple
  icons: false   # [默认]
  # 背景色偏移量（modern: -12|12; flat: -18|6）[默认: 0]
  light_bg_offset: 0

用法： 

1
2
3
{% note [class] [no-icon] [summary] %}
内容
{% endnote %}

  • [class]：可选，default | primary | success | info | warning | danger
  • [no-icon]：可选，禁用图标
  • [summary]：可选，摘要（可折叠）

示例： 

1
2
3
4
5
6
7
8
9
10
11
12
{% note warning %}
#### 警告标题
**注意**内容
{% endnote %}

{% note info no-icon %}
无图标提示
{% endnote %}

{% note primary This is a summary %}
可折叠内容
{% endnote %}

10.10 PDF

1
2
3
pdf:
  enable: false   # [默认]
  height: 500px   # [默认]

用法： 

1
{% pdf url [height] %}

示例： 

1
2
{% pdf https://example.com/sample.pdf %}
{% pdf /path/to/your/file.pdf 600px %}

跨域加载 PDF 需正确设置 CORS。使用 PDF 标签需安装 pdf.js 依赖。

10.11 选项卡

1
2
3
4
5
tabs:
  sticky: false   # [默认] 长内容时标签栏吸顶
  transition:
    tabs: false   # [默认]
    labels: true  # [默认]

用法： 

1
2
3
4
5
{% tabs Unique name, [index] %}
<!-- tab [Tab caption] [@icon] -->
内容
<!-- endtab -->
{% endtabs %}

  • Unique name：唯一名称（同一页面内不可重复），用于生成锚点
  • [index]：默认激活的标签序号，-1 表示不激活（类似剧透）
  • [Tab caption]：标签标题，不填则使用唯一名称+序号
  • [@icon]：Font Awesome 图标

示例： 

1
2
3
4
5
6
7
8
{% tabs 我的选项卡, 2 %}
<!-- tab 方案一 -->
内容一
<!-- endtab -->
<!-- tab 方案二@home -->
内容二
<!-- endtab -->
{% endtabs %}

支持嵌套子选项卡（{% subtabs %}）。

10.12 WaveDrom 时序图

1
2
wavedrom:
  enable: false   # [默认]

用法： 

1
2
3
4
5
6
7
{% wavedrom %}
{ signal : [
  { name: "clk", wave: "p......" },
  { name: "bus", wave: "x.34.5x", data: "head body tail" },
  { name: "wire", wave: "0.1..0." },
]}
{% endwavedrom %}

第十一章 第三方服务

11.1 数学公式

在主题配置文件 _config.next.yml 进行相应设置： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
math:
  # false [默认]：仅在 front-matter 中设置 mathjax: true 的页面加载渲染引擎
  # true：每页都加载
  every_page: false

  mathjax:
    enable: false   # [默认]
    # 公式编号：none [默认] | ams | all
    tags: none
    # 公式溢出处理（v8.29.0+）：overflow | scroll [默认] | scale | truncate | linebreak
    display_overflow: scroll

  katex:
    enable: false   # [默认]
    copy_tex: false # [默认] 复制时保留 LaTeX 源码

MathJax 渲染器

MathJax 是开源浏览器端 LaTeX 公式渲染 JS 库，在 Hexo‑NexT 中搭配 hexo‑renderer‑pandoc 与系统 Pandoc 可实现 equation、align 等公式环境自动编号，LaTeX 语法兼容性强，还支持公式引用跳转与复制源码，非常适合数学类博客。

安装 pandoc（文档转换器）

NexT 使用 MathJax ，系统需要预先安装 pandoc ，Pandoc 是一款开源、跨平台的命令行文档转换工具。推荐从官网下载，若下载失败，在不同时间段反复尝试。

官网地址：https://pandoc.org/installing.html

安装 MathJax 插件（支持 MathJax 4）

推荐使用 hexo-renderer-pandoc： 

1
2
npm un hexo-renderer-marked
npm i hexo-renderer-pandoc

若 hexo‑renderer‑pandoc 使用 v5.0.0+ 版本，需在 Hexo 配置文件 _config.yml 中手动添加如下配置： 

1
2
3
pandoc:
 args:
   - --mathjax

按需渲染时，在文章 front-matter 中设置： 

1
mathjax: true

KaTeX 渲染器

KaTeX 是 Khan Academy 开发的开源前端数学公式渲染库，可在浏览器渲染 LaTeX 公式，无需 Pandoc、部署简单且渲染速度快，支持复制 TeX 源码，但不支持 AMS 公式自动编号，部分复杂 LaTeX 语法兼容性不及 MathJax。

1
2
npm un hexo-renderer-marked
npm i hexo-renderer-markdown-it-plus

或使用 hexo-renderer-markdown-it（需额外安装 markdown-it-katex）。

公式编号与引用

设置 math.mathjax.tags: ams，使用 equation 环境包裹公式，通过 \label{} 和 \eqref{} 引用：

1
2
3
4
5
$$\begin{equation} \label{eq1}
e=mc^2
\end{equation}$$

如公式 $\eqref{eq1}$ 所示...

安装/卸载渲染器后需执行 hexo clean。无需安装 hexo-math 等额外插件，会与 NexT 内置引擎冲突。

11.2 评论系统

多评论系统共存

1
2
3
4
5
6
7
8
9
comments:
  style: tabs    # [默认] 可选：tabs | buttons
  active:        # 默认显示的评论系统：disqus | disqusjs | livere | gitalk | utterances | isso
  storage: true  # [默认] 记住访问者选择的评论系统
  lazyload: false # [默认] 懒加载评论
  nav:
    #disqus:
    #  text: Load Disqus
    #  order: -1

在指定页面禁用评论

在页面 front-matter 中添加：

1
comments: false

Disqus

1
2
3
4
disqus:
  enable: false   # [默认]
  shortname:      # Disqus shortname
  count: true     # [默认] 显示评论数

建议在 Disqus 设置中关闭 Affiliate links，避免插入推广链接。

DisqusJS（基于 Disqus API）

1
2
3
4
5
disqusjs:
  enable: false   # [默认]
  api:            # Disqus API 反代地址（直连时留空）
  apikey:         # Disqus API Key
  shortname:      # Disqus shortname

LiveRe

1
livere_uid:  # 你的 UID

Gitalk

1
2
3
4
5
6
7
8
9
10
11
gitalk:
  enable: false
  github_id:              # GitHub 用户名
  repo:                   # 存储 Issue 的仓库名
  client_id:              # OAuth Application Client ID
  client_secret:          # OAuth Application Client Secret
  admin_user:             # 管理员用户名
  distraction_free_mode: true  # [默认]
  proxy: https://cors-anywhere.azm.workers.dev/https://github.com/login/oauth/access_token
  language:               # 强制语言：en | es-ES | fr | ru | zh-CN | zh-TW
  body:                   # 自定义 Issue 内容

若 GitHub 用户名纯数字，需加引号：github_id: "12345678"。 Gitalk 依赖页面路径的 md5 值，永久链接变更后评论将无法加载。

Utterances

1
2
3
4
5
utterances:
  enable: false
  repo: user-name/repo-name
  issue_term: pathname  # [默认] 可选：pathname | url | title | og:title
  theme: github-light   # [默认] 可选：github-light | github-dark | preferred-color-scheme 等

Isso

需自行搭建 Isso 服务器：

1
isso:  # data-isso 值

11.3 统计与分析

NexT 仅在页面域名与 Hexo 配置中的 url 匹配时发送统计数据，防止本地调试污染数据。

Google Analytics

1
2
3
4
google_analytics:
  tracking_id:        # UA-XXXXXXXX-X 或 GA4 ID
  only_pageview: false  # [默认] true 时仅发送 pageview，减少外部脚本
  measure_protocol_api_secret:  # only_pageview 模式所需

百度统计

1
baidu_analytics:  # 你的 ID

Cloudflare Web Analytics

1
cloudflare_analytics:

Microsoft Clarity

1
clarity_analytics:  # <project_id>

Matomo（自建）

1
2
3
4
matomo:
  enable: false
  server_url:   # https://www.example.com/
  site_id:      # 站点 ID

Umami（自建）

1
2
3
4
5
umami:
  enable: false
  script_url:   # https://umami.example.com/script.js
  website_id:   # 网站 ID
  host_url:     # Umami 站点 URL

Plausible（自建）

1
2
3
4
plausible:
  enable: false
  script_url:   # https://plausible.io/js/script.js
  site_domain:  # www.example.com

Firebase 访客计数（v8.29.0+ 使用 REST API）

1
2
3
4
firestore:
  enable: false
  collection: articles  # [默认] 必填
  projectId:            # 必填（v8.29.0 起不再需要 apiKey）

需在 Firebase 中创建 Firestore 数据库并配置安全规则。仅统计独立访客（UV），刷新不重复计数。

不蒜子计数（中国）

1
2
3
4
5
6
7
8
busuanzi_count:
  enable: false          # [默认] 全局开关
  total_visitors: true   # [默认] 站点 UV（页脚）
  total_visitors_icon: fa fa-user
  total_views: true      # [默认] 站点 PV（页脚）
  total_views_icon: fa fa-eye
  post_views: true       # [默认] 文章 PV（文章元信息）
  post_views_icon: far fa-eye

若 total_visitors、total_views、post_views 全为 false，不蒜子仅计数不显示。

11.4 文章分享

1
2
3
4
5
6
7
8
addtoany:
  enable: false   # [默认]
  buttons:
    - facebook
    - twitter
    #- telegram
    #- wechat
    #- qzone

11.5 搜索服务

需安装 Hexo 索引插件（hexo-algolia 或 hexo-algoliasearch），在 Algolia 创建 Index 并获取 API 密钥。

1
2
3
4
algolia_search:
  enable: false   # [默认]
  hits:
    per_page: 10  # [默认]

使用 Algolia 时需关闭本地搜索。

本地搜索（推荐）

1
npm install hexo-generator-searchdb

Hexo 配置文件：

1
2
3
4
5
search:
  path: search.xml
  field: post
  content: true
  format: html

NexT 配置文件：

1
2
3
4
5
local_search:
  enable: false       # [默认]
  top_n_per_article: 1  # [默认] 每篇文章显示前 n 条结果，-1 显示全部
  unescape: false      # [默认] 反转义 HTML
  preload: false       # [默认] 页面加载时预加载搜索数据

11.6 在线客服

Chatra

1
2
3
4
chatra:
  enable: false
  async: true   # [默认]
  id:           # ChatraID

Tidio

1
2
3
tidio:
  enable: false
  key:          # Public Key

Knocket（腾讯 RTC，免费）

1
2
3
4
knocket:
  enable: false
  async: true   # [默认]
  identifier:   # 从 https://trtc.io/solutions/knocket 获取

启用任一客服后，可在侧边栏显示聊天按钮：

1
2
3
chat:
  enable: false   # [默认]
  icon: fa fa-comment  # [默认] 设为 false 可禁用图标

11.7 外部库

PJAX

1
pjax: false   # [默认]

使用 PJAX 时，文章中的图片请使用绝对路径或 asset_img 标签，否则刷新时可能加载失败。

Fancybox（图片灯箱）

1
fancybox: false   # [默认]

Medium Zoom（图片缩放）

1
mediumzoom: false   # [默认]

不可同时启用 Fancybox 和 MediumZoom。

Pangu（中英文间距）

1
pangu: false   # [默认]

Quicklink（链接预取）

1
2
3
4
5
6
7
quicklink:
  enable: false   # [默认]
  home: false     # [默认] 首页启用（独立于 enable）
  archive: false  # [默认] 归档页启用（独立于 enable）
  delay: true     # [默认] load 事件后初始化
  timeout: 3000   # [默认] 预取超时（毫秒）
  priority: true  # [默认] 优先使用 fetch() API

动画效果

1
2
3
4
5
6
7
8
9
10
11
motion:
  enable: true    # [默认]
  async: false    # [默认]
  duration: 200   # [默认]
  transition:
    menu_item: fadeInDown    # [默认]
    post_block: fadeIn       # [默认]
    post_header: fadeInDown  # [默认]
    post_body: fadeInDown    # [默认]
    coll_header: fadeInLeft  # [默认]
    sidebar: fadeInUp        # [默认] 仅 Pisces | Gemini

所有过渡效果变体预览：https://theme-next.js.org/animate/ v8.29.0 起移除 Anime.js，改用原生 API 实现滚动动画。

进度条

1
2
3
4
5
6
7
8
pace:
  enable: false   # [默认]
  # 可选颜色：black | blue [默认] | green | orange | pink | purple | red | silver | white | yellow
  color: blue
  # 可选主题：minimal [默认] | big-counter | bounce | barber-shop | center-atom |
  #          center-circle | center-radar | center-simple | corner-indicator |
  #          fill-left | flash | loading-bar | mac-osx | material
  theme: minimal

Canvas 彩带

1
2
3
4
5
canvas_ribbon:
  enable: false   # [默认]
  size: 300       # [默认] 彩带宽度
  alpha: 0.6      # [默认] 透明度
  zIndex: -1      # [默认] 显示层级

第十二章 高级设置

以下设置若配置错误可能导致异常，请在理解其作用后修改。

12.1 CDN 与 Vendors

1
2
3
4
5
6
7
vendors:
  # 内部脚本 CDN：local [默认] | jsdelivr | unpkg | cdnjs | custom
  internal: local
  # 第三方插件 CDN：cdnjs [默认] | local | jsdelivr | unpkg | custom
  plugins: cdnjs
  # 自定义 CDN URL 模板
  custom_cdn_url:
  • internal: local：内部脚本从站点本身加载（默认）。免费托管（GitHub/GitLab Pages）建议使用 CDN。
  • plugins: cdnjs：第三方插件默认从 CDNJS 加载。中国大陆部分地区被墙，建议国内用户改用 jsdelivr。
  • plugins: local：从本地加载，需安装 @next-theme/plugins 包，适合内网部署。

自定义 CDN

1
2
3
4
5
6
7
vendors:
  internal: custom
  plugins: custom
  # jsDelivr 镜像
  custom_cdn_url: https://fastly.jsdelivr.net/npm/${npm_name}@${version}/${minified}
  # CDNJS 镜像
  #custom_cdn_url: https://cdnjs.cloudflare.com/ajax/libs/${cdnjs_name}/${version}/${cdnjs_file}

单独指定库的 CDN

1
2
vendors:
  anime: //fastly.jsdelivr.net/gh/juliangarnier/anime@latest/lib/anime.min.js

库名与 _vendors.yml 中一致，建议使用相同版本以避免问题。

12.2 静态资源路径

1
2
3
4
# 静态资源目录（仅当 vendors.internal 为 local 时 js 选项有效）
css: css       # [默认]
js: js         # [默认]
images: images # [默认]

12.3 自定义文件

在 source/_data/ 目录下创建自定义文件，然后在 NexT 配置中取消注释对应项：

1
2
3
4
5
6
7
8
9
10
11
12
custom_file_path:
  #head: source/_data/head.njk
  #header: source/_data/header.njk
  #sidebar: source/_data/sidebar.njk
  #postMeta: source/_data/post-meta.njk
  #postBodyStart: source/_data/post-body-start.njk
  #postBodyEnd: source/_data/post-body-end.njk
  #footer: source/_data/footer.njk
  #bodyEnd: source/_data/body-end.njk
  #variable: source/_data/variables.styl
  #mixin: source/_data/mixins.styl
  #style: source/_data/styles.styl

示例：Live2D 看板娘

source/_data/head.njk：

1
<script src="https://fastly.jsdelivr.net/gh/stevenjoezhang/live2d-widget@latest/autoload.js"></script>
1
2
custom_file_path:
  head: source/_data/head.njk

示例：修改内容宽度

source/_data/variables.styl（Muse/Mist）：

1
2
3
$content-desktop = 90%
$content-desktop-large = 90%
$content-desktop-largest = 90%

默认值： - Muse/Mist：700px / 800px / 900px - Pisces/Gemini：calc(100% - ...) / 1160px / 73%

示例：移动端隐藏侧边栏

source/_data/styles.styl：

1
2
3
4
5
+tablet-mobile() {
  .sidebar-toggle, .sidebar {
    display: none;
  }
}

示例：隐藏归档页标题

source/_data/styles.styl：

1
2
3
.archive .collection-title {
  display: none !important;
}

12.4 注入点（Injects）

通过 Hexo 过滤器向任意注入点添加自定义内容：

1
2
3
4
5
6
7
8
9
10
11
12
hexo.extend.filter.register('theme_inject', function(injects) {
  // 注入原始 HTML 到 bodyEnd
  injects.bodyEnd.raw('load-custom-js', '<script src="js-path-or-cdn.js"></script>', {}, {cache: true});

  // 注入模板文件到 sidebar
  injects.sidebar.file('my-widget', 'source/_data/my-widget.njk', {
    foods: ['apple', 'orange']
  });

  // 注入自定义样式
  injects.style.push('source/_data/big-header.styl');
});

可用的视图注入点：head、header、sidebar、postMeta、postBodyStart、postBodyEnd、footer、bodyEnd、comment

可用的样式注入点：variable、mixin、style

custom_file_path 占用了 custom 名称，使用 Injects 时请勿使用该名称。

12.5 Front-matter 变量

NexT 扩展了以下 front-matter 变量：

变量 类型 说明 默认值
author string 文章版权作者 Hexo 配置中的 author
post_link string 转载文章原文链接 无
copyright_reprint bool 标记为转载文章（需同时设置 author 和 post_link） false
link string 标题点击跳转到外部链接 无
description string 文章摘要 无
direction string 文字方向，可选 rtl 无
header boolean 是否显示文章头部 true
mathjax boolean 是否加载 MathJax 取决于 math.every_page
sidebar boolean 是否显示侧边栏 取决于 sidebar.display
copyright boolean 是否显示版权声明 true
sticky number 置顶文章（需 hexo-generator-index） 0
quicklink object Quicklink 设置 继承 NexT 配置
reward_settings object 打赏设置 继承 NexT 配置
toc object 目录设置 继承 NexT 配置
noindex boolean 添加 noindex 禁止搜索引擎索引 false
comments boolean 是否显示评论 true
photos array 相册文章图片 无

示例：

1
2
3
4
5
6
7
toc:
  enable: true
  number: false
  max_depth: 3
reward_settings:
  enable: true
  comment: Buy me a coffee

第十三章 部署

13.1 本地部署

1
2
hexo clean && hexo s    # 本地预览
hexo g -d               # 生成并部署

13.2 持续集成（CI）

GitHub Pages

  1. 仓库 Settings → Pages → Source 选择 GitHub Actions
  2. 创建 .github/workflows/hexo.yaml：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
name: Deploy Hexo site to Pages

on:
  push:
    branches: [$default-branch]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

defaults:
  run:
    shell: bash

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: recursive
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v3
      - name: Use Node.js 18.x
        uses: actions/setup-node@v3
        with:
          node-version: "18"
      - name: Install Dependencies
        run: npm install
      - name: Build with Hexo
        run: npx hexo g
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deploy.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Cloudflare Pages

构建设置： - Build command: npx hexo g - Build output directory: /public

GitLab CI

创建 .gitlab-ci.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
image: node:lts

before_script:
  - "git ls-files -z | while read -d '' path; do touch -d \"$(git log -1 --format=\"@%ct\" \"$path\")\" \"$path\"; done"

pages:
  stage: build
  cache:
    paths:
    - node_modules/
  script:
  - npm install
  - npx hexo deploy
  artifacts:
    paths:
    - public
  only:
  - master

第十四章 升级指南

14.1 版本历史

年份 版本 仓库
2014~2017 v5 https://github.com/iissnan/hexo-theme-next
2018~2019 v6~v7 https://github.com/theme-next/hexo-theme-next
2020 至今 v8 https://github.com/next-theme/hexo-theme-next

14.2 npm 升级

1
2
cd hexo-site
npm install hexo-theme-next@latest

node_modules 中的本地修改会丢失，请使用自定义文件功能代替直接修改主题文件。

14.3 Git 升级

1
2
3
cd hexo-site
cd themes/next
git pull origin master

若遇合并冲突，可使用 Commit、Stash 或 Reset 处理本地修改。

14.4 近期重要变更

v8.29.0（2026-08-05）

  • 破坏性变更：移除 Anime.js，滚动动画改用原生 API
  • 新增 MathJax display_overflow 选项（overflow | scroll | scale | truncate | linebreak）
  • Firestore 改用 REST API，不再需要 apiKey，仅需 projectId
  • 废弃 body_scrollbar.stable 选项
  • 废弃 lazyload 选项（lozad.js 图片懒加载已移除）
  • 支持 MathJax 4

v8.28.0（2026-07-01）

  • 新增 Knocket 在线客服（腾讯 RTC，免费）

v8.27.0（2026-01-07）

  • 暗色模式默认启用（darkmode: true）
  • Gitalk 新增 body 选项自定义 Issue 内容

14.5 从旧版本升级到 v8

  1. 备份旧配置文件（_config.yml 或 next.yml）、自定义 CSS/布局文件
  2. 将旧 themes/next 目录重命名为 themes/next-old
  3. 按安装步骤安装 v8
  4. 执行 hexo clean && hexo s 验证
  5. 若报错，升级 Hexo 及所有插件（npm outdated 查看可升级项）

破坏性变更： - v6.0.3 起，zh-Hans 更名为 zh-CN，需修改 Hexo 配置中的 language - v8.0.0 起，next/source/lib 下的库移至 @next-theme/plugins，第三方库需通过 CDN 或 plugins: local 加载

第十五章 故障排除

15.1 快速调试步骤

  1. 执行 hexo clean，清除浏览器缓存和 CDN 缓存
  2. 禁用浏览器插件或换浏览器/设备测试
  3. 切换到其他主题（如默认 landscape）确认是否为 NexT 问题
  4. 升级 NexT 到最新版本
  5. 升级 Hexo 及所有插件（可使用 npm-check 工具）
  6. 升级或降级 Node.js 到最新 LTS 版本
  7. 卸载非必要插件，或删除 node_modules 后执行 npm install --force

15.2 YAML 缩进

所有 Hexo/NexT 配置文件使用 2 空格缩进，不允许 Tab。

15.3 skip_render

在 Hexo 配置文件中跳过特定文件的渲染：

1
2
3
skip_render:
  - robots.txt
  - CNAME

15.4 暗色模式不生效

三个前提条件： 1. NexT 配置中 darkmode 已启用（v8.27.0+ 默认启用） 2. 浏览器支持 prefers-color-scheme（2020 年后的浏览器） 3. 操作系统设置中启用了暗色模式

15.5 TOC 目录问题

  • 不要跳级使用标题（如 ### 后直接跟 #####）
  • 若使用 hexo-renderer-markdown-it，建议安装 markdown-it-named-headings： 
    1
    npm install markdown-it-named-headings

15.6 Favicon 不生效

将 favicon 放在站点 source/ 目录下，清除浏览器缓存后直接访问 http(s)://your-domain.com/favicon.ico 验证。若站点在子目录，设置 favicon: favicon.ico。

15.7 提交 Issue

若以上步骤无法解决问题，提交 Issue 时请提供： - 问题是否可稳定复现及复现条件 - Node、Hexo、NexT 版本（node -v、hexo version） - 已安装包列表（npm ls --depth 0）

附录 A 完整配置速查

以下为 NexT v8.29.0 默认配置文件的完整结构，# 开头为注释或默认禁用项：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
# ============================================================
# 主题核心配置
# ============================================================
cache:
  enable: true
minify: false

custom_file_path:
  #head: source/_data/head.njk
  #header: source/_data/header.njk
  #sidebar: source/_data/sidebar.njk
  #postMeta: source/_data/post-meta.njk
  #postBodyStart: source/_data/post-body-start.njk
  #postBodyEnd: source/_data/post-body-end.njk
  #footer: source/_data/footer.njk
  #bodyEnd: source/_data/body-end.njk
  #variable: source/_data/variables.styl
  #mixin: source/_data/mixins.styl
  #style: source/_data/styles.styl

# ============================================================
# Scheme 与暗色模式
# ============================================================
scheme: Muse
#scheme: Mist
#scheme: Pisces
#scheme: Gemini
darkmode: true
lightdark:
  enable: false
  check_supports: true

# ============================================================
# 站点信息
# ============================================================
favicon:
  small: /images/favicon-16x16-next.png
  medium: /images/favicon-32x32-next.png
  apple_touch_icon: /images/apple-touch-icon-next.png
  safari_pinned_tab: /images/logo.svg
  #android_manifest: /manifest.json
custom_logo:
creative_commons:
  license: by-nc-sa
  size: small
  sidebar: false
  post: false
  language:
open_graph:
  enable: true
  options:
    #twitter_card:
    #twitter_id:
    #twitter_site:
    #twitter_image:
    #fb_admins:
    #fb_app_id:

# ============================================================
# 菜单
# ============================================================
menu:
  #home: / || fa fa-home
  #about: /about/ || fa fa-user
  #tags: /tags/ || fa fa-tags
  #categories: /categories/ || fa fa-th
  #archives: /archives/ || fa fa-archive
  #schedule: /schedule/ || fa fa-calendar
  #sitemap: /sitemap.xml || fa fa-sitemap
  #commonweal: /404/ || fa fa-heartbeat
menu_settings:
  icons: true
  badges: false

# ============================================================
# 侧边栏
# ============================================================
sidebar:
  position: left
  width_expanded: 320
  width_dual_column: 240
  display: post
  padding: 18
  offset: 12
avatar:
  url:
  rounded: false
  rotated: false
site_state: true
social:
  #GitHub: ...
social_icons:
  enable: true
  icons_only: false
  transition: false
links_settings:
  icon: fa fa-globe
  layout: block
links:
toc:
  enable: true
  number: true
  wrap: false
  expand_all: false
  max_depth: 6

# ============================================================
# 页脚
# ============================================================
language_switcher: false
footer:
  #since:
  icon:
    name: fa fa-heart
    animated: false
    color: "#ff0000"
  copyright:
  powered: true
  beian:
    enable: false
    icp:
    gongan_id:
    gongan_num:
    gongan_icon_url:

# ============================================================
# 文章
# ============================================================
excerpt_description: true
read_more_btn: true
post_meta:
  item_text: true
  created_at: true
  updated_at:
    enable: true
    another_day: true
  categories: true
symbols_count_time:
  separated_meta: true
  item_text_total: false
tag_icon: false
reward_settings:
  enable: false
  animation: false
reward:
  #wechatpay:
  #alipay:
  #paypal:
  #bitcoin:
follow_me:
  #Twitter: ...
related_posts:
  enable: false
  icon: fa fa-signs-post
post_edit:
  enable: false
  url: https://github.com/user-name/repo-name/tree/branch-name/subdirectory-name/
post_navigation: left

# ============================================================
# 自定义页面
# ============================================================
tagcloud:
  min: 12
  max: 30
  amount: 200
  orderby: name
  order: 1
calendar:
  calendar_id: <required>
  api_key: <required>
  orderBy: startTime
  showLocation: false
  offsetMax: 72
  offsetMin: 4
  showDeleted: false
  singleEvents: true
  maxResults: 250

# ============================================================
# 杂项
# ============================================================
preconnect: false
text_align:
  desktop: justify
  mobile: justify
mobile_layout_economy: false
theme_color:
  light: "#222"
  dark: "#222"
body_scrollbar:
  overlay: false
codeblock:
  theme:
    light: default
    dark: stackoverflow-dark
  prism:
    light: prism
    dark: prism-dark
  copy_button:
    enable: false
    style:
  fold:
    enable: false
    height: 500
  language: false
back2top:
  enable: true
  sidebar: false
  scrollpercent: false
reading_progress:
  enable: false
  start_at: left
  position: top
  reversed: false
  color: "#37c6c0"
  height: 3px
bookmark:
  enable: false
  color: "#222"
  save: auto
github_banner:
  enable: false
  permalink: https://github.com/yourname
font:
  enable: false
  host:
  global:
    external: true
    family: Lato
    size:
  title:
    external: true
    family:
    size:
  headings:
    external: true
    family:
    size:
  posts:
    external: true
    family:
  codes:
    external: true
    family:

# ============================================================
# SEO
# ============================================================
index_with_subtitle: false
exturl: false
exturl_icon: true
google_site_verification:
bing_site_verification:
yandex_site_verification:
baidu_site_verification:

# ============================================================
# 标签插件
# ============================================================
note:
  style: simple
  icons: false
  light_bg_offset: 0
tabs:
  sticky: false
  transition:
    tabs: false
    labels: true
pdf:
  enable: false
  height: 500px
mermaid:
  enable: false
  theme:
    light: default
    dark: dark
wavedrom:
  enable: false

# ============================================================
# 数学公式
# ============================================================
math:
  every_page: false
  mathjax:
    enable: false
    tags: none
    display_overflow: scroll
  katex:
    enable: false
    copy_tex: false

# ============================================================
# 外部库
# ============================================================
pjax: false
fancybox: false
mediumzoom: false
pangu: false
quicklink:
  enable: false
  home: false
  archive: false
  delay: true
  timeout: 3000
  priority: true
motion:
  enable: true
  async: false
  duration: 200
  transition:
    menu_item: fadeInDown
    post_block: fadeIn
    post_header: fadeInDown
    post_body: fadeInDown
    coll_header: fadeInLeft
    sidebar: fadeInUp
pace:
  enable: false
  color: blue
  theme: minimal
canvas_ribbon:
  enable: false
  size: 300
  alpha: 0.6
  zIndex: -1

# ============================================================
# 评论
# ============================================================
comments:
  style: tabs
  active:
  storage: true
  lazyload: false
  nav:
disqus:
  enable: false
  shortname:
  count: true
disqusjs:
  enable: false
  api:
  apikey:
  shortname:
livere_uid:
gitalk:
  enable: false
  github_id:
  repo:
  client_id:
  client_secret:
  admin_user:
  distraction_free_mode: true
  proxy: https://cors-anywhere.azm.workers.dev/https://github.com/login/oauth/access_token
  language:
  body:
utterances:
  enable: false
  repo: user-name/repo-name
  issue_term: pathname
  theme: github-light
isso:

# ============================================================
# 分享
# ============================================================
addtoany:
  enable: false
  buttons:

# ============================================================
# 统计与分析
# ============================================================
google_analytics:
  tracking_id:
  only_pageview: false
  measure_protocol_api_secret:
baidu_analytics:
cloudflare_analytics:
clarity_analytics:
matomo:
  enable: false
  server_url:
  site_id:
umami:
  enable: false
  script_url:
  website_id:
  host_url:
plausible:
  enable: false
  script_url:
  site_domain:
firestore:
  enable: false
  collection: articles
  projectId:
busuanzi_count:
  enable: false
  total_visitors: true
  total_visitors_icon: fa fa-user
  total_views: true
  total_views_icon: fa fa-eye
  post_views: true
  post_views_icon: far fa-eye

# ============================================================
# 搜索
# ============================================================
algolia_search:
  enable: false
  hits:
    per_page: 10
local_search:
  enable: false
  top_n_per_article: 1
  unescape: false
  preload: false

# ============================================================
# 在线客服
# ============================================================
chat:
  enable: false
  icon: fa fa-comment
chatra:
  enable: false
  async: true
  id:
tidio:
  enable: false
  key:
knocket:
  enable: false
  async: true
  identifier:

# ============================================================
# CDN
# ============================================================
vendors:
  internal: local
  plugins: cdnjs
  custom_cdn_url:
css: css
js: js
images: images

附录 B NexT 插件生态

Hexo 官方插件（NexT 文档推荐）

插件 用途
hexo-generator-searchdb 本地搜索数据源
hexo-pangu 中英文间自动加空格（服务端）
hexo-filter-mathjax MathJax 服务端渲染
hexo-word-counter 字数与阅读时长统计
hexo-optimize 性能优化

NexT 专属插件

插件 用途
hexo-next-three Three.js 3D 效果
hexo-next-fireworks 点击烟花效果
hexo-next-exif 照片 EXIF 信息显示
hexo-next-valine Valine 评论系统
hexo-next-giscus Giscus 评论系统

更多插件见 Awesome NexT 列表。

本手册基于 NexT 官方文档（https://theme-next.js.org/docs/）及 v8.29.0 默认配置文件编写。 如遇手册未涵盖的问题，请参考官方文档、GitHub Issues 或加入社区讨论。