从 Jekyll 迁移到 Hugo

May 20, 2026

从 Jekyll 迁移到 Hugo

许多用户选择从 Jekyll 迁移到 Hugo，通常是出于对性能、灵活性或特定功能的需求。Hugo 以其闪电般的构建速度和更现代化的开发体验，成为了一个极具吸引力的替代方案。本指南将帮助您完成从 Jekyll 到 Hugo 的迁移过程。

在开始迁移之前，请确保您已经安装了 Hugo。您可以在 Hugo 官网上找到详细的安装说明。

Jekyll 的内容通常存储在 Markdown 文件中，并带有 YAML Front Matter。Hugo 也广泛使用 Markdown 和 TOML/YAML/JSON Front Matter。

Front Matter 格式:
- Jekyll: 通常使用 YAML Front Matter，以 --- 分隔。
- Hugo: 默认使用 TOML Front Matter，以 +++ 分隔。您也可以配置 Hugo 使用 YAML (---) 或 JSON ({}).
- 迁移: 您需要将 Jekyll 的 YAML Front Matter 转换为 Hugo 的 TOML Front Matter。例如：
  Jekyll:
```
---
layout: post
title: "我的第一篇文章"
date: 2023-10-26
categories: [生活, 随笔]
---
```
  Hugo (TOML):
```
+++
layout = "post" # Hugo 通常不需要 explicit layout for posts if using archetypes
title = "我的第一篇文章"
date = 2023-10-26
categories = ["生活", "随笔"]
+++
```
- 工具: 可以使用脚本（如 Python 或 sed）来批量转换 Front Matter。
文件结构:
- Jekyll: 内容通常放在 _posts/ 目录下，文件名格式为 YYYY-MM-DD-title.md。
- Hugo: 内容放在 content/ 目录下。对于博客文章，通常放在 content/posts/ 目录下，文件名可以是 title.md 或 YYYY-MM-DD-title.md。Hugo 会自动处理日期。
- 迁移: 将 Jekyll 的 _posts/ 目录内容复制到 Hugo 的 content/posts/ 目录下。如果文件名包含日期，Hugo 会自动识别。
图片和静态文件:
- Jekyll: 图片和静态文件通常放在 assets/ 或 images/ 目录下。
- Hugo: 图片和静态文件应放在 static/ 目录下。
- 迁移: 将 Jekyll 的图片和静态文件目录内容复制到 Hugo 的 static/ 目录下。

这是迁移中最具挑战性的部分。

模板语言:
- Jekyll: 使用 Liquid 模板语言。
- Hugo: 使用 Go 模板语言。
- 迁移: 您需要将 Jekyll 的 Liquid 模板逐一转换为 Hugo 的 Go 模板。这可能需要一些学习和适应。例如，访问变量的方式、条件判断、循环结构等都有所不同。
布局结构:
- Jekyll: 通常使用 _layouts/, _includes/ 目录。
- Hugo: 使用 layouts/ 目录，其中包含 _default/ (用于通用列表和单页模板)，以及 partials/ (用于可重用片段)。
- 迁移: 根据 Hugo 的布局结构重新组织您的模板文件。
配置:
- Jekyll: 使用 _config.yml 文件。
- Hugo: 使用 config.toml (或 config.yaml/config.json) 文件。
- 迁移: 将 Jekyll 的配置项迁移到 Hugo 的配置文件中。注意配置项的名称和结构可能不同。

如果您的 Jekyll 网站使用了 Liquid 的 {% include %} 或自定义的 Liquid 标签来嵌入内容，您需要将其转换为 Hugo 的短代码。Hugo 的短代码提供了更强大的功能和更灵活的使用方式。

Jekyll 拥有丰富的插件生态系统。Hugo 默认不依赖插件，而是通过内置功能和短代码来实现类似的功能。您需要查找 Hugo 的内置功能或第三方短代码来替代 Jekyll 的插件。

在完成迁移后，务必在本地使用 hugo server 命令预览您的网站，检查所有页面、链接、图片和功能是否正常工作。对比迁移前后的内容和样式，确保一切都符合预期。

一旦确认无误，您就可以使用 hugo 命令生成静态文件，并按照您常用的部署方式将文件上传到服务器或托管平台。

通过细致的规划和逐步的实施，从 Jekyll 迁移到 Hugo 是一个可行的过程，并且通常会带来显著的性能提升和更优的开发体验。