NexT 主题配置完全指南

Posted on

NexT 主题配置完全指南

本文基于 Hexo NexT v8+ 版本整理，参考官方文档：https://theme-next.js.org/docs/

一、配置方式

NexT 推荐使用 Alternate Theme Config（主题配置分离），避免升级时被覆盖。

方式一：config.next.yml（推荐）

在 Hexo 根目录创建 _config.next.yml，将主题配置写入其中。

1
2
# 首次安装时，从默认配置复制
cp node_modules/hexo-theme-next/_config.yml _config.next.yml

方式二：写入 Hexo 主配置

在 Hexo 根目录 _config.yml 中，用 theme_config: 包裹所有 NexT 配置项（需保持两空格缩进）。

二、归档、标签、分类

⚠️ 关键结论

不需要手动创建 MD 文件！ 只需在 _config.next.yml 中取消注释菜单项，然后在 Hexo 主配置中启用相应功能，NexT 会自动生成页面。

2.1 启用步骤

Step 1：配置菜单（导航栏显示入口）

在 _config.next.yml 中取消对应行的注释：

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

格式说明：名称: /链接/ || Font Awesome 图标

Step 2：Hexo 自动生成页面

NexT 的标签页和分类页由 Hexo 自动生成，无需手动创建 MD 文件。只需在文章的 front-matter 中使用：

1
2
3
4
5
6
---
title: 我的文章
date: 2024-01-01
categories: 技术
tags: [Hexo, NexT]
---

NexT 会根据文章的 categories 和 tags 自动归类。

Step 3：自定义标签页和分类页（可选）

如果想自定义标签页样式，可在 source/ 下创建页面：

1
2
hexo new page tags    # 创建 source/tags/index.md
hexo new page categories  # 创建 source/categories/index.md

修改 front-matter：

1
2
3
4
5
6
# source/tags/index.md
---
title: 标签
type: tags
comments: false
---

2.3 归档页面

归档页面无需任何 MD 文件。启用菜单中的 archives 后，访问 /archives/ 即可看到按时间聚合的所有文章列表。

三、主题方案（Scheme）

NexT 内置四种方案，切换只需取消注释一行配置：

1
2
3
4
scheme: Muse
# scheme: Mist
# scheme: Pisces
# scheme: Gemini
方案 风格
Muse 经典布局，侧边栏在左侧（默认）
Mist 简洁紧凑，导航栏在顶部
Pisces 双栏布局，侧边栏固定
Gemini 类似 Pisces，宽度更大

四、暗黑模式

1
2
3
4
5
6
7
# 基础暗黑模式（自动跟随系统）
darkmode: true

# 进阶：支持手动切换的明暗切换器
lightdark:
  enable: true
  check_supports: true

开启后，页面会自动适配系统深色/浅色模式，也可在页脚看到切换按钮。

五、侧边栏配置

5.1 位置与宽度

1
2
3
4
5
6
7
8
9
10
sidebar:
  position: left          # 侧边栏位置：left | right
  display: post           # 显示时机：post | always | hide | remove
  padding: 18             # 内边距（像素）
  offset: 12              # 与导航栏的距离（Pisces/Gemini 专属）

  # Muse | Mist：展开宽度
  width_expanded: 320
  # Pisces | Gemini：桌面端宽度
  width_dual_column: 240

5.2 头像

1
2
3
4
avatar:
  url: /images/avatar.gif
  rounded: true      # 圆形头像
  rotated: false    # 悬停旋转

5.3 站点状态（文章/分类/标签数量）

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

5.4 博客链接

1
2
3
4
5
6
7
links_settings:
  icon: fa fa-globe
  layout: block     # block 行级 | inline 行内

links:
  GitHub: https://github.com/yourname
  博客: https://example.com

六、导航菜单与图标

1
2
3
menu_settings:
  icons: true        # 显示图标
  badges: false      # 显示数字角标

菜单项支持自定义外部链接：

1
2
menu:
  导航: https://example.com || fa fa-external-link-alt

七、社交链接

1
2
3
4
5
6
7
8
9
social:
  GitHub: https://github.com/yourname || fab fa-github
  E-Mail: mailto:yourname@gmail.com || fa fa-envelope
  Twitter: https://twitter.com/yourname || fab fa-twitter

social_icons:
  enable: true
  icons_only: false    # true=只显示图标不显示文字
  transition: false    # 悬停动画

八、代码高亮

NexT 内置多种代码高亮主题，无需安装额外插件。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
codeblock:
  theme:
    light: default
    dark: stackoverflow-dark

  # Prism 主题（需安装 hexo-filter-mathjax 等依赖）
  prism:
    light: prism
    dark: prism-dark

  # 复制按钮
  copy_button:
    enable: true
    style: mac    # default | flat | mac

  # 代码折叠
  fold:
    enable: false
    height: 500

  # 显示语言名称
  language: false

九、评论系统

NexT 支持多评论系统并存（tabs 切换），以下任选其一：

9.1 Disqus

1
2
3
4
disqus:
  enable: true
  shortname: your-short-name
  count: true

9.2 Gitalk（基于 GitHub Issues）

1
2
3
4
5
6
7
8
gitalk:
  enable: true
  github_id: your-github-username
  repo: comments       # 存放评论的仓库
  client_id: your-client-id
  client_secret: your-client-secret
  admin_user: your-github-username
  distraction_free_mode: true

⚠️ 注意：如果 GitHub 用户名是纯数字，在 _config.next.yml 中要加引号：

1
github_id: "12345678"

9.3 Utterances（轻量级 GitHub Issues 评论）

1
2
3
4
5
utterances:
  enable: true
  repo: user-name/repo-name
  issue_term: pathname   # pathname | url | title
  theme: github-light

9.4 LiveRe（韩国评论系统）

1
livere_uid: your_uid   # 从 livere.com 获取

9.5 关闭单页评论

在文章的 front-matter 中：

1
2
3
4
---
title: 我的文章
comments: false
---

十、搜索功能

10.1 本地搜索（推荐，无需注册）

安装依赖：

1
npm install hexo-generator-searchdb

Hexo 主配置文件 _config.yml：

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

NexT 主题配置：

1
2
3
4
5
local_search:
  enable: true
  top_n_per_article: 1    # 每篇文章最多显示几条结果
  unescape: false
  preload: false         # 页面加载时预加载搜索数据

10.2 Algolia 搜索

1
2
3
4
algolia_search:
  enable: true
  hits:
    per_page: 10

需要配合 hexo-algolia 插件使用，并在 Algolia 注册账号。

十一、SEO 设置

1
2
3
4
5
6
7
8
9
10
11
12
# 副标题加入首页标题
index_with_subtitle: false

# 外部链接加密
exturl: false
exturl_icon: true

# 各搜索引擎验证
google_site_verification:
bing_site_verification:
yandex_site_verification:
baidu_site_verification:

验证值需从各搜索引擎站长平台获取。

十二、分析统计

服务 配置键 说明
Google Analytics google_analytics.tracking_id UA 或 GA4
百度统计 baidu_analytics 百度统计 app_id
Cloudflare cloudflare_analytics
Microsoft Clarity clarity_analytics project_id
Matomo matomo 自建分析
Umami umami 自建分析
Plausible plausible
不蒜子 busuanzi_count 轻量级访客统计

不蒜子示例：

1
2
3
4
5
busuanzi_count:
  enable: true
  total_visitors: true
  total_views: true
  post_views: true

十三、CDN 配置

1
2
3
4
5
6
7
8
9
vendors:
  # 内部脚本 CDN（建议设为 local）
  internal: local

  # 第三方插件 CDN
  plugins: cdnjs    # local | jsdelivr | unpkg | cdnjs | custom

  # 自定义 CDN（当 plugins 设为 custom 时）
  custom_cdn_url: https://cdn.jsdelivr.net/npm/${npm_name}@${version}/${minified}

如果使用最新版 NexT master 分支，请将 internal 设为 local。

十四、数学公式

14.1 安装 MathJax 插件

1
npm install hexo-filter-mathjax

14.2 NexT 配置

1
2
3
4
5
6
7
8
math:
  every_page: false    # true=全站加载 | false=按需加载（需在文章 front-matter 加 math: true）
  mathjax:
    enable: false
    tags: none         # none | ams | all
  katex:
    enable: false
    copy_tex: false

十五、图片处理

1
2
3
4
5
6
7
8
# FancyBox（图片灯箱）
fancybox: false

# Medium Zoom（图片缩放，与 fancybox 二选一）
mediumzoom: false

# 图片懒加载
lazyload: false

⚠️ fancybox 和 mediumzoom 不可同时开启。

十六、动画效果

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

十七、文章页面设置

17.1 摘要与阅读更多

  • 使用 <!-- more --> 在正文中手动截断（推荐）
  • 或在 front-matter 中使用 description: 设置摘要
1
2
excerpt_description: true   # 是否使用 description 作为摘要
read_more_btn: true         # 显示"阅读更多"按钮

17.2 文章元信息

1
2
3
4
5
6
7
post_meta:
  item_text: true
  created_at: true
  updated_at:
    enable: true
    another_day: true     # 与创建日期相同时是否仍显示
  categories: true

17.3 字数统计（需安装插件）

1
npm install hexo-word-counter
1
2
3
symbols_count_time:
  separated_meta: true    # 统计单独成行
  item_text_total: false  # 页脚显示总字数

17.4 上一篇/下一篇导航

1
post_navigation: left   # left | right | false

十八、打赏/捐赠

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

十九、标签插件（内置）

NexT 提供多个内置标签，无需额外安装：

19.1 Note 标签（提示框）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{% note default %}
默认提示
{% endnote %}

{% note primary %}
主要提示
{% endnote %}

{% note success %}
成功提示
{% endnote %}

{% note warning %}
警告提示
{% endnote %}

{% note danger %}
危险提示
{% endnote %}

NexT 配置样式：

1
2
3
4
note:
  style: simple    # simple | modern | flat | disabled
  icons: false
  light_bg_offset: 0

19.2 Tabs 标签（标签页）

1
2
3
4
5
6
{% tabs unique-name %}
<!-- tab 第一页 -->
内容1
<!-- tab 第二页 -->
内容2
{% endtabs %}

19.3 PDF 标签（需安装依赖）

1
npm install hexo-pdf
1
2
3
pdf:
  enable: true
  height: 500px

19.4 Mermaid 标签（流程图）

1
2
3
4
5
mermaid:
  enable: true
  theme:
    light: default
    dark: dark

二十、自定义页面

20.1 404 页面

1
2
menu:
  commonweal: /404/ || fa fa-heartbeat

在 source/ 下创建 404/index.md 即可。

20.2 日程页面（Google Calendar）

1
2
3
4
5
6
calendar:
  calendar_id: <required>
  api_key: <required>
  orderBy: startTime
  offsetMax: 72
  offsetMin: 4

20.3 Sitemap

1
npm install hexo-generator-sitemap hexo-generator-baidurl-submit

二十一、性能优化

21.1 PJAX（无刷新跳转）

1
pjax: true

21.2 预加载

1
2
3
4
5
6
7
8
9
10
11
# 字体预连接
preconnect: true

# 快速链接预取
quicklink:
  enable: true
  home: false
  archive: false
  delay: true
  timeout: 3000
  priority: true

21.3 Pangu（中日韩文与英文间距）

1
npm install hexo-pangu
1
pangu: true

二十二、其他实用配置

22.1 阅读进度条

1
2
3
4
5
6
reading_progress:
  enable: true
  start_at: left
  position: top
  color: "#37c6c0"
  height: 3px

22.2 回到顶部按钮

1
2
3
4
back2top:
  enable: true
  sidebar: false      # 显示在侧边栏
  scrollpercent: true  # 显示滚动百分比

22.3 GitHub Banner

1
2
3
github_banner:
  enable: true
  permalink: https://github.com/yourname

22.4 网站图标

1
2
3
4
5
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

二十三、国际化（i18n）

NexT 支持 20+ 语言。在 Hexo 主配置文件 _config.yml 中设置：

1
language: zh-CN

可覆盖默认翻译，方法：编辑 themes/next/languages/ 下的语言文件，或在 source/_data/ 中自定义。

附录：配置清单速查

功能 关键配置项
标签页 menu.tags + 文章 tags front-matter
分类页 menu.categories + 文章 categories front-matter
归档页 menu.archives（无需 MD，Hexo 自动生成）
暗黑模式 darkmode: true
社交链接 social: 配置块
评论 disqus/gitalk/utterances/livere 等
搜索 local_search: 或 algolia_search:
统计 google_analytics/busuanzi_count 等
CDN vendors.internal / vendors.plugins
代码高亮 codeblock.theme
数学公式 math: + hexo-filter-mathjax
懒加载 lazyload: true
进度条 reading_progress:
回到顶部 back2top:

📌 提示：所有配置修改后，执行 hexo clean && hexo server 清除缓存并重新预览。