使用 Cursor 完成 Hexo 到 Hugo 博客迁移实践

背景

我的个人博客从 2013 年开始搭建，一直在使用 Github Pages 部署，先后使用过 jekyll、farbox、hexo 等来构建静态博客，折腾过不少次。

本次我决定对博客做如下的改动：

  1. 使用 hugo 来构建静态博客。hexo 管理博客有些麻烦的地方，涉及到很多依赖包的版本管理问题。我之前曾经尝试迁移到 hugo 来管理博客，但发现有些复杂，得需要全面了解 hugo 才能保证兼容性，比如 hexo 和 hugo 中对于博客文章的 url 链接并不相同，如果博客文章之间有超链接的情况，就会导致死链的出现。AI 时代到来后，Cursor 是我一直在深度使用的编程工具，心血来潮决定使用 Cursor 来完成博客的迁移。在整体迁移的过程中，我并未对 hugo 系统有较深的了解，甚至官方的文档都没怎么阅读，仅靠跟 Cursor 的交互就完成了所有的需求。
  2. 放弃域名 kuring.me。博客我一直写的不太多，也没啥流量。再加上 AI 的兴起，我的很多笔记类的博客文章反而更没有必要了。个人的一些感悟也有微信公众号可以承载。我决定弃用之前一直在使用的域名 kuring.me，但放弃域名并不意味着我打算放弃自己的博客。
  3. Github Pages 的访问速度较慢，决定同时寻找其他解决方案来加快博客在国内的访问速度。

迁移工作涉及：

  • 所有已发布文章
  • 草稿文章
  • 静态资源文件（图片、参考文档等）
  • 保持原有 URL 结构不变（SEO 友好）
  • 配置 GitHub Actions 自动部署到 GitHub Pages
  • 配置 Cloudflare Pages 部署（提升中国大陆访问速度）

迁移步骤

需求分析和计划制定

首先，我向 Cursor 描述了完整的迁移需求：

1
2
3
4
5
6
7
8
9

我想将我的博客从 hexo 迁移到 hugo，请帮我完成整体的迁移。

hexo 博客系统的信息：
1. 本地目录：~/github/kuring/kuring.github.io

hugo 博客系统为全新创建：
1. 本地目录：~/github/kuring/hugo
2. 我期望将该项目同步到 github 的 kuring/hugo 的 main 分支上
3. 当 kuring/hugo 的 main 分支提交后自动构建博客，并使用 github actions发布到 kuring/kuring.github.io 的 gh-pages 分支。

Cursor 在 Plan Mode 下分析了需求，并提出了几个关键问题：

  • 主题选择（我选择了 Stack 主题）
  • URL 格式保持策略（我选择保持原格式）

项目初始化

Cursor 自动执行了以下步骤：

1
2
3
4
5

# 初始化 Hugo 项目
hugo new site . --force

# 安装 Stack 主题
git submodule add git@github.com:CaiJimmy/hugo-theme-stack.git themes/hugo-theme-stack

配置文件迁移

Cursor 分析了 Hexo 的 _config.yml，并创建了对应的 hugo.yaml：

  • 站点基本信息（标题、语言等）
  • URL 格式配置（保持 /post/:title/ 格式）
  • Giscus 评论系统配置
  • 分页、标签、分类等设置

内容迁移

这是最复杂的部分了，期间跟 cursor 互动了多次才终于完成。

文章迁移

  • 将所有 markdown 文件从 source/_posts 复制到 content/post
  • 保持原有的目录结构（k8s/、ai/、knowledge-share/ 等）
  • 处理 front matter 格式转换：
    • url: → slug:（Hugo 使用 slug 字段）
    • tags: value → tags: [value]（转换为列表格式）
    • 统一 Tags: 为 tags:

草稿迁移

原先博客中有很多草稿类型的文档，这些文档并不会真正发布，但需要一起迁移到 hugo 中。

  • 复制 source/_drafts 到 content/draft
  • 为所有草稿文件添加 draft: true 标记

静态资源迁移

  • source/images/ → static/images/
  • source/ref/ → static/ref/
  • source/draw.io/ → static/draw.io/
  • source/CNAME → static/CNAME

格式修复

迁移过程中发现了一些格式问题，Cursor 自动创建了 Python 脚本来批量修复：

1
2
3
4
5
6

# 修复 tags 格式的脚本示例
def fix_front_matter(content):
    # 将 url: 转换为 slug:
    # 将 tags: value 转换为 tags: [value]
    # 统一 Tags: 为 tags:
    ...

总共修复了 177 篇发布文章和 4 篇草稿的格式问题。

URL 兼容性保证

这是迁移中最关键的部分。Cursor 确保了：

  • 使用 permalinks.post: /post/:slug/ 保持 URL 格式
  • 对于有 url: 字段的文章，转换为 slug: 字段
  • 所有文章的 URL 与 Hexo 版本完全一致
  • 配置 baseurl: / 支持多平台部署（GitHub Pages 和 Cloudflare Pages）

自动化发布

GitHub Actions 配置

Cursor 创建了 .github/workflows/deploy.yml，实现了：

  • 当 main 分支有 push 时自动触发
  • 使用 Hugo 构建静态站点
  • 跨仓库部署到 kuring/kuring.github.io 的 gh-pages 分支
  • 使用 Personal Access Token 实现跨仓库权限

Cloudflare Pages 配置

由于 GitHub Pages 在中国大陆访问速度较慢，我决定同时配置 Cloudflare Pages 部署。

在配置完成 Cloudflare Pages 后发现，在中国大陆完全无法访问，但在公司网络正好可以访问，而且访问速度还比较快。

多平台部署兼容性检查

需要确保博客配置支持多平台部署：

  • baseurl 配置：设置为 /，让 Hugo 根据实际访问域名自动生成 URL
  • Giscus 评论系统：使用 GitHub 仓库存储评论，两个平台共享同一套评论
  • 硬编码 URL 修复：将代码示例中的绝对 URL 改为相对路径

Cloudflare Pages 配置步骤

  1. 连接 GitHub 仓库：

    • 在 Cloudflare Dashboard 中创建 Pages 项目
    • 连接 kuring/hugo 仓库

  2. 构建设置：

    • Framework preset: Hugo
    • Build command: git submodule update --init --recursive && hugo --minify
    • Build output directory: public
    • 设置 HUGO_VERSION 环境变量为具体版本号（如 0.153.3，不要使用 latest，可以使用 hugo version 命令查看本地使用 hugo 版本）

  3. 自动部署：

    • Production branch: main
    • 启用 Preview deployments（每个 PR 自动创建预览）

多平台部署的优势

  • GitHub Pages：kuring.github.io - 作为主要部署平台
  • Cloudflare Pages：kuring.pages.dev - 提供更快的中国大陆访问速度
  • 共享评论系统：两个平台使用同一套 Giscus 评论，评论数据统一管理
  • URL 兼容性：使用相对路径和正确的 baseurl 配置，确保两个平台都能正常工作

结语

使用 Cursor 较为完美的帮我完成了迁移工作。仅需要在本地执行 git push 命令即可完成博客的发布操作。

如果在没有 AI 辅助的情况下，要完成博客系统的迁移我至少要花上一天的时间，而使用 cursor 前后差不多用了一个小时的时间就完成了，可以说效率大幅度的提升。

美中不足的是博客系统的访问，需要尝试 kuring.github.io 或者 kuring.pages.dev 两个域名，但因为博客与我而言并非高频访问场景，且用户量极少，该问题暂且可以忍受。