如何在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端點手動刷新緩存