前言

Hexo 是一个快速、简洁且高效的博客框架，使用 Markdown 解析文章，可以在几秒内生成静态网页。本教程将指导您从零开始搭建一个 Hexo 博客网站，并部署到互联网上。

在开始搭建 Hexo 博客之前，我们先了解一下基本流程和准备工作。完整的搭建过程包括：环境准备、Hexo安装、主题配置和网站部署等步骤。

必要的工具和链接

  • Node.js：运行 Hexo 的必要环境，请安装最新版本。
  • Git：用于版本控制和管理代码。
  • 淘宝 NPM 镜像源：用于加速 npm 包的安装。
  • Hexo 官方网站：可以查找更多主题和插件。
  • GitHub：用来存储博客代码，需要一个 GitHub 账号。
  • Visual Studio Code：推荐使用的编辑器，便于代码管理（可选）。

检查环境

安装完 Node.js 和 Git 后，可以通过以下命令检查是否安装成功：

1
2
3
node -v
npm -v
git -v

如果返回版本号，说明安装成功。

安装 Hexo

使用以下命令全局安装 Hexo：

1
npm install -g hexo-cli

如果网络环境较差，可以使用淘宝的镜像源安装 Hexo：

1
cnpm install -g hexo-cli

初始化 Hexo 项目

选择一个文件夹来存放你的 Hexo 项目，执行以下命令来初始化：

1
hexo init <项目名称>

例如：

1
hexo init my-blog

初始化过程中如果遇到卡顿，可以按下 CTRL + C 终止。然后进入项目目录：

1
cd my-blog

安装项目依赖：

1
npm install

遇到 SSL 错误的解决方案

如果遇到 SSL 证书错误，可以通过以下命令关闭 Git 的 SSL 验证（仅建议在开发环境中使用）：

1
git config --global http.sslVerify false

选择并安装主题

  1. 选择一个 Hexo 主题（例如 Butterfly）。

  2. 访问主题的 GitHub 页面，点击 Code，下载压缩包。解压到 Hexo 项目的 themes 目录下，或直接使用 Git 克隆主题：

    1
    git clone https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

  3. 修改 Hexo 根目录的 _config.yml 文件，设置主题名称：

    1
    theme: butterfly

Butterfly 主题个性化配置

安装完 Butterfly 主题后，我们可以通过修改主题配置文件 _config.butterfly.yml 来打造个性化的博客。以下是详细的配置指南：

1. 导航菜单配置

一个清晰的导航菜单是网站的地图，让访客知道去哪里找到他们需要的内容。

修改说明： 创建”首页”、”目录”和”关于”三个顶级菜单。”目录”是一个下拉菜单，包含了”文章”、”分类”和”标签”三个子页面。

1
2
3
4
5
6
7
menu:
  首页: / || fas fa-home
  目录||fa-fw fas fa-compass:
    文章: /archives || fa-fw fas fa-archive
    分类: /categories || fa-regular fa-folder-open
    标签: /tags || fa-solid fa-tags
  关于: /about || fa-solid fa-id-card

2. 代码块高度限制

如果文章中包含大量代码，过长的代码块会影响页面美观和阅读流畅性。

修改说明： 将 height_limit 设置为 300，代码块高度超过 300px 时将自动出现滚动条。

1
2
code_blocks:
  height_limit: 300

3. 社交链接配置

在侧边栏展示社交媒体链接，方便访客与你建立联系。

1
2
3
social:
  fab fa-github: https://github.com/xyuns-cn || Github || '#24292e'
  fas fa-envelope: mailto:[email protected] || Email || '#4a7dbe'

4. 核心视觉元素设置

统一的视觉元素是打造品牌感的第一步。设置网站图标、个人头像和各个页面的顶部图。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 网站图标
favicon: https://b2.xyuns.cc/icons8-french-fries-48.png

# 头像
avatar:
  img: https://b2.xyuns.cc/pic.jpg
  effect: false

# 首页顶部图
index_img: https://b2.xyuns.cc/wallhaven-wex83x.jpg

# 归档页顶部图
archive_img: https://b2.xyuns.cc/wallhaven-wex83x.jpg

# 标签页顶部图
tag_img: https://b2.xyuns.cc/wallhaven-wex83x.jpg

# 分类页顶部图
category_img: https://b2.xyuns.cc/wallhaven-wex83x.jpg

5. 文章封面设置

为没有设置特定封面的文章提供默认封面图，让主页看起来更丰富多彩。由于 Butterfly 主题默认无法适配随机图片 API，我们需要进行特殊配置。

创建随机图片支持脚本

首先，在 Hexo 根目录下的 themes\butterfly\scripts 文件夹中新建一个 random_img.js 文件，并添加以下代码：

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
/**
 * Butterfly
 * ramdom cover
 */

'use strict'

hexo.extend.filter.register('before_post_render', function (data) {
  const { config } = this
  if (config.post_asset_folder) {
    const imgTestReg = /\.(png|jpe?g|gif|svg|webp)(\?.*)?$/
    const topImg = data.top_img
    const cover = data.cover
    if (topImg && topImg.indexOf('/') === -1 && imgTestReg.test(topImg)) data.top_img = data.path + topImg
    if (cover && cover.indexOf('/') === -1) data.cover = data.path + cover
  }

  if (data.cover === false) {
    data.randomcover = randomCover()
    return data
  }

  data.cover = data.cover || randomCover()
  return data
},0)

function randomCover () {
  const theme = hexo.theme.config
  let cover
  let num

  if (theme.cover && theme.cover.default_cover) {
    if (!Array.isArray(theme.cover.default_cover)) {
      cover = theme.cover.default_cover
    } else {
      num = Math.floor(Math.random() * theme.cover.default_cover.length)
      cover = theme.cover.default_cover[num]
    }
  } else {
    cover = theme.default_top_img || 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7'
  }
  if(theme.cover.suffix){
    if(theme.cover.suffix == 1)
      cover = cover + ("?" + Math.ceil(Math.random()*10000))
    else if(theme.cover.suffix == 2)
      cover = cover + ("&" + Math.ceil(Math.random()*10000))
  }
  return cover
}

配置主题文件

然后在 Butterfly 主题配置文件 _config.butterfly.yml 中配置封面设置：

1
2
3
4
5
6
7
8
9
cover:
  # Disable the cover or not
  index_enable: true
  aside_enable: true
  archives_enable: true
  suffix: 1  # 0是不使用后缀、1是?加随机数；2是&加随机数
  # When cover is not set, the default cover is displayed
  default_cover:
    - https://tu.ltyuanfang.cn/api/fengjing.php

配置说明：

  • suffix: 1 会在随机图片 API 链接后面加入后缀 ?spm={随机数}，确保每次都能获取到不同的图片
  • 这样配置后，每篇没有设置封面的文章都会显示不同的随机风景图片

6. 首页定制

首页是访客对博客的第一印象，我们可以启用打字机效果的副标题，并更改文章列表的布局。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 首页副标题
subtitle:
  enable: true
  effect: true
  sub:
    - 技术改变世界
    - 欢迎来到我的博客

# 首页文章布局（5为封面图作为背景的卡片布局）
index_layout: 5

# 首页文章摘要显示方式（1为优先显示description）
index_post_content:
  method: 1
  length: 500

7. 侧边栏配置

侧边栏是展示附加信息的好地方，我们可以修改作者卡片和公告栏。

1
2
3
4
5
6
7
8
9
10
11
12
aside:
  card_author:
    enable: true
    description:
    button:
      enable: true
      icon: fab fa-github
      text: Follow Me
      link: https://github.com/xyuns-cn
  card_announcement:
    enable: true
    content: 好博客，一定要 分享出去 呀~

8. 功能增强

启用 Butterfly 内置的实用功能。

1
2
3
4
5
6
7
8
9
10
11
12
13
# 显示滚动百分比
rightside_scroll_percent: true

# 开启字数统计（需要先安装 hexo-wordcount 插件）
wordcount:
  enable: true
  post_wordcount: true
  min2read: true
  total_wordcount: true

# 开启本地搜索
search:
  use: local_search

9. 页脚信息

更新网站的起始年份等信息。

1
2
3
4
footer:
  owner:
    enable: true
    since: 2017 # 修改为你网站开始的年份

本地生成和预览

  1. 清理缓存文件：

    1
    hexo clean

  2. 生成静态文件：

    1
    hexo generate

  3. 启动本地服务器进行预览：

    1
    hexo server

    可以将命令写在一起hexo cl && hexo g && hexo s
    在浏览器中访问 http://localhost:4000 即可查看博客效果。

安装必要插件

在完成主题配置后，我们需要安装一些插件来支持上述功能：

安装搜索插件

为了支持本地搜索功能，需要安装 hexo-generator-search 插件：

1
npm install hexo-generator-search --save

安装字数统计插件

为了支持字数统计功能，需要安装 hexo-wordcount 插件：

1
npm install hexo-wordcount --save

配置全局配置文件

在 Hexo 根目录的 _config.yml 文件中添加搜索配置：

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

配置完成后，重新生成并启动服务器即可看到所有功能：

1
hexo clean && hexo generate && hexo server

部署博客

部署到 GitHub

  1. 在 GitHub 上创建一个仓库来保存你的 Hexo 博客代码。

  2. 安装 Hexo 的部署插件：

    1
    npm install hexo-deployer-git --save

    或使用淘宝镜像源：

    1
    cnpm install hexo-deployer-git --save

  3. 配置 Hexo 部署信息，修改根目录下的 _config.yml 文件，添加以下内容：

    1
    2
    3
    4
    deploy:
      type: git
      repo: https://<你的访问令牌>@github.com/你的用户名/你的仓库名.git
      branch: main

    示例配置：

    1
    2
    3
    4
    deploy:
      type: git
      repo: https://[email protected]/xyuns-cn/xyunblog.git
      branch: main

  4. 使用以下命令将本地生成的静态文件推送到 GitHub：

    1
    hexo deploy

部署到 Vercel 等免费容器

如果希望使用免费容器服务部署博客，可以考虑 Vercel 等平台。

  1. 使用 GitHub 账户登录 Vercel 并授权。
  2. 通过 Vercel 同步你的 GitHub 仓库，即可轻松将博客托管在互联网上。

Hexo常用命令

以下是Hexo的一些常用命令，可以帮助你更高效地管理博客：

基本命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 创建新文章
hexo new "文章标题"

# 创建新页面
hexo new page "页面名称"

# 生成静态文件
hexo generate 或 hexo g

# 启动服务器预览
hexo server 或 hexo s

# 部署网站
hexo deploy 或 hexo d

# 清除缓存
hexo clean

# 列出网站信息
hexo list

组合命令

1
2
3
4
5
6
7
# 清除缓存、生成静态文件并启动服务器
hexo clean && hexo generate && hexo server
或简写：hexo cl && hexo g && hexo s

# 生成静态文件并部署
hexo generate && hexo deploy
或简写：hexo g && hexo d

自定义文章模板

你可以在 scaffolds 目录下修改或创建自己的文章模板，如修改 post.md 来自定义新建文章的默认内容。

总结

通过以上步骤，你应该已经成功安装并配置了 Hexo 博客，并能够将其部署到 GitHub 或其他平台。借助这些常用命令，你可以更高效地管理和更新你的博客。记得根据需求不断调整和优化主题及功能，打造属于自己的独特博客系统。