如何在Astro博客项目中配置和使用Notion作为CMS

Notion 集成说明文档#

本文档介绍如何在 Astro 博客项目中配置和使用 Notion 作为 CMS。这个实现完全复制了 NotionNext 的主要功能，包括内容获取、缓存、ISR (增量静态再生) 和自动更新机制。

核心功能#

Notion 数据库作为 CMS - 在 Notion 中创作、管理所有博客文章
ISR 机制 - 混合渲染模式，结合静态生成与服务器渲染
缓存系统 - 高性能缓存减少 API 调用
增量更新 - 通过 webhook 和重新验证 API 支持增量更新
完整兼容 - 与博客现有的 Markdown front matter 格式完全兼容

环境变量设置#

在项目根目录创建.env文件，添加以下配置：

# 必填项
NOTION_TOKEN=your_notion_integration_token
NOTION_DATABASE_ID=your_notion_database_id

# 可选配置项
NOTION_CACHE_SECONDS=300           # 缓存时间（秒）
USE_CACHE_IN_DEV=false             # 开发环境是否启用缓存
NOTION_WEBHOOK_SECRET=your_secret   # Webhook密钥
REVALIDATE_TOKEN=NOTION_ISR_SECRET  # 重新验证API的令牌
ENABLE_ISR=true                     # 是否启用ISR功能
NOTION_ACTIVE_USER=your_user_id     # Notion用户ID (某些功能可能需要)
VERCEL_DEPLOY_HOOK_URL=your_hook_url # Vercel部署钩子URL

Notion 数据库配置#

在 Notion 中创建一个数据库，并添加以下属性来匹配博客的 front matter 格式：

属性名称	类型	描述	对应 front matter 字段
Title	标题	文章标题	title
Slug	文本	URL 路径 (可选，不填会从标题生成)	slug
Date	日期	发布日期	published
UpdatedDate	日期	更新日期 (可选)	updated
Description	文本	文章描述	description
Tags	多选	文章标签	tags
Category	选择	文章分类	category
Image	文件 / 链接	封面图片	image
Published	复选框	是否发布	draft (取反)
Draft	复选框	是否为草稿 (可选)	draft
Lang	选择	文章语言 (可选)	lang

Notion API 集成设置#

创建 Notion 集成: https://www.notion.so/my-integrations
获取集成令牌并设置到NOTION_TOKEN环境变量
复制 Notion 数据库 ID (从数据库分享链接获取) 并设置到NOTION_DATABASE_ID环境变量
将您的集成分享给数据库

部署配置#

Vercel 部署#

在 Vercel 中配置所有环境变量
启用混合 SSG+SSR 模式
创建 Vercel 部署钩子并设置到VERCEL_DEPLOY_HOOK_URL环境变量

设置 Webhook (可选但推荐)#

创建自定义 Notion 集成
配置 Webhook 端点: https://your-domain.com/api/notion/webhook
配置回调事件: page_updated, page_created
设置安全密钥并添加到环境变量

使用方法#

一旦配置完成，您可以访问以下页面：

/notion - 显示所有 Notion 文章列表
/notion/post/[slug] - 显示特定文章详情

API 端点#

系统提供以下 API 端点：

GET /api/notion/posts - 获取文章列表，支持分页和筛选
GET /api/notion/post/[slug] - 获取特定文章详情
POST /api/notion/revalidate - 重新验证缓存 (需要提供 REVALIDATE_TOKEN)
POST /api/notion/webhook - 接收 Notion 更新事件

NotionNext vs 本实现#

我们完全移植了 NotionNext 的核心功能，主要区别：

架构差异：使用 Astro 的混合渲染而非 Next.js 的 ISR
性能优化：实现了自定义缓存系统模拟 ISR
兼容性：属性映射适配博客现有 Markdown 格式
部署模式：使用 Vercel 适配器支持边缘函数

故障排除#

如果遇到问题：

检查环境变量配置
确保 Notion 集成已正确分享给数据库
验证数据库结构是否符合上述要求
检查控制台错误日志
尝试通过/api/notion/revalidate端点手动刷新缓存