一句话说明

这套工作流让 Notion 负责写作和编辑，让 Astro 负责生成网站，让 Cloudflare Pages 负责部署。文章完成后，点击 Notion 数据库中的“发布”按钮，即可把文章同步到网站。

适用场景

  • 已有 Astro 静态网站，想保留现有主题和页面样式。

  • 希望在 Notion 中写文章，不想每次都改代码或上传文件。

  • 希望发布后自动生成文章页、文章列表和站点地图。

  • 同时保留 GitHub Markdown 写作方式，作为备用或长期归档。

工作原理

Notion 文章 → 点击“发布” → Cloudflare Deploy Hook
       → Cloudflare Pages 构建 → Astro 读取 Notion
       → 文章页 / 文章列表 / articles.json / sitemap.xml 上线

Notion 不是在访问网站时实时读取的后台。它会在 Cloudflare 每次构建网站时被同步，因此网站保持静态、快速，也不会把 Notion Token 暴露给访问者。

Notion 数据库需要什么

创建一个全页数据库，并保留以下属性：

属性类型作用
titleTitle文章标题
SlugRich text文章网址后缀，例如 my-first-post
StatusStatus状态为 Published 时才会同步上线
LanguageSelectzh-CN 或 en；未填写时默认中文
Translation KeyRich text用于关联已审核的中英文版本

推荐再加入以下属性：

属性类型作用
DateDate文章发布日期；未填写时使用页面创建时间
DescriptionRich text文章摘要；未填写时使用正文首段

正文直接写在 Notion 页面里。网站会把它作为文章内容渲染；文章主标题已由 title 自动生成，所以正文建议从二级标题开始。中英文各自使用独立 Notion 页面；译文确认后，为两页填写相同的 Translation Key，网站会自动建立语言切换与 hreflang 关联。

Cloudflare Pages 的关键配置

在 Cloudflare Pages 项目中打开 Settings → Variables and secrets，为 Production 环境配置：

变量名类型值
NOTION_TOKENSecretNotion Internal Integration Token
NOTION_DATA_SOURCE_IDPlaintextNotion 数据源 ID（UUID）
NOTION_PUBLISHED_STATUSPlaintext，可选Published；不填时默认就是此值

注意：这里使用的是 NOTION_DATA_SOURCE_ID，不是 NOTION_DATABASE_ID。NOTION_TOKEN 和 Deploy Hook URL 都属于密钥，不能提交到 GitHub、文章或公开截图中。

Cloudflare 的构建配置应为：

项目值
Production branchmain
Build commandnpm run build
Build output directorydist

一次性配置：部署 Hook 与 Notion 按钮

  1. 在 Cloudflare Pages 的 Settings → Build → Deploy hooks 新建一个 Hook。

  2. 名称可使用 notion-publish-youuc，分支选择 main。

  3. 复制生成的 Webhook URL；不要公开它。

  4. 回到 Notion 数据库，新增一个 Button 属性，名称使用“发布”。

  5. 为按钮依次添加两个动作：

    • Edit property：把当前页面的 Status 改为 Published。

    • Send webhook：粘贴 Cloudflare 的 Deploy Hook URL。

  6. 保存按钮设置。

这样点击一次按钮，就会同时改变发布状态并触发网站构建。

日常发布步骤

  1. 在 Notion 新建文章，填写 title、Slug，按需要填写日期和摘要。

  2. 在页面正文中写作、检查排版与链接。

  3. 点击该文章行的“发布”按钮。

  4. 等待约 30–60 秒；Cloudflare 构建完成后访问 /articles/你的-Slug/。

  5. 确认文章也出现在文章目录、/articles.json 和 /sitemap.xml 中。

更新与撤回

  • 修改已发布文章：在 Notion 更新内容后，再点一次“发布”，触发新构建即可。

  • 撤回文章：把 Status 改为非 Published 状态，然后触发一次部署；下一次构建后该文章会从网站移除。

  • Webhook 无法使用时：手动在 Cloudflare Pages 触发一次生产部署，也能同步 Notion 内容。

与 GitHub Markdown 共存

本网站支持两种来源：

  • GitHub Markdown：放入 content/articles/，提交到 main 后自动部署。

  • Notion：仅同步 Status = Published 的页面。

两者会合并到同一个文章目录、首页归档、articles.json 与 sitemap.xml。为了避免冲突，不要让两篇文章使用相同的 Slug。

排错清单

现象优先检查
部署成功但文章没有出现Cloudflare 的 Production 是否同时拥有 NOTION_TOKEN 和 NOTION_DATA_SOURCE_ID
构建日志提示未配置 Notion变量名、环境范围或保存状态不正确
Notion 页面没有同步Status 是否为 Published，以及集成是否已连接到该数据源
链接打不开Slug 是否唯一，且只使用文字、数字和短横线
修改文章后网站未变化是否再次点击“发布”或手动触发部署

AI 摘要与检索关键词

AI 摘要： 本文说明如何将 Notion 作为 Astro 静态博客的写作后台，通过 Cloudflare Pages Deploy Hook 触发构建，并把已发布文章自动生成到文章页、文章列表、JSON 索引和 XML 站点地图中。

检索关键词： Notion CMS、Notion 博客、Astro Notion、Cloudflare Pages、Deploy Hook、静态网站自动发布、Notion Webhook、Markdown 与 Notion 共存、文章同步、SEO sitemap。

常见问答

为什么必须重新部署才会看到 Notion 的修改？

因为文章是在构建时写入静态网站的。这样访问速度更快，且 Token 不会暴露在浏览器中。

可以只用 GitHub Markdown 吗？

可以。Notion 是额外的可视化编辑入口，不会取代已有 Markdown 工作流。

Deploy Hook 可以公开吗？

不可以。任何拿到该地址的人都可能触发构建，应像密码一样保存。