从 2020 年开始，我用 Hexo 搭建并维护了这个博客，一晃就是 5 年多，累计发表了 225 篇文章。最近，我完成了一次"大修"——将整个博客从 Hexo 迁移到了 Hugo。这篇文章记录了我为什么要迁移、Hugo 的优势、如何从零开始使用 Hugo，以及从 Hexo 低成本迁移的完整步骤。如果你也在考虑换博客框架，希望这篇指南能帮你少走弯路。

一、用了5年Hexo，为什么要换？

先交代一下背景。我的原博客基于 Hexo + NexT 主题，托管在 GitHub Pages 上，自定义域名访问，跑了整整 5 年。Hexo 本身是个很好的工具，陪伴我走过了从博客搭建小白到能熟练定制主题的全过程。

但几个问题日积月累，最终促使我下定决心迁移：

1. 构建速度越来越慢

随着文章数量增加到 200 多篇，Hexo 的生成时间从最初的几秒变成了几十秒。每次本地预览都要等，写作体验大打折扣。

2. Node.js 依赖地狱

Hexo 基于 Node.js，各种插件、主题依赖经常因为版本升级出问题。我有过两次因为 Node 版本升级导致构建失败的遭遇，排查起来非常耗时。

3. 主题维护停滞

我用的 NexT 主题虽然经典，但更新频率明显降低，一些新特性（如深色模式自动切换、更好的搜索体验）要么实现起来麻烦，要么干脆没有。

4. 单文件配置复杂

Hexo 的配置集中在一个 _config.yml 里，随着定制增多，这个文件越来越庞大，管理和维护都很不方便。

于是我开始寻找替代方案，最终选择了 Hugo。

二、Hugo vs Hexo vs WordPress：为什么选择 Hugo？

在决定迁移之前，我对比了市面上主流的几个博客方案：

Hugo

维度	评价
构建速度	极快。基于 Go 语言编写，每秒可生成数千页面，225 篇文章在我的笔记本上不到 1 秒完成构建
依赖管理	几乎零依赖。只有一个二进制文件，无需 Node.js、Python 等运行时
主题生态	丰富且活跃。PaperMod、Blowfish 等主题功能现代、维护积极
配置方式	灵活。支持 YAML/TOML/JSON，支持多环境配置、模块化配置
学习曲线	适中。模板语法使用 Go 的 `html/template`，有一定门槛
内容格式	原生支持 Markdown，Front Matter 兼容性好

Hexo

维度	评价
构建速度	中等。Node.js 单线程，文章多了明显变慢
依赖管理	复杂。npm 依赖树庞大，版本升级容易出问题
主题生态	丰富但分化。经典主题维护放缓，新主题数量不如 Hugo
配置方式	单文件 `_config.yml`，功能多了以后很臃肿
学习曲线	较低。基于 JavaScript，前端开发者上手容易
内容格式	支持 Markdown，插件丰富

WordPress

维度	评价
构建速度	动态生成，无需构建，但服务器响应受插件影响
依赖管理	需要 PHP + MySQL 环境，服务器维护成本高
主题生态	极其丰富，但优质主题多收费
配置方式	图形化后台，对技术用户反而不够灵活
学习曲线	低。但深度定制需要懂 PHP
内容格式	富文本编辑器，Markdown 需插件支持
托管成本	需要服务器/虚拟主机，GitHub Pages 无法直接托管

我的选择理由

我的需求	Hugo 的匹配度
免费托管在 GitHub Pages	完美支持
文章多、构建要快	Hugo 是静态生成器中最快的
不想折腾 Node.js 依赖	单个二进制文件，零依赖
现代化主题（深色模式、搜索等）	PaperMod 主题开箱即用
从 Hexo 迁移成本低	Front Matter 高度兼容，文章基本无需改动
长期维护省心	Go 语言生态稳定，Hugo 社区活跃

总结：如果你追求极致的构建速度、零依赖、现代化主题，并且习惯用 Markdown 写作，Hugo 是目前静态博客生成器的最佳选择之一。如果你更在意生态丰富度和前端开发的灵活性，Hexo 依然是好选择。WordPress 则适合需要动态功能、不想接触代码的用户，但要承担服务器成本。

三、Hugo 安装：一步到位的极简体验

Hugo 的安装可以说是所有博客工具中最简单的，没有之一。

macOS

1
2
3
4
5
# 使用 Homebrew 安装
brew install hugo

# 验证安装
hugo version

Windows

1
2
3
4
5
6
7
8
# 使用 Chocolatey
choco install hugo-extended

# 或使用 Scoop
scoop install hugo-extended

# 验证安装
hugo version

Linux

1
2
3
4
5
6
7
8
9
# Ubuntu/Debian
sudo apt install hugo

# 或下载官方二进制文件
wget https://github.com/gohugoio/hugo/releases/download/v0.160.1/hugo_extended_0.160.1_linux-amd64.deb
sudo dpkg -i hugo_extended_0.160.1_linux-amd64.deb

# 验证安装
hugo version

注意：如果主题使用了 Sass/SCSS（如 PaperMod），请安装 hugo-extended 版本，否则构建会报错。

安装完成后，你只有一个 hugo 可执行文件，没有任何后台服务、没有依赖目录，干净利落。

四、从零开始：创建 Hugo 站点并部署到 GitHub Pages

Step 1：创建新站点

1
2
3
4
5
6
# 创建站点目录
hugo new site myblog
cd myblog

# 初始化 Git 仓库
git init

目录结构如下：

myblog/
├── archetypes/      # 文章模板
├── assets/          # 需要处理的资源（Sass、JS）
├── content/         # 文章内容
├── data/            # 数据文件
├── layouts/         # HTML 模板
├── static/          # 静态文件（直接复制到输出目录）
├── themes/          # 主题
└── hugo.toml        # 站点配置文件

Step 2：安装主题

这里以 PaperMod 为例，它是目前 Hugo 上最受欢迎的主题之一，功能现代、配置灵活。

1
2
3
4
5
6
# 将主题添加为 Git 子模块（推荐，方便后续更新）
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
git submodule update --init --recursive

# 启用主题
echo "theme = 'PaperMod'" >> hugo.toml

Step 3：配置站点

编辑 hugo.toml（或 hugo.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
55
56
57
58
59
60
61
baseURL = 'https://yourname.github.io'
defaultContentLanguage = 'zh'
languageCode = 'zh-CN'
hasCJKLanguage = true
title = "我的博客"
theme = 'PaperMod'

[params]
  author = "你的名字"
  description = "博客描述"
  defaultTheme = 'auto'        # 自动切换深色/浅色模式
  ShowToc = true               # 显示文章目录
  ShowReadingTime = true       # 显示阅读时间
  ShowWordCount = true         # 显示字数统计
  ShowCodeCopyButtons = true   # 代码复制按钮
  ShowRelatedPosts = true      # 相关文章推荐
  ShowPostNavLinks = true      # 上一篇/下一篇导航
  ShowBreadCrumbs = true       # 面包屑导航
  comments = true              # 开启评论

  [params.homeInfoParams]
    Title = "欢迎来到我的博客"
    Content = '记录学习与生活'

  [[params.socialIcons]]
    name = 'github'
    url = 'https://github.com/yourname'

[menu]
  [[menu.main]]
    name = '首页'
    url = '/'
    weight = 1
  [[menu.main]]
    name = '归档'
    url = '/archives/'
    weight = 2
  [[menu.main]]
    name = '分类'
    url = '/categories/'
    weight = 3
  [[menu.main]]
    name = '标签'
    url = '/tags/'
    weight = 4
  [[menu.main]]
    name = '关于'
    url = '/about/'
    weight = 5
  [[menu.main]]
    name = '搜索'
    url = '/search/'
    weight = 6

[markup]
  [markup.highlight]
    style = 'dracula'
    lineNos = true
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

Step 4：创建内容

1
2
3
4
5
# 创建文章
hugo new content posts/hello-world.md

# 创建页面
hugo new content about.md

文章 Front Matter 示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
---
title: "文章标题"
date: 2026-04-29T10:00:00+08:00
draft: false
tags:
  - Hugo
categories:
  - 技术
---

这里是正文内容，支持 Markdown 语法。

Step 5：本地预览

1
hugo server -D

打开浏览器访问 http://localhost:1313，-D 参数表示同时预览草稿（draft）文章。

Step 6：GitHub Actions 自动部署

在仓库中创建 .github/workflows/deploy.yml：

 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
name: Deploy Hugo to GitHub Pages

on:
  push:
    branches: [master]
  workflow_dispatch:

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

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

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.160.1
    steps:
      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
          sudo dpkg -i ${{ runner.temp }}/hugo.deb
      - name: Checkout
        uses: actions/checkout@v4
        with:
          submodules: recursive
          fetch-depth: 0
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Build with Hugo
        env:
          HUGO_CACHEDIR: ${{ runner.temp }}/hugo_cache
          HUGO_ENVIRONMENT: production
          TZ: Asia/Shanghai
        run: hugo --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

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

关键配置说明

submodules: recursive：必须启用，因为主题是通过子模块引入的
fetch-depth: 0：获取完整历史，Hugo 需要 Git 历史来生成文章修改时间等信息
hugo_extended：如果主题使用了 Sass/SCSS，必须使用 extended 版本
--minify：压缩 HTML/CSS/JS，减小文件体积
TZ: Asia/Shanghai：设置时区，确保文章发布时间正确

启用 GitHub Pages

在 GitHub 仓库的 Settings → Pages 中，将 Source 设置为 GitHub Actions
推送代码到 master 分支，自动触发部署
访问 https://yourname.github.io 查看效果

五、从 Hexo 迁移到 Hugo：低成本的完整方案

这是本文的核心部分。我已经成功将 225 篇文章从 Hexo 迁移到 Hugo，整个过程比你想象的要简单。

迁移前的准备

1. 备份原博客

1
cp -r myhexo/myblog myhexo/myblog-backup

2. 了解差异

对比项	Hexo	Hugo
配置文件	`_config.yml`	`hugo.toml` / `hugo.yaml`
文章目录	`source/_posts/`	`content/posts/`
页面目录	`source/`	`content/`
静态文件	`source/`	`static/`
主题目录	`themes/`	`themes/`
Front Matter	YAML	YAML/TOML/JSON

好消息是：Hugo 的 Front Matter 与 Hexo 高度兼容，大部分文章可以直接复制过去，几乎无需修改。

文章迁移

最简单的方法：直接复制

如果你的 Hexo 文章 Front Matter 比较标准，可以直接复制：

1
2
3
4
5
6
# 创建 Hugo 站点并初始化
cd myhugo
mkdir -p content/posts

# 复制文章
cp /path/to/hexo/source/_posts/*.md content/posts/

需要调整的地方

Hexo 写法	Hugo 写法	说明
`categories: [技术, 开发]`	`categories: ["技术", "开发"]`	层级分类需要显式声明为嵌套数组
`abbrlink: xxx`	`abbrlink: xxx`	相同，需要配合 shortcode
`<!-- more -->`	`

批量处理脚本

我写了一个简单的 Python 脚本来批量处理迁移中的常见问题：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
#!/usr/bin/env python3
import os
import re
import glob

def migrate_post(filepath):
    with open(filepath, 'r', encoding='utf-8') as f:
        content = f.read()

    # 1. 修复 <!-- more --> 为 <!--more-->
    content = re.sub(r'<!--\s*more\s*-->', '<!--more-->', content)

    # 2. 修复分类格式（如果需要）
    # Hexo 的多级分类可能需要调整

    # 3. 保存
    with open(filepath, 'w', encoding='utf-8') as f:
        f.write(content)

    print(f"Processed: {filepath}")

# 处理所有文章
for md_file in glob.glob('content/posts/*.md'):
    migrate_post(md_file)

保持原有链接不变（重要！）

如果你的博客已经被搜索引擎收录，或者有外部链接指向，保持 URL 不变非常重要。

方案一：使用 Permalink 规则

在 hugo.toml 中配置：

1
2
[permalinks]
  posts = '/:year/:month/:day/:title/'

方案二：使用 abbrlink（推荐）

如果你原来用了 Hexo 的 hexo-abbrlink 插件，可以在 Hugo 中保持相同的短链接：

安装 abbrlink 支持（需要自定义 shortcode 或插件）
或者使用 Hugo 的 aliases 功能做重定向：

1
2
3
4
5
---
title: "文章标题"
aliases:
  - /posts/79ebd763/
---

方案三：生成重定向页面

批量生成从旧 URL 到新 URL 的重定向页面，确保旧链接不会 404。

主题和样式迁移

如果你原来对 Hexo 主题做了大量自定义，这部分工作会比较多。我的建议是：

优先选择功能匹配的主题：如 PaperMod 已覆盖大部分常见需求
利用 Hugo 的自定义 CSS/JS：在 assets/css/ 和 layouts/ 中覆盖主题默认样式
渐进式迁移：先把内容跑起来，再逐步调整样式

图片和静态资源

1
2
3
4
5
6
# 复制图片
mkdir -p static/images
cp -r /path/to/hexo/source/images/* static/images/

# 复制其他静态文件
cp -r /path/to/hexo/source/favicon.ico static/

注意：如果原博客图片使用了图床（如七牛云、GitHub 图床等），则无需迁移，Hugo 中 Markdown 的图片链接格式完全相同。

评论系统

如果你原来用了 Valine、Waline、Gitalk 等评论系统：

在 Hugo 主题的模板中找到评论插入位置（通常是 layouts/partials/comments.html）
将原来的评论代码粘贴进去
配置保持不变

搜索功能

Hugo 原生支持生成 JSON 索引，配合前端搜索库即可实现站内搜索：

1
2
[outputs]
  home = ["HTML", "RSS", "JSON"]

PaperMod 主题内置了 Fuse.js 搜索，开箱即用。

六、迁移后的优化建议

1. 启用 Hugo 的缓存

在 GitHub Actions 中配置缓存，加速构建：

1
2
3
4
5
- name: Cache Hugo resources
  uses: actions/cache@v4
  with:
    path: /tmp/hugo_cache
    key: ${{ runner.os }}-hugo-${{ hashFiles('**/hugo.toml') }}

2. 图片懒加载

PaperMod 主题已内置图片懒加载，无需额外配置。

3. 生成站点地图和 RSS

在 hugo.toml 中：

1
2
[outputs]
  home = ["HTML", "RSS", "JSON"]

Hugo 自动生成 /sitemap.xml 和 /index.xml。

4. 配置自定义域名（可选）

在 static/ 目录下创建 CNAME 文件：

echo "blog.yourdomain.com" > static/CNAME

同时在域名服务商处添加 CNAME 记录指向 yourname.github.io。

七、迁移效果对比

指标	Hexo (迁移前)	Hugo (迁移后)
构建时间	~30 秒	< 1 秒
依赖数量	数百个 npm 包	0（单个二进制）
主题更新	停滞	活跃
深色模式	手动配置	自动 + 跟随系统
搜索体验	需额外插件	内置 Fuse.js
移动端适配	良好	优秀
文章数量	225	225（完整迁移）

八、写在最后

迁移博客框架是一件需要权衡的事。如果你目前的博客运行良好，没有明显痛点，未必需要折腾。但如果像我一样，长期被构建慢、依赖多、主题旧等问题困扰，Hugo 确实是一个值得认真考虑的选项。

整个迁移过程，我只花了大约两个周末的时间：

第一个周末：搭建 Hugo 站点、选择主题、配置 GitHub Actions 自动部署
第二个周末：批量迁移文章、处理链接兼容性、微调样式

最终的结果是令人满意的——构建速度提升了数十倍，本地开发体验大幅改善，主题现代化，而且整个工具链更加简洁稳定。

如果你也打算迁移，希望这篇指南能帮你少走弯路。有任何问题，欢迎在评论区留言交流。

参考链接

一、用了5年Hexo，为什么要换？#

1. 构建速度越来越慢#

2. Node.js 依赖地狱#

3. 主题维护停滞#

4. 单文件配置复杂#

二、Hugo vs Hexo vs WordPress：为什么选择 Hugo？#

Hugo#

Hexo#

WordPress#

我的选择理由#

三、Hugo 安装：一步到位的极简体验#

macOS#

Windows#

Linux#

四、从零开始：创建 Hugo 站点并部署到 GitHub Pages#

Step 1：创建新站点#

Step 2：安装主题#

Step 3：配置站点#

Step 4：创建内容#

Step 5：本地预览#

Step 6：GitHub Actions 自动部署#

关键配置说明#

启用 GitHub Pages#

五、从 Hexo 迁移到 Hugo：低成本的完整方案#

迁移前的准备#

1. 备份原博客#

2. 了解差异#

文章迁移#

最简单的方法：直接复制#

需要调整的地方#

批量处理脚本#

保持原有链接不变（重要！）#

方案一：使用 Permalink 规则#

方案二：使用 abbrlink（推荐）#

方案三：生成重定向页面#

主题和样式迁移#

图片和静态资源#

评论系统#

搜索功能#

六、迁移后的优化建议#

1. 启用 Hugo 的缓存#

2. 图片懒加载#

3. 生成站点地图和 RSS#

4. 配置自定义域名（可选）#

七、迁移效果对比#

八、写在最后#