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

背景

我的个人博客从 2013 年开始使用 Hexo 搭建，至今已有 256 篇发布的文章和 33 篇草稿。随着时间推移，我逐渐发现 Hugo 在构建速度和功能上的一些优势，因此决定将博客迁移到 Hugo。

迁移工作涉及：

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

这是一个典型的代码迁移任务，非常适合使用 AI 辅助工具来完成。我选择了 Cursor，这是一款基于 AI 的代码编辑器，能够理解上下文并执行复杂的代码重构任务。

为什么选择 Cursor

  1. 上下文理解能力强：Cursor 能够理解整个项目的结构和需求，而不仅仅是单个文件
  2. 计划模式：可以先制定详细的迁移计划，让 AI 理解整体目标后再执行
  3. 批量处理能力：可以一次性处理大量文件的格式转换
  4. 错误修复：遇到问题时，AI 能够快速定位并修复

迁移步骤

1. 需求分析和计划制定

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

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

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

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

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

2. 项目初始化

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

3. 配置文件迁移

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

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

4. 内容迁移

这是最复杂的部分，Cursor 处理了：

4.1 文章迁移

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

4.2 草稿迁移

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

4.3 静态资源迁移

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

5. 格式修复

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

1
2
3
4
5
6

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

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

6. GitHub Actions 配置

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

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

7. Cloudflare Pages 配置

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

7.1 多平台部署兼容性检查

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

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

7.2 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.120.0，不要使用 latest）

  3. 自动部署：

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

7.3 多平台部署的优势

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

详细的 Cloudflare Pages 部署教程请参考：Cloudflare Pages 部署教程

8. URL 兼容性保证

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

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

使用 Cursor 的技巧

1. 明确表达需求

在 Plan Mode 下，详细描述你的需求，包括：

  • 源系统和目标系统
  • 需要保持的特性（如 URL 格式）
  • 部署流程要求

2. 分阶段执行

不要一次性要求完成所有任务，而是：

  • 先让 AI 制定计划
  • 确认计划后再执行
  • 每个阶段完成后验证结果

3. 利用批量处理

对于格式转换这类重复性工作，让 AI 创建脚本批量处理，而不是逐个文件修改。

4. 及时反馈问题

当遇到错误时（如 tags 格式问题），直接告诉 AI 错误信息，它会：

  • 分析问题原因
  • 创建修复脚本
  • 验证修复结果

5. 验证关键点

在迁移过程中，我特别强调了：

  • URL 必须保持不变
  • 目录结构需要保留
  • 草稿需要正确标记

Cursor 在每次修改后都会验证这些关键点。

迁移结果

最终迁移成果：

  • ✅ 256 篇发布文章全部迁移，URL 保持不变
  • ✅ 33 篇草稿文章迁移，正确标记为 draft
  • ✅ 所有静态资源迁移完成
  • ✅ GitHub Actions 自动部署配置完成
  • ✅ Cloudflare Pages 部署配置完成，支持多平台部署
  • ✅ 多平台部署兼容性验证通过（两个平台共享评论系统）
  • ✅ 本地测试通过，站点正常运行

经验总结

  1. AI 辅助工具适合复杂迁移任务：能够理解上下文，处理大量重复性工作
  2. 计划模式很重要：先制定计划，确认后再执行，避免返工
  3. 关键需求要明确：URL 兼容性、目录结构等关键需求要在一开始就明确
  4. 分阶段验证：每个阶段完成后都要验证，及时发现问题
  5. 利用脚本批量处理：对于格式转换等重复工作，让 AI 生成脚本更高效

后续工作

迁移完成后，还需要：

  1. GitHub Pages 部署：

    • 创建 GitHub Personal Access Token 并配置到仓库 Secrets
    • 推送代码到 GitHub
    • 验证 GitHub Actions 自动部署流程

  2. Cloudflare Pages 部署：

    • 在 Cloudflare Dashboard 创建 Pages 项目
    • 连接 GitHub 仓库并配置构建设置
    • 设置 HUGO_VERSION 环境变量（具体版本号，不要使用 latest）
    • 验证自动部署流程

  3. 多平台验证：

    • 验证两个平台的站点都能正常访问
    • 测试搜索功能在两个平台都正常工作
    • 验证 Giscus 评论系统在两个平台都正常工作
    • 对比新旧站点，确保内容一致

详细的部署指南请参考：

结语

使用 Cursor 完成这次迁移，让我深刻体会到 AI 辅助编程的效率。原本需要数天的手工迁移工作，在 AI 的帮助下，几个小时就完成了。更重要的是，AI 能够理解整体需求，确保迁移的完整性和正确性。

对于类似的代码迁移、重构任务，我强烈推荐使用 Cursor 这样的 AI 辅助工具。它不仅能提高效率，还能减少人为错误，确保迁移质量。