我一直习惯用 Notion 写博客，它的编辑体验的确非常好：支持丰富的文本格式，能随时随地编辑，团队协作也十分方便。不过，直接用 Notion 的公开页面（Public Pages）来发布博客，却有几个痛点：

  1. 性能问题：Notion 公开页面的加载速度很慢，尤其在国内访问时，速度非常慢。此外，页面的样式和布局几乎无法定制，看起来不像一个真正的博客。

  2. SEO 不友好：Google 索引的链接不是我指定的 slug，而是 Notion 自动生成的一长串随机字符，这对搜索引擎优化（SEO）是致命的。

  3. 价格昂贵：如果想在 Notion 使用自定义域名，每月需要 10 美元，没有任何折扣。

相比之下，Hugo + Cloudflare Pages 能完美解决这些问题。Hugo 生成的静态网站加载飞快，配合 Cloudflare 遍布全球的 CDN 节点，国内访问速度也十分理想。最关键的是，这套方案完全免费，同时能让我完全设计网站的样式和结构。

我的核心目标是：让整个配置过程尽可能简单。 理想情况下，用户只需 fork 项目，添加几个必要的 Access Token，就能实现从 Notion 到博客的全自动化发布流程。

项目功能设计

这个项目的核心逻辑很直接：从 Notion 数据库读取文章，将其转换为 Hugo 所需的 Markdown 格式，最后自动构建并部署到 Cloudflare Pages。

整个工作流如下：Notion Database → GitHub Actions → Hugo Site → Cloudflare Pages

我的文章内容通常比较复杂，项目需要处理各种格式的转换，包括但不限于：

  • 数学公式（KaTeX）

  • 表格

  • Mermaid 图表

  • 多列图文布局

  • 音频和视频

  • 引用块（Blockquotes）

  • 高亮提示框（Callouts）

  • 网页书签（Web Bookmarks）

对于图片、音视频等媒体文件，项目会自动下载并缓存到本地，避免每次构建时重复下载，且不依赖Notion存储图片、音频和视频等。

所有自动化任务都通过 GitHub Actions 完成。你可以设置定时任务（例如每隔几小时自动同步一次），也可以在需要时手动触发。

半天，我如何完成这个开源项目

1. AI 生成初始框架

我首先向 Claude Opus 4 详细描述了我的需求，它很快就为我规划了项目的整体架构。

准备工作：

  • Notion Integration Token：用于 API 调用

  • GitHub 仓库：用于托管代码和触发 Actions

  • Cloudflare 账号和 API Token：用于部署

  • Cloudflare Pages 项目：最终的网站托管平台

Notion 设置步骤：

  1. 访问 https://www.notion.so/my-integrations 创建一个新的 Integration。

  2. 保存生成的 Internal Integration Token。

  3. 创建一个博客专用的数据库，并确保包含以下字段：

    • Title (标题)
    • Slug (URL 路径)
    • Date (发布日期)
    • Tags (标签)
    • Published (Checkbox，用于控制是否发布)
    • Content (正文内容)

  4. 将刚刚创建的 Integration 连接到这个数据库。

Claude Opus 4 很快给出了清晰的项目结构：

your-blog-repo/
├── .github/
│   └── workflows/
│       └── deploy.yml
├── scripts/
│   ├── notion-to-hugo.js
│   └── deploy-to-cloudflare.js
├── content/
│   └── posts/
├── themes/
├── config.toml
├── package.json
└── .gitignore

在实现语言上，我最终选择了 Python。虽然 AI 可以写任何语言，但选择自己最熟悉的，才能在出问题时快速排查，而不是被 AI 牵着鼻子走。

Claude Opus 4 的初步方案考虑得相当周全，生成的代码框架在添加了 Notion Auth Token 等配置后，基本就能直接跑起来。

2. 迭代调试与问题修复

然而，AI 生成的代码并非完美无瑕。初始版本遇到了一些无法转换的格式，我把报错信息直接丢给 Claude Opus 4，它会根据错误来修改代码。例如，为了正确渲染数学公式，就需要对 KaTeX 语法进行特殊处理。

另一个大问题是：我不确定脚本是否真的成功连接到了 Notion API 并读取了数据。于是，我让 Claude Opus 4 添加一个数据库测试功能，运行时先打印出数据库的属性和文章数量，这样就能立刻确认连接状态。

3. 细节打磨与完善

框架能跑通后，接下来就是细节的打磨。结合 GPT-5 和 Claude Opus 4，逐一解决以下问题：

  • 生成 Hugo 配置：让 AI 帮我创建一份完整的 Hugo 配置文件 (config.toml)。

  • README.md：我只提供了 License，AI 就根据代码逻辑生成非常详尽的项目文档。

  • 处理内部链接：将 Notion 页面间的跳转链接，正确转换为 Hugo 的站内链接格式。

  • 处理锚点链接：文章内部的目录跳转（#开头的链接）也需要特殊处理。

  • 修复渲染问题：部分复杂公式无法正确渲染，需要微调转换逻辑。

  • 适配媒体宽度：确保视频和音频能在页面上以合适的宽度显示。

  • 解决 GIF 问题：修复了 GIF 动图在转换后不动的问题。

4. 挑战与思考

有些问题是 AI 也暂时搞不定的。比如嵌入 Google Slides 链接，我和 AI 来回尝试了多种方案，效果都不理想，最后我选择暂时放弃这个功能。修改 AI 生成的代码时要格外小心，不要全盘ACCEPT。 Claude Opus 4 和 GPT-5 经常会引入一些冗余甚至错误的代码。

我还遇到了一个典型的“模型知识截止日期”问题。AI 最初建议的 cloudflare/pages-action 部署工具其实已经被废弃了（deprecated）。我只需要把这条废弃警告发给 AI，它就能立刻理解并帮我切换到最新的 wrangler-action。

此外，像“如何创建 Cloudflare Pages 项目”、“如何配置 Auth Token”、“如何设置 GitHub Secrets”这类操作步骤，我也全部交给 AI 来写。AI 生成的文档比我自己写的要详细得多，也更规范。

5. 我的开发技巧总结

在整个开发过程中，我逐渐形成了一套高效的工作流：

  1. 清晰描述：向 AI 清晰地描述需求或抛出问题。

  2. 快速测试：立刻测试 AI 生成的代码。

  3. 精确反馈：发现问题后，将具体的错误信息、日志、甚至自己的猜测一起反馈给 AI。

  4. 谨慎审查：Review AI 的修改建议，只接受合理的部分，保持对代码的控制权。

  5. 及时提交：一旦某个功能模块达到预期，就立刻 commit。使用 Cursor 的 "Generate Commit Message" 功能，比自己写的详细得多。

核心思路是：先用最强的 AI 搭建整体框架，再结合多个 AI 工具雕琢细节。

通过这种方式，我在半天之内就完成了一个功能完整的开源项目：notion-hugo-blog。

如何使用？

使用这个项目非常简单，整个过程无需配置本地环境，完全通过线上操作完成：

  1. Fork 项目到你自己的 GitHub 仓库。

  2. 在 Notion 中创建 Integration 并获取 Token。

  3. 按照模板创建你的博客数据库，并添加必要的字段，将数据库添加到Integration的Access中。

  4. 创建并配置 Cloudflare Pages 项目。

  5. 在你的 GitHub 仓库中配置 Secrets（例如 Notion Token）。

  6. 完成以上步骤后，每6个小时（或手动触发 Action）即可完成自动部署。

总结

这个项目很好地证明了，利用 AI 辅助，可以极大地加速项目开发进程。我的关键心得是：

  • 清晰定义需求是第一步，让 AI 为你生成合理的初始框架。

  • 选择自己熟悉的技术栈，始终保持对代码的最终掌控力。

  • 高频次地测试和验证，用精确的反馈引导 AI 修复问题。

  • 保持独立思考，不盲目接受 AI 的所有建议。

项目已经开源，欢迎使用和贡献代码： https://github.com/trainsh/notion-hugo-blog