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 维度 评价 构建速度 极快。基于 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 --> ` ...