在网站开发过程中，迁移到新的技术栈是一个常见的需求，尤其当原有的技术栈在性能、功能或维护性上不再满足需求时。Jekyll 是一款非常流行的 Ruby 编写的静态站点生成器，以其简单和与 GitHub Pages 的紧密集成而闻名。然而，随着项目规模的增长，Jekyll 的构建速度可能成为瓶颈。Hugo，作为一款用 Go 语言编写的静态站点生成器，以其惊人的构建速度和丰富的特性，成为了许多从 Jekyll 迁移出来的首选。本文将分享从 Jekyll 迁移到 Hugo 的一些经验和技巧。
为什么选择迁移？
在决定迁移之前，我们需要明确迁移的动机。对于许多 Jekyll 用户来说，主要原因可能包括：
- 构建速度: Jekyll 的构建速度在处理大量内容时会显著变慢，而 Hugo 通常能实现秒级构建。
- 功能: Hugo 提供了比 Jekyll 更丰富的功能集，例如更强大的模板语言、内置的图像处理、更灵活的 Taxonomy 管理等。
- 部署: 虽然 Jekyll 与 GitHub Pages 集成良好，但 Hugo 的纯静态输出使其能够轻松部署到任何静态托管服务，提供更大的灵活性。
- 开发语言: 如果您熟悉 Go 语言，迁移到 Hugo 会感觉更亲切。
迁移步骤概览
迁移过程大致可以分为以下几个阶段：
- 环境准备: 安装 Hugo。
- 创建 Hugo 项目: 初始化一个新的 Hugo 项目。
- 主题迁移: 选择或重新创建 Hugo 主题。
- 内容迁移: 转换 Markdown 文件和数据文件。
- 配置迁移: 复制和调整站点配置。
- 测试与验证: 在本地预览并进行全面测试。
- 部署: 将生成的静态文件部署到生产环境。
1. 环境准备
首先，确保您已安装 Hugo。您可以从 Hugo 官网下载预编译的二进制文件，或使用包管理器（如 Homebrew、Chocolatey）进行安装。
2. 创建 Hugo 项目
使用 Hugo CLI 创建一个新的项目骨架：
hugo new site my-hugo-site
cd my-hugo-site
3. 主题迁移
这是迁移过程中最关键也可能最耗时的一步。您有几个选择：
- 使用现有的 Hugo 主题: Hugosidebar.com 提供了大量现成的 Hugo 主题。您可以从中选择一个与您 Jekyll 主题风格相似的，或者一个全新的主题。
- 重新创建主题: 如果您对 Jekyll 主题有非常个性化的要求，或者想学习 Hugo 的主题开发，可以根据您的 Jekyll 主题结构，使用 Hugo 的布局系统（
layouts/目录）和模板语言（Go templates）重新创建一个主题。
Jekyll 的主题结构通常包含 _layouts、_includes、_sass、assets 等目录。Hugo 的对应目录是 layouts、layouts/partials、assets。您需要将 Jekyll 的 Liquid 模板转换为 Hugo 的 Go 模板。
Jekyll 常用 Liquid 标签与 Hugo Go 模板的对应示例:
| Jekyll (Liquid) | Hugo (Go Template) | 说明 |
|---|---|---|
{{ page.title }} | {{ .Title }} | 当前页面的标题 |
{{ site.title }} | {{ .Site.Title }} | 站点的标题 |
{{ page.url }} | {{ .RelPermalink }} 或 {{ .Permalink }} | 当前页面的 URL |
{{ page.content }} | {{ .Content }} | 当前页面的内容 |
{% include header.html %} | {{ partial "header.html" . }} | 包含一个 Partial (可重用模板片段) |
| `{{ page.date | date: “%Y-%m-%d” }}` | {{ .Date.Format "2006-01-02" }} |
迁移技巧:
- 从
baseof.html开始: Hugo 的主题通常有一个layouts/_default/baseof.html作为基础布局，其他布局会继承它。您可以先尝试将 Jekyll 的_layouts/default.html转换为 Hugo 的baseof.html。 - 拆分
_includes为partials: Jekyll 的_includes目录中的文件通常可以轻松地转换为 Hugo 的layouts/partials/目录下的文件，并使用{{ partial "partial-name.html" . }}来调用。 - Taxonomies: Jekyll 使用
categories和tags。Hugo 也有categories和tags，并且支持自定义 Taxonomy。您需要调整 Front Matter 中的字段名，并更新模板以正确渲染。
4. 内容迁移
Jekyll 的内容通常是 Markdown 文件，并带有 YAML Front Matter。Hugo 也使用 Markdown 和 Front Matter，但默认支持 TOML、YAML 和 JSON 格式。
- Front Matter 格式: 如果您的 Jekyll 网站使用 YAML Front Matter，Hugo 默认也支持。如果想使用 TOML，需要修改
config.toml中的frontmatterFormat = "toml"。 - 日期格式: Jekyll 的日期通常是
YYYY-MM-DD-title.md。Hugo 的内容文件命名方式更灵活，您可以在 Front Matter 中指定date字段，或者使用YYYY-MM-DD作为文件名前缀（例如2023-10-27-my-post.md）。 - 链接: Jekyll 的永久链接（Permalinks）配置需要仔细检查，并将其映射到 Hugo 的
config.toml中的[permalinks]设置。例如，Jekyll 的/YYYY/MM/DD/post-title/可能会被映射到 Hugo 的/posts/:year/:month/:day/:slug/。 - Markdown 差异: 虽然 Markdown 标准化程度很高，但不同解析器之间可能存在细微差异。Hugo 使用 Goldmark 作为默认 Markdown 处理器，您可能需要检查一些特殊格式的渲染是否与 Jekyll 保持一致。
5. 配置迁移
Jekyll 的 _config.yml 文件需要转换为 Hugo 的配置文件（通常是 config.toml）。
_config.yml (Jekyll) 转换为 config.toml (Hugo):
title:title = "Your Site Title"url:baseURL = "https://your-site.com/"theme: 如果使用主题，在 Hugo 中通过theme = "theme-name"指定。plugins: Hugo 没有插件系统，许多功能由核心或主题提供。exclude: Hugo 中使用ignoreFiles或ignore。defaults: Hugo 的defaults配置提供了更精细的控制。
Front Matter 的默认值: Jekyll 允许在 _config.yml 中设置默认 Front Matter。Hugo 可以在 config.toml 的 [params] 下设置，或者使用 archetypes 目录来管理。
6. 测试与验证
迁移完成后，运行 hugo server 在本地启动开发服务器。仔细检查：
- 页面内容: 确保所有文本、图像、链接都正确显示。
- 导航: 检查菜单、分类、标签链接是否正常工作。
- 样式: 确保网站的 CSS 样式与原 Jekyll 网站一致。
- 特殊功能: 如评论系统、搜索功能等，确保它们已正确迁移和配置。
7. 部署
当您对本地预览满意后，运行 hugo 命令生成静态文件。生成的网站文件通常位于 public/ 目录下。然后，将 public/ 目录下的所有文件上传到您的托管服务器。
总结
从 Jekyll 迁移到 Hugo 是一个值得考虑的选项，特别是当您面临构建速度慢、需要更强大功能或更灵活部署的挑战时。虽然迁移过程需要投入时间和精力，特别是主题的转换，但 Hugo 提供的性能优势和开发体验上的提升，往往能带来长期的收益。通过仔细规划和逐步执行，您可以成功地将您的 Jekyll 网站迁移到 Hugo，并享受其带来的诸多好处。
