从 0 到上线：一步一步搭建 Notion + Next.js + Netlify 博客

123node --version
git --version
npm --version

123456789Notion 写作
   ↓
同步脚本读取数据库和正文区块
   ↓
生成 content/notion-snapshot.json
   ↓
Next.js 根据快照生成首页和文章页
   ↓
Netlify 构建并发布到 CDN

123npx create-next-app@latest notion-blog --typescript --eslint --app --no-src-dir --import-alias "@/*"
cd notion-blog
npm install

12npm install katex highlight.js
npm install -D vinext vite nitro @vitejs/plugin-react @vitejs/plugin-rsc

12345678910{
  "scripts": {
    "dev": "vinext dev",
    "sync:notion": "node scripts/sync-notion.mjs",
    "build": "node scripts/sync-notion.mjs && vinext build",
    "build:netlify": "node scripts/sync-notion.mjs && vite build",
    "start": "vinext start",
    "lint": "eslint . --ignore-pattern dist --ignore-pattern .next --ignore-pattern .netlify"
  }
}

1234567import vinext from "vinext";
import { nitro } from "nitro/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [vinext(), nitro({ preset: "netlify" })],
});

1npm run dev

12345678title: Hello Notion
slug: hello-notion
status: Published
type: Post
summary: 我的第一篇 Notion 博客文章
date: 今天
category: 技术分享
tags: Notion, 建站

11e34cfb3-d63d-8143-9a2a-000b424944ba

123NOTION_TOKEN=secret_xxxxxxxxxxxxxxxxx
NOTION_ZH_DATA_SOURCE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
NEXT_PUBLIC_SITE_URL=http://localhost:3000

123456789NOTION_TOKEN=
NOTION_ZH_DATA_SOURCE_ID=
NEXT_PUBLIC_SITE_URL=
NETLIFY_BUILD_HOOK=
NOTION_WEBHOOK_SECRET=
NEXT_PUBLIC_GISCUS_REPO=
NEXT_PUBLIC_GISCUS_REPO_ID=
NEXT_PUBLIC_GISCUS_CATEGORY=Announcements
NEXT_PUBLIC_GISCUS_CATEGORY_ID=

123.env
.env.local
.env.*.local

123mkdir scripts
mkdir content
mkdir public/notion

1New-Item -ItemType Directory -Force scripts, content, public/notion

12345{
  "generatedAt": null,
  "latestEditedAt": null,
  "posts": []
}

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142import { mkdir, readFile, writeFile } from "node:fs/promises";
import { join } from "node:path";

const API = "https://api.notion.com/v1";
const VERSION = "2026-03-11";
const token = process.env.NOTION_TOKEN;
const dataSourceId = process.env.NOTION_ZH_DATA_SOURCE_ID;
const snapshotPath = join(process.cwd(), "content", "notion-snapshot.json");

async function oldSnapshot() {
  try {
    return JSON.parse(await readFile(snapshotPath, "utf8"));
  } catch {
    return { generatedAt: null, latestEditedAt: null, posts: [] };
  }
}

if (!token || !dataSourceId) {
  const snapshot = await oldSnapshot();
  console.log(`[notion-sync] no credentials; using ${snapshot.posts.length} cached posts`);
  process.exit(0);
}

async function notion(path, init = {}) {
  for (let attempt = 0; attempt < 4; attempt += 1) {
    const response = await fetch(`${API}${path}`, {
      ...init,
      signal: AbortSignal.timeout(20000),
      headers: {
        Authorization: `Bearer ${token}`,
        "Notion-Version": VERSION,
        "Content-Type": "application/json",
        ...init.headers,
      },
    });

    if (response.ok) return response.json();
    if (response.status !== 429 && response.status < 500) {
      throw new Error(`Notion ${response.status}: ${path}`);
    }
    await new Promise((resolve) => setTimeout(resolve, 400 * 2 ** attempt));
  }
  throw new Error(`Notion retry exhausted: ${path}`);
}

function prop(properties, name) {
  const key = Object.keys(properties ?? {}).find(
    (item) => item.toLowerCase() === name.toLowerCase(),
  );
  return key ? properties[key] : undefined;
}

function text(value) {
  return [...(value?.title ?? []), ...(value?.rich_text ?? [])]
    .map((item) => item.plain_text ?? "")
    .join("")
    .trim();
}

function selected(value) {
  return value?.select?.name ?? value?.status?.name ?? "";
}

function mapPage(page) {
  const p = page.properties;
  const title = text(prop(p, "title"));
  const slug = text(prop(p, "slug"));
  const status = selected(prop(p, "status"));
  const type = selected(prop(p, "type"));

  if (!title || !slug || status !== "Published" || type !== "Post") return null;

  return {
    id: page.id,
    notionId: page.id,
    title,
    slug: slug.replace(/^\/+|\/+$/g, ""),
    description: text(prop(p, "summary")) || "一篇来自 Notion 的文章。",
    publishedAt: prop(p, "date")?.date?.start?.slice(0, 10)
      ?? page.last_edited_time.slice(0, 10),
    updatedAt: page.last_edited_time,
    category: selected(prop(p, "category")) || "未分类",
    tags: (prop(p, "tags")?.multi_select ?? []).map((tag) => tag.name),
    featured: prop(p, "featured")?.checkbox ?? false,
  };
}

async function queryPosts() {
  const pages = [];
  let cursor;
  do {
    const result = await notion(`/data_sources/${dataSourceId}/query`, {
      method: "POST",
      body: JSON.stringify({
        page_size: 100,
        ...(cursor ? { start_cursor: cursor } : {}),
      }),
    });
    pages.push(...result.results);
    cursor = result.has_more ? result.next_cursor : undefined;
  } while (cursor);

  return pages.map(mapPage).filter(Boolean);
}

async function children(blockId) {
  const blocks = [];
  let cursor;
  do {
    const query = new URLSearchParams({ page_size: "100" });
    if (cursor) query.set("start_cursor", cursor);
    const result = await notion(`/blocks/${blockId}/children?${query}`);
    blocks.push(...result.results);
    cursor = result.has_more ? result.next_cursor : undefined;
  } while (cursor);

  for (const block of blocks) {
    if (block.has_children) block.children = await children(block.id);
  }
  return blocks;
}

try {
  const posts = await queryPosts();
  for (const post of posts) post.blocks = await children(post.notionId);

  posts.sort((a, b) => new Date(b.publishedAt) - new Date(a.publishedAt));
  const generatedAt = new Date().toISOString();
  const latestEditedAt = posts.map((post) => post.updatedAt).sort().at(-1) ?? null;

  await mkdir(join(process.cwd(), "content"), { recursive: true });
  await writeFile(
    snapshotPath,
    JSON.stringify({ generatedAt, latestEditedAt, posts }, null, 2) + "\n",
    "utf8",
  );
  console.log(`[notion-sync] generated ${posts.length} posts`);
} catch (error) {
  const snapshot = await oldSnapshot();
  if (!snapshot.posts.length) throw error;
  console.warn(`[notion-sync] failed; preserving ${snapshot.posts.length} cached posts`);
}

1npm run sync:notion

12345678910111213141516171819202122232425262728293031323334import snapshot from "@/content/notion-snapshot.json";

export type Post = {
  id: string;
  title: string;
  slug: string;
  description: string;
  publishedAt: string;
  updatedAt: string;
  category: string;
  tags: string[];
  featured: boolean;
  blocks: NotionBlock[];
};

export type NotionBlock = {
  id: string;
  type: string;
  has_children?: boolean;
  children?: NotionBlock[];
  [key: string]: unknown;
};

const posts = (snapshot.posts ?? []) as Post[];

export async function getAllPosts() {
  return [...posts].sort(
    (a, b) => new Date(b.publishedAt).getTime() - new Date(a.publishedAt).getTime(),
  );
}

export async function getPostBySlug(slug: string) {
  return posts.find((post) => post.slug === slug) ?? null;
}

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657import type { ReactNode } from "react";
import type { NotionBlock } from "@/lib/notion";

function richText(items: any[] = []) {
  return items.map((item, index) => {
    let value: ReactNode = item.plain_text ?? item.text?.content ?? "";
    const a = item.annotations ?? {};
    if (a.code) value = <code>{value}</code>;
    if (a.bold) value = <strong>{value}</strong>;
    if (a.italic) value = <em>{value}</em>;
    if (a.strikethrough) value = <s>{value}</s>;
    const href = item.href ?? item.text?.link?.url;
    if (href) value = <a href={href}>{value}</a>;
    return <span key={index}>{value}</span>;
  });
}

function payload(block: NotionBlock): any {
  return block[block.type];
}

function renderBlock(block: NotionBlock): ReactNode {
  const data = payload(block) ?? {};
  const text = richText(data.rich_text);
  const nested = block.children?.map(renderBlock);

  switch (block.type) {
    case "paragraph":
      return <p key={block.id}>{text}{nested}</p>;
    case "heading_1":
      return <h2 key={block.id}>{text}</h2>;
    case "heading_2":
      return <h3 key={block.id}>{text}</h3>;
    case "heading_3":
      return <h4 key={block.id}>{text}</h4>;
    case "bulleted_list_item":
      return <li key={block.id}>{text}{nested}</li>;
    case "numbered_list_item":
      return <li key={block.id}>{text}{nested}</li>;
    case "quote":
      return <blockquote key={block.id}>{text}{nested}</blockquote>;
    case "code":
      return <pre key={block.id}><code>{data.rich_text?.map((x: any) => x.plain_text).join("")}</code></pre>;
    case "divider":
      return <hr key={block.id} />;
    case "image": {
      const src = data.file?.url ?? data.external?.url;
      return src ? <img key={block.id} src={src} alt="" loading="lazy" /> : null;
    }
    default:
      return nested?.length ? <div key={block.id}>{nested}</div> : null;
  }
}

export function NotionContent({ blocks }: { blocks: NotionBlock[] }) {
  return <div className="notion-content">{blocks.map(renderBlock)}</div>;
}

123456789101112131415161718192021222324252627import Link from "next/link";
import { getAllPosts } from "@/lib/notion";

export const dynamic = "force-static";

export default async function Home() {
  const posts = await getAllPosts();

  return (
    <main className="container">
      <header className="hero">
        <p>Personal Blog</p>
        <h1>写技术，也记录技术之外的生活。</h1>
      </header>

      <section>
        {posts.map((post) => (
          <article key={post.id} className="post-card">
            <p>{post.category} · {post.publishedAt}</p>
            <h2><Link href={`/posts/${post.slug}`}>{post.title}</Link></h2>
            <p>{post.description}</p>
          </article>
        ))}
      </section>
    </main>
  );
}

1234567891011121314151617181920212223242526272829import { notFound } from "next/navigation";
import { NotionContent } from "@/components/NotionContent";
import { getAllPosts, getPostBySlug } from "@/lib/notion";

export async function generateStaticParams() {
  return (await getAllPosts()).map((post) => ({ slug: post.slug }));
}

export default async function PostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPostBySlug(slug);
  if (!post) notFound();

  return (
    <main className="article">
      <a href="/">← 返回首页</a>
      <header>
        <p>{post.category} · {post.publishedAt}</p>
        <h1>{post.title}</h1>
        <p>{post.description}</p>
      </header>
      <NotionContent blocks={post.blocks} />
    </main>
  );
}

1234567891011121314151617181920:root {
  color: #22211f;
  background: #f4f1ea;
  font-family: Inter, system-ui, sans-serif;
}

body { margin: 0; }
a { color: inherit; }
.container, .article { width: min(760px, calc(100% - 40px)); margin: 0 auto; }
.hero { padding: 96px 0 64px; }
.hero h1 { font: 500 clamp(42px, 8vw, 80px)/1.04 Georgia, serif; }
.post-card { padding: 32px 0; border-top: 1px solid #cbc5ba; }
.article { padding: 72px 0 120px; }
.article > header { margin: 48px 0 64px; }
.article h1 { font: 500 clamp(40px, 7vw, 72px)/1.08 Georgia, serif; }
.notion-content { font-size: 18px; line-height: 1.85; }
.notion-content h2, .notion-content h3 { margin-top: 2.4em; font-family: Georgia, serif; }
.notion-content pre { overflow: auto; padding: 20px; color: #eee; background: #1e1f22; border-radius: 12px; }
.notion-content img { display: block; max-width: 100%; height: auto; margin: 32px 0; border-radius: 12px; }
.notion-content blockquote { margin-left: 0; padding-left: 20px; border-left: 2px solid #8c806c; }

1npm run dev

12http://localhost:3000
http://localhost:3000/posts/hello-notion

12npm run lint
npm run build

123456git init
git add .
git commit -m "feat: build Notion powered blog"
git branch -M main
git remote add origin git@github.com:你的用户名/notion-blog.git
git push -u origin main

123Build command: npm run build:netlify
Publish directory: dist
Node version: 22

12345678910[build]
  command = "npm run build:netlify"
  publish = "dist"

[build.environment]
  NODE_VERSION = "22.14.0"
  NITRO_PRESET = "netlify"

[functions]
  directory = "netlify/functions"

123NOTION_TOKEN=你的真实Token
NOTION_ZH_DATA_SOURCE_ID=你的DataSourceID
NEXT_PUBLIC_SITE_URL=https://Netlify分配的域名

1[notion-sync] generated 1 posts

1Project configuration → Build & deploy → Build hooks

1NETLIFY_BUILD_HOOK=https://api.netlify.com/build_hooks/xxxxxxxx

12345678910111213141516171819202122232425262728293031323334353637383940414243import { createHmac, timingSafeEqual } from "node:crypto";

const accepted = new Set([
  "page.created",
  "page.content_updated",
  "page.properties_updated",
  "page.deleted",
  "page.undeleted",
]);

function validSignature(raw, signature) {
  const secret = process.env.NOTION_WEBHOOK_SECRET;
  if (!secret || !signature) return false;
  const expected = `sha256=${createHmac("sha256", secret).update(raw).digest("hex")}`;
  return signature.length === expected.length
    && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

export default async function handler(request) {
  if (request.method !== "POST") return new Response("Method not allowed", { status: 405 });

  const raw = await request.text();
  const payload = JSON.parse(raw);

  // Notion 创建订阅时会先发送验证令牌。
  if (payload.verification_token) {
    console.log(`[notion-webhook] verification_token=${payload.verification_token}`);
    return Response.json({ ok: true, verification_token: payload.verification_token });
  }

  if (!validSignature(raw, request.headers.get("x-notion-signature"))) {
    return new Response("Invalid signature", { status: 401 });
  }

  if (accepted.has(payload.type)) {
    const response = await fetch(process.env.NETLIFY_BUILD_HOOK, { method: "POST" });
    if (!response.ok) return new Response("Build hook failed", { status: 502 });
  }

  return Response.json({ ok: true });
}

export const config = { path: "/api/notion-webhook" };

1https://你的域名/api/notion-webhook

12345{
  "generatedAt": null,
  "latestEditedAt": null,
  "postCount": 0
}

12Notion 最近 Published Post 的 last_edited_time
线上 notion-snapshot-meta.json 的 latestEditedAt

123export const config = {
  schedule: "*/30 * * * *",
};

1NEXT_PUBLIC_SITE_URL=https://你的正式域名

1234NEXT_PUBLIC_GISCUS_REPO=用户名/blog-comments
NEXT_PUBLIC_GISCUS_REPO_ID=R_xxxxxxxxx
NEXT_PUBLIC_GISCUS_CATEGORY=Announcements
NEXT_PUBLIC_GISCUS_CATEGORY_ID=DIC_xxxxxxxxx