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

Wed, 29 Apr 2026 17:41:22 +0000

从 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 -->`	`

Hugo on XieJava's blog