返回博客
Next.jsSupabaseGitHub ActionsMarkdownWebhookSSRISRSEO

Next.js 内容系统实践:GitHub Actions 同步 Markdown 到 Supabase,并通过 Webhook 实现 SSR + ISR 刷新

本文记录一种适合内容型网站的工程方案:使用 Git 管理 Markdown,通过 GitHub Actions 校验并同步到 Supabase,再由 Webhook 触发 Next.js revalidate,实现可维护的 SSR + ISR 内容更新链路。

RaytonX
4 min read

在做内容型网站时,最容易低估的不是页面渲染,而是内容从“写完”到“稳定出现在页面上”的整条链路。

如果只是一个博客,把 Markdown 放在代码仓里一起部署就够了。但当内容逐渐变多,或者需要多人协作、后台检索、标签筛选、SEO 页面更新时,单纯依赖本地文件会开始遇到一些问题:

  • 内容更新是否每次都要重新部署?
  • Markdown 的 frontmatter 是否可靠?
  • 页面列表、搜索、标签页是否需要读取结构化数据?
  • 旧页面更新后,缓存如何及时刷新?
  • 新内容发布后,如何避免页面和数据库状态不一致?

我们在内容系统里采用过一种相对克制的方案:

使用 Git 管理 Markdown 源文件,通过 GitHub Actions 做校验和同步,将结构化内容写入 Supabase;Next.js 页面从 Supabase 读取内容,结合 SSR 与 ISR 提供可缓存、可刷新的页面。

这套方案不是为了替代完整 CMS,而是为了在小团队、内容站、技术博客和轻量知识库场景里,兼顾写作体验、工程可控性和 SEO。

整体架构

这条链路可以拆成四个部分:

Markdown 仓库
  │
  │ git push
  ▼
GitHub Actions
  - 读取 Markdown
  - 校验 frontmatter
  - 转换结构化字段
  - upsert 到 Supabase
  │
  │ 调用 Webhook
  ▼
Next.js Revalidate API
  - revalidateTag
  - revalidatePath
  │
  ▼
Next.js 页面
  - SSR 读取最新内容
  - ISR 缓存稳定页面

核心思路是:Git 作为内容事实源,Supabase 作为线上查询与索引层,Next.js 负责渲染与缓存。

这样做以后,内容仍然可以通过 Markdown 编写和 Code Review 管理;上线后页面不需要每次重新部署,内容也不只是作为文件被渲染,而是变成可以被查询、关联和复用的数据。

为什么要同步到 Supabase

如果只是做一个普通博客,直接读取 content/blog/*.mdx,或者在服务端通过 GitHub API 拉取 Markdown,都是合理方案。

这类方案足够简单,也不需要额外引入数据库同步流程。对文章数量不多、只需要渲染详情页和列表页的官网来说,直接使用文件或 GitHub API 往往更合适。

选择同步到 Supabase,不是因为“展示 Markdown”本身需要数据库,而是因为内容后续会进入更多使用场景:

  1. 列表查询更方便
    标签、分类、发布日期、语言、状态等字段可以直接通过 SQL 查询,不需要每次扫描文件系统。

  2. 可以利用 PostgreSQL 的内容能力
    内容进入 PostgreSQL 后,可以使用索引、全文检索、关联查询、排序、过滤和统计能力。比如根据标签聚合文章、生成相关文章、按业务对象关联指南与案例等。

  3. 更适合作为 LLM 的知识来源
    如果后续要做智能问答、内容助手或 RAG,LLM 不应该临时去读散落的 Markdown 文件。更稳妥的方式是让文章正文、摘要、标签、语言、发布时间等字段先进入数据库,再基于 PostgreSQL 或 pgvector 做检索和召回。

  4. 内容状态更清晰
    可以区分 draft、published、archived 等状态,避免未发布内容进入线上页面。

  5. 运行时依赖更可控
    线上页面读取 Supabase,而不是每次调用 GitHub API,减少外部网络依赖,也避免 GitHub API 的鉴权、限流和网络波动直接影响页面请求。

所以这里的取舍是:GitHub 负责内容创作和版本管理,Supabase 负责把内容变成可查询、可检索、可被 LLM 使用的数据资产。

Markdown 内容格式

每篇文章保留普通 MDX/frontmatter 结构:

---
title: Next.js 内容系统实践
slug: nextjs-content-system
date: 2026-07-16
tags: ['Next.js', 'Supabase', 'ISR']
summary: 记录一种基于 GitHub Actions 与 Supabase 的内容发布方案。
status: published
---

正文内容...

我们会把 frontmatter 里的结构化字段写入 Supabase 的普通列,把正文写入 content_markdown 字段。

一个简化后的表结构可以是这样:

create table blog_posts (
  id uuid primary key default gen_random_uuid(),
  slug text not null unique,
  title text not null,
  summary text,
  content_markdown text not null,
  tags text[] not null default '{}',
  status text not null default 'draft',
  published_at timestamptz,
  updated_at timestamptz not null default now()
);

这里不急着把所有东西拆得很细。对一个技术博客或内容站来说,slug、title、summary、tags、status、content_markdown 已经能支撑大部分页面需求。

GitHub Actions 同步内容

GitHub Actions 的职责不应该只是“把文件传到数据库”,它更像一个内容发布检查点。

建议至少做三件事:

  • 校验 frontmatter 是否完整
  • 校验 slug、date、status 等字段是否合法
  • 将 Markdown 内容 upsert 到 Supabase

一个简化后的同步脚本可以是这样:

import fs from 'node:fs';
import path from 'node:path';
import matter from 'gray-matter';
import { z } from 'zod';
import { createClient } from '@supabase/supabase-js';

const PostSchema = z.object({
  title: z.string().min(1),
  slug: z.string().regex(/^[a-z0-9-]+$/),
  date: z.string(),
  tags: z.array(z.string()).default([]),
  summary: z.string().default(''),
  status: z.enum(['draft', 'published']).default('draft'),
});

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!,
);

async function syncPost(filePath: string) {
  const raw = fs.readFileSync(filePath, 'utf-8');
  const { data, content } = matter(raw);
  const post = PostSchema.parse(data);

  const { error } = await supabase.from('blog_posts').upsert(
    {
      slug: post.slug,
      title: post.title,
      summary: post.summary,
      tags: post.tags,
      status: post.status,
      published_at: post.date,
      content_markdown: content,
      updated_at: new Date().toISOString(),
    },
    { onConflict: 'slug' },
  );

  if (error) {
    throw error;
  }
}

GitHub Actions 里只需要在 push 后执行同步脚本:

name: Sync Markdown To Supabase

on:
  push:
    branches: [main]
    paths:
      - 'content/**/*.mdx'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm sync:content
        env:
          SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
          SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}

需要注意,SUPABASE_SERVICE_ROLE_KEY 只能放在 GitHub Secrets 里,不应该出现在浏览器端,也不应该写进前端环境变量。

Webhook 触发 revalidate

内容写入 Supabase 后,还需要通知 Next.js 刷新缓存。这里可以由 GitHub Actions 在同步成功后调用一个内部接口:

- name: Revalidate Next.js Pages
  run: |
    curl -X POST "$REVALIDATE_URL" \
      -H "Authorization: Bearer $REVALIDATE_SECRET" \
      -H "Content-Type: application/json" \
      -d '{"type":"blog"}'
  env:
    REVALIDATE_URL: ${{ secrets.REVALIDATE_URL }}
    REVALIDATE_SECRET: ${{ secrets.REVALIDATE_SECRET }}

Next.js 侧提供一个 route handler:

import { revalidatePath, revalidateTag } from 'next/cache';
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const auth = request.headers.get('authorization');

  if (auth !== `Bearer ${process.env.REVALIDATE_SECRET}`) {
    return NextResponse.json({ message: 'Unauthorized' }, { status: 401 });
  }

  const body = await request.json();

  if (body.type === 'blog') {
    revalidateTag('blog-posts');
    revalidatePath('/blog');

    if (body.slug) {
      revalidatePath(`/blog/${body.slug}`);
    }
  }

  return NextResponse.json({ revalidated: true });
}

这里的关键点是:Webhook 不直接修改页面,它只是告诉 Next.js 哪些缓存需要失效。

SSR + ISR 如何配合

在 App Router 中,页面可以从 Supabase 读取内容,同时通过 next: { tags } 或 revalidate 控制缓存。

例如博客列表页:

export const revalidate = 3600;

async function getPosts() {
  const { data } = await supabase
    .from('blog_posts')
    .select('slug,title,summary,tags,published_at')
    .eq('status', 'published')
    .order('published_at', { ascending: false });

  return data ?? [];
}

文章详情页可以通过 slug 查询正文,再在服务端渲染 Markdown:

import { MDXRemote } from 'next-mdx-remote/rsc';

export const revalidate = 3600;

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

  return (
    <article className="prose">
      <h1>{post.title}</h1>
      <MDXRemote source={post.content_markdown} />
    </article>
  );
}

这样页面不是每次都重新生成,也不是只能等下一次部署。多数访问会命中缓存;内容更新时,可以通过 Webhook 主动让相关页面失效。

这就是这里说的 SSR + ISR:

  • SSR:页面在服务端读取 Supabase 数据并渲染 HTML
  • ISR:渲染结果可以缓存,并在内容更新时按需刷新

SEO 上的收益

这套方案对 SEO 的帮助不是来自某个技巧,而是来自更稳定的内容输出方式:

  • 页面首屏直接返回完整 HTML,而不是浏览器端再请求正文
  • 标题、摘要、发布时间、标签都来自结构化字段
  • sitemap 可以直接从 published 内容生成
  • 旧文章更新后可以通过 revalidate 尽快刷新页面
  • Markdown 渲染结果仍然保持语义化标题、段落、列表和代码块

对内容型网站来说,搜索引擎不需要理解你的发布流程,但它会受益于稳定、可抓取、可更新的页面结果。

方案边界

这套方案适合:

  • 公司官网技术博客
  • 文档站
  • 轻量知识库
  • SEO 内容站
  • 需要 Git 审核流程的小团队内容系统

但它不一定适合所有项目。

如果内容运营人员完全不熟悉 Git,可能需要配一个后台编辑器;如果内容权限非常复杂,也需要单独设计权限模型;如果内容有大量协同编辑、版本对比和审批流,成熟 CMS 可能更合适。

工程方案的重点不是把系统做重,而是让当前阶段的内容生产、发布和渲染链路足够清楚。

总结

这套内容系统的价值在于把职责拆开:

  • Markdown 负责写作和版本管理
  • GitHub Actions 负责校验和同步
  • Supabase 负责线上查询和结构化存储
  • Webhook 负责通知缓存刷新
  • Next.js 负责服务端渲染和 ISR 缓存

它没有引入复杂 CMS,也没有把内容更新绑定到整站部署。对中小型内容站来说,这是一条比较实用的路径:保留 Git 工作流的确定性,同时让线上页面具备数据库查询和按需刷新的能力。