在上篇中，我们已经完成 Hexo 的安装、站点初始化、文章写作、本地预览与静态构建。现在内容系统已经可用，接下来要解决的是体验问题：让博客拥有清晰的导航、现代化首页、文章目录、搜索和评论。

本篇会安装 Solitude v4，并按照一条适合新站的顺序完成配置。你不需要第一天就打开所有功能，先把最重要的阅读路径搭好，再逐步增加评论、统计和个性化样式。

如果你还没有可运行的 Hexo 站点，请先阅读：

如何用 Hexo 和 Solitude 为自己搭建博客（上）：Hexo 的安装与使用

开始前需要什么？

截至 2026 年 7 月，Solitude 当前 NPM 主版本为 4.0.0。官方最低要求是 Hexo 7.0.0+ 与 Node.js 14.0.0+，但如果你使用上篇安装的 Hexo 8，Node.js 仍必须满足 Hexo 的更高要求，也就是 20.19.0 或以上。

开始前确认：

1
2
node --version
hexo version

并确认默认主题下的站点能够正常运行：

1
2
3
hexo clean
hexo generate
hexo server

更换主题前，建议先把博客源码提交到 Git。这样配置出错时，可以清楚看到自己修改了哪些内容。

一、安装 Solitude

Solitude 支持 NPM 与 Git 两种安装方式。新站更推荐 NPM：依赖关系清晰，升级也更方便。

推荐方式：NPM 安装

在 Hexo 站点根目录执行：

1
npm install hexo-theme-solitude@4

主题会进入 node_modules/hexo-theme-solitude，同时记录在 package.json 中。

备选方式：Git 安装

1
2
git clone --branch v4.0.0 --depth 1 \
  https://github.com/everfu/hexo-theme-solitude.git themes/solitude

这种方式适合需要直接阅读或修改主题源码的开发者。普通使用时，不建议把大量个性化改动直接写进主题目录，否则以后升级会很痛苦。

二、启用主题

打开站点根目录的 _config.yml，找到 theme：

1
theme: solitude

同时确认站点的基础信息已经填写：

1
2
3
4
5
6
7
title: 我的个人博客
subtitle: 笔记、项目与生活
description: 一个记录学习和创作的个人博客
author: Your Name
language: zh-CN
timezone: Asia/Shanghai
url: https://example.com

这里的 _config.yml 属于 Hexo，负责站点级配置。Solitude 自己还有一份独立主题配置，下一步就来创建。

三、创建 _config.solitude.yml

NPM 安装方式

1
cp node_modules/hexo-theme-solitude/_config.yml _config.solitude.yml

Git 安装方式

1
cp themes/solitude/_config.yml _config.solitude.yml

以后主要修改站点根目录的 _config.solitude.yml，不要直接修改 node_modules 中的默认文件。

这样做有三个好处：

  • npm install 不会覆盖你的主题配置
  • 升级时可以对比新旧默认配置
  • Hexo 站点配置与主题配置的职责更清晰

首次启用后重新构建：

1
2
3
hexo clean
hexo generate
hexo server

浏览器打开 http://localhost:4000/。如果页面仍然是默认 Landscape 主题，检查根 _config.yml 中是否确实写了 theme: solitude，然后重新执行 hexo clean。

四、先准备图片资源

Solitude 会使用头像、网站图标、文章封面和首页推荐图。建议把自有资源放到 source/img：

1
2
3
4
5
source/img/
├── avatar.png
├── favicon.png
├── default-cover.png
└── recommend.png

配置中使用从网站根路径开始的地址：

1
/img/avatar.png

不要使用电脑上的绝对路径，也不要把图片放进 node_modules。后者会在重新安装依赖时被替换。

图片建议：

  • 头像使用清晰的正方形图片
  • Favicon 尺寸尽量简洁，缩小后仍能识别
  • 封面保持统一比例，避免首页卡片高度跳动
  • 图片先压缩再上线，减少移动端加载时间

五、配置网站名称和图标

打开 _config.solitude.yml，找到 site：

1
2
3
4
5
site:
  name:
    class: text
    custom: 我的个人博客
  icon: /img/favicon.png

class: text 表示导航栏使用文字站名。主题也支持图标或图片形式，但刚开始更推荐文字，稳定且清晰。

Solitude 的配置文件很长，不要急着从头到尾修改。每完成一组配置，就刷新页面检查一次，比一次改几百行更容易定位错误。

六、配置导航栏

一个个人博客最基本的导航通常包括：首页、归档、分类、标签和关于。

1
2
3
4
5
6
7
8
9
10
11
12
nav:
  menu:
    首页: /
    文章:
      归档: /archives/ || fas fa-folder-closed
      分类: /categories/ || fas fa-clone
      标签: /tags/ || fas fa-tags
    关于: /about/ || fas fa-user

  right:
    random: true
    custom:

|| 后面是 Font Awesome 图标类名。没有图标也可以只填写链接。

如果还没有关于页面，先执行：

1
hexo new page "about"

然后编辑 source/about/index.md。

Solitude 会根据 Hexo 生成的归档、分类和标签页面显示内容。如果页面访问 404，先确认对应生成器依赖存在，再重新构建站点。

七、配置首页顶部

Solitude 的 hometop 用于控制首页顶部介绍与推荐入口。新站可以使用一段简洁定位，而不是堆满功能说明。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
hometop:
  enable: true
  banner:
    title: 分享技术<br />与日常生活
    desc:
      - 记录真实的学习过程
      - 分享可以复用的实践经验

  recommendList:
    enable: true
    sup: 推荐
    title: 从这里开始
    url: /about/
    img: /img/recommend.png
    color: none

首页大标题应该说明博客是谁、写什么或提供什么，不必使用空泛口号。描述控制在两三条，移动端会更容易阅读。

文章列表布局位于 index_post_list：

1
2
3
4
index_post_list:
  direction: column
  column: 2
  cover: both

配置项会随主题版本演进，修改前应以当前 _config.solitude.yml 中的注释和官方文档为准。

八、配置侧边栏

侧边栏用于展示作者信息、最新文章和站点数据。不要把所有模块都打开，否则文章页面会显得很重。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
aside:
  home:
    noSticky: "about"
    Sticky: "allInfo"
  post:
    noSticky: "about"
    Sticky: "newestPost"
  page:
    noSticky: "about"
    Sticky: "newestPost,allInfo"
  position: 1

  my_card:
    author:
      img: /img/avatar.png
    description: 笔记、项目与生活。
    content: 在这里记录长期有价值的内容。
    information:
      GitHub: https://github.com/your-name || fab fa-github

Solitude v4 的有效侧栏模块名包括：

  • about
  • newestPost
  • allInfo
  • newest_comment

position: 0 表示左侧，position: 1 表示右侧。首页、文章和独立页面可以分别配置固定与非固定模块。

九、配置文章体验

主题的文章设置位于 post。建议先关注默认封面、文章目录、版权和元信息。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
page:
  default:
    cover:
      - /img/default-cover.png

post:
  default:
    cover:
      - /img/default-cover.png
    locate: China
    copyright:
      enable: true
      author: /img/avatar.png
      license: CC BY-NC-SA 4.0
      licenurl: https://creativecommons.org/licenses/by-nc-sa/4.0/deed.zh-hans

文章目录由侧栏的 toc 控制：

1
2
3
4
5
aside:
  toc:
    post: true
    page: false
    vague: true

单篇文章仍然可以通过 Front Matter 设置专属封面与摘要：

1
2
3
4
5
6
7
8
9
10
---
title: 文章标题
date: 2026-07-29 16:00:00
categories:
  - 技术
tags:
  - Hexo
cover: /img/article-cover.png
description: 这是一段用于首页与搜索引擎的文章摘要。
---

首页默认只展示摘要时，可以在正文合适位置加入：

1
<!--more-->

十、启用本地搜索

本地搜索不需要外部账号，适合个人博客。先安装生成器：

1
npm install hexo-generator-search --save

在 Hexo 的 _config.yml 中添加：

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

然后在 _config.solitude.yml 中配置：

1
2
3
4
5
6
7
8
9
search:
  enable: true
  type: local
  tags:
    - Hexo
    - Solitude
  local:
    preload: false
    CDN: /search.xml

重新构建：

1
2
3
hexo clean
hexo generate
hexo server

先直接访问 http://localhost:4000/search.xml。这个文件能打开，主题搜索却没有结果时，再检查浏览器控制台和主题配置。

对于文章数量不多的个人博客，本地搜索已经足够。只有内容规模和搜索需求明显增加时，再考虑 Algolia 或 DocSearch。

如果使用 Algolia，浏览器端只能配置用于查询的 Search-Only API Key，绝不能暴露 Admin API Key。

十一、使用 Giscus 添加评论

Giscus 使用 GitHub Discussions 保存评论，适合以技术内容为主、读者普遍拥有 GitHub 账号的博客。

准备步骤：

  1. 博客对应的 GitHub 仓库必须是公开仓库
  2. 在仓库设置中开启 Discussions
  3. 安装 Giscus GitHub App
  4. 在 giscus.app 生成仓库参数

在 _config.solitude.yml 中配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
comment:
  use: giscus
  commentBarrage: false
  lazyload: true
  count: true
  sidebar: false
  pv: false
  avatar: https://gravatar.com/avatar

giscus:
  repo: owner/repository
  repo_id: repository-id
  category_id: discussion-category-id
  theme:
    light: light
    dark: dark
  option:

注意 giscus 是和 comment 平级的顶层配置块，不能缩进到 comment 里面。

Giscus 不支持 Solitude 的最新评论列表与 PV 计数。需要这些能力时，可以评估 Twikoo 或 Waline，但它们通常还需要独立的服务端部署。

想关闭某一篇文章的评论，在该文章 Front Matter 中使用：

1
comment: false

不要把评论服务的管理员 Token、Master Key 或 Admin API Key 提交到公开仓库。

十二、添加自定义 CSS 与脚本

尽量不要直接改主题源码。可以把样式放在：

1
source/css/custom.css

再通过 _config.solitude.yml 引入：

1
2
3
4
extends:
  head:
    - <link rel="stylesheet" href="/css/custom.css">
  body:

自定义脚本同理，可以放到 source/js 后在 extends.body 中引用。

Solitude v4 使用统一的 PJAX 生命周期。页面切换时需要重复初始化的脚本，不能只监听传统的 DOMContentLoaded。从 v3 升级的自定义脚本如果依赖旧的 pjax、utils 或 GLOBAL_CONFIG 全局对象，应按照 v4 文档迁移到新的接口。

这也是为什么普通用户更适合优先使用主题配置，而不是大范围修改模板和 JavaScript。

十三、构建前检查

每完成一组配置，都可以运行：

1
2
3
hexo clean
hexo generate
hexo server

上线前至少检查：

  • 首页桌面与移动端布局
  • 导航栏中的每一个链接
  • 文章目录与代码块
  • 归档、分类、标签和关于页面
  • 搜索是否返回文章
  • 评论区是否能加载并切换明暗主题
  • 图片、字体与脚本是否出现 404
  • 浏览器控制台是否有 ES Module 或动态导入错误
  • 浏览器前进、后退和多次页面切换是否正常

只检查首页是不够的。主题问题经常出现在文章页、搜索结果、移动端菜单或 PJAX 第二次进入页面时。

十四、升级 Solitude

NPM 安装方式

1
npm install hexo-theme-solitude@4

Git 安装方式

1
2
git -C themes/solitude fetch --tags
git -C themes/solitude switch --detach v4.0.0

升级前先提交或备份当前配置。然后：

  1. 取得新版本默认 _config.yml
  2. 以新默认配置为底稿
  3. 把自己的站点名称、图片、导航等值合并进去
  4. 重新构建并完整测试

不要拿 Solitude 3.x 的 _config.solitude.yml 直接覆盖 v4 默认配置。主版本升级往往会调整字段结构和前端生命周期，强行复用旧文件会产生难以定位的问题。

十五、常见问题

页面仍然显示默认主题

确认根 _config.yml：

1
theme: solitude

然后执行 hexo clean 再启动。

配置修改后站点无法构建

多数情况来自 YAML 缩进。查看错误提示附近的行，检查 Tab、缩进层级和冒号后的空格。

搜索窗口没有内容

先访问 /search.xml。如果文件不存在，检查搜索生成器是否安装，以及 Hexo _config.yml 中的 search 配置。

文章字数和阅读时间不显示

这类数据通常需要额外安装 hexo-wordcount，不是主题仅靠配置就能计算出来。

访问量不显示

Solitude 可以配合评论服务的页面统计或 busuanzi。两套统计不要重复开启，以免展示的数据口径不一致。

图片灯箱重复弹出

Fancybox、Medium Zoom 等图片预览实现只启用一套。多个脚本同时绑定图片点击事件会产生冲突。

配置顺序建议

Solitude 提供的选项很多，第一次使用可以按下面的顺序推进：

  1. 站点身份与图标
  2. 导航栏和必要页面
  3. 首页介绍与文章列表
  4. 侧边栏和文章目录
  5. 默认封面与文章版权
  6. 本地搜索
  7. 评论系统
  8. 统计、PWA、音乐等可选功能
  9. 自定义 CSS 与脚本

先保证阅读和查找内容的主流程顺畅，再加入装饰性功能。一个长期维护的博客，稳定、清楚和容易写作，比第一天打开全部开关更重要。

系列回顾

完成这两篇后，你已经拥有一套完整的个人博客基础：Markdown 写作、静态构建、主题展示、内容搜索与读者评论。后续真正值得投入的，是持续写内容、定期备份源码，并让设计逐渐适合自己的主题。

参考资料