在做内容型网站时,最容易低估的不是页面渲染,而是内容从“写完”到“稳定出现在页面上”的整条链路。
如果只是一个博客,把 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”本身需要数据库,而是因为内容后续会进入更多使用场景:
-
列表查询更方便
标签、分类、发布日期、语言、状态等字段可以直接通过 SQL 查询,不需要每次扫描文件系统。 -
可以利用 PostgreSQL 的内容能力
内容进入 PostgreSQL 后,可以使用索引、全文检索、关联查询、排序、过滤和统计能力。比如根据标签聚合文章、生成相关文章、按业务对象关联指南与案例等。 -
更适合作为 LLM 的知识来源
如果后续要做智能问答、内容助手或 RAG,LLM 不应该临时去读散落的 Markdown 文件。更稳妥的方式是让文章正文、摘要、标签、语言、发布时间等字段先进入数据库,再基于 PostgreSQL 或pgvector做检索和召回。 -
内容状态更清晰
可以区分draft、published、archived等状态,避免未发布内容进入线上页面。 -
运行时依赖更可控
线上页面读取 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 工作流的确定性,同时让线上页面具备数据库查询和按需刷新的能力。