从Hexo到Hugo：我的博客迁移之旅与完整实践指南

从 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

Hexo

WordPress

我的选择理由

总结：如果你追求极致的构建速度、零依赖、现代化主题，并且习惯用 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

关键配置说明

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

启用 GitHub Pages

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

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

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

迁移前的准备

1. 备份原博客

1

cp -r myhexo/myblog myhexo/myblog-backup

2. 了解差异

好消息是：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/

需要调整的地方