给 Next.js 博客接上数据库:Prisma 7 + Neon,从建表到导入文章
文章为什么存数据库而不是读文件、两个连接串各管什么、pgvector 为什么第一次迁移就要建、Prisma 单例防什么、seed 为什么用 upsert 并且默认不发布。一个博客数据层的每个决定和它的理由。
这个博客的文章存在 Postgres 里,用 Prisma 访问。数据库是在 Vercel 后台通过 Marketplace 创建的 Neon 实例,环境变量由 Vercel 注入。
这篇按接入顺序,把数据层的每个决定和理由写下来:存哪里、怎么连、表怎么设计、迁移怎么做、客户端怎么建、初始文章怎么导入。
Prisma 7 和网上大多数教程(停在 Prisma 6)差别很大,装包和跑第一条命令时我连踩了几个坑,单独写在了《Prisma 7 把我会的写法全废了》里。这里只讲接入本身。
一、文章为什么存数据库
博客常见的做法是直接读 Markdown 文件。这个项目选了「文件写作、导入数据库、页面读数据库」,两个原因:
- 后面要做向量检索。 计划里有一个站内 AI 助手,要把文章切片、生成 embedding 存进 pgvector。正文迟早要进库,再从文件读一遍,就是维护两份事实源。
- 发布要有落点。 后台发布文章后要按需失效缓存,「发布」天然是一次数据库写入。读文件的话,这个动作没地方挂。
正文存纯 Markdown 字符串,不用 MDX。文章不需要嵌入 React 组件,也避免在服务端编译执行数据库里的代码;以后做向量切片,纯文本也更好处理。
代价是构建时多了数据库查询,这在后面做静态生成时会体现出来。
二、两个连接串
Neon 集成往 Vercel 注入了 18 个环境变量,只用其中两个:
| 用途 | 变量 | 端点 |
|---|---|---|
| 应用运行时 | DATABASE_URL | pooled,hostname 带 -pooler |
| Prisma CLI(迁移等) | DATABASE_URL_UNPOOLED | direct,直连 |
应用为什么走连接池:serverless 下每个函数实例都会建自己的连接,并发上去之后连接数会线性增长。pooled 端点背后是 PgBouncer,由它复用连接。
迁移为什么必须直连:PgBouncer 的 transaction 模式下,连接按事务分配,advisory lock、会话参数这类 session 级状态不保证落在同一个后端连接上。Prisma 迁移依赖 advisory lock 防止并发,还要跑多语句 DDL。用错了的表现是「小迁移能过,大迁移偶发失败」,最难排查。
Prisma 官方 Neon 文档的原话:「The Prisma CLI keeps using the direct connection string from prisma.config.ts, while your application's connections are pooled」。
本地用 vercel env pull 把变量拉到 .env.local 。
三、driver adapter 选 adapter-pg
Prisma 7 起,driver adapter 对所有数据库都是必需的:Prisma 只负责把查询编译成 SQL,连接数据库、发 SQL 交给 JS 驱动。候选有两个:
@prisma/adapter-pg:node-postgres,走 TCP。@prisma/adapter-neon:Neon 的 serverless 驱动,走 WebSocket / HTTP。
选了 adapter-pg 。adapter-neon 的核心价值在 Edge Runtime,那里没有 TCP。而 Next.js 16 的 Cache Components 要求 Node.js runtime,用不上 Edge。连接池问题已经交给 Neon 的 pooler 解决,应用层不用再操心。少一层 Neon 专有依赖,以后换别家 Postgres 只改一行。
四、prisma.config.ts 与 schema
Prisma 7 把连接串从 schema.prisma 挪到了项目根的 prisma.config.ts ,这里配的是 CLI 用的那个:
import { defineConfig, env } from 'prisma/config'
// Prisma CLI 以独立 Node 进程执行本文件,不经过 Next.js,
// Next.js 自动加载 .env.local 的能力在这里不生效,得自己加载。
// Vercel 上没有 .env.local(变量由平台注入),所以要容错。
try {
process.loadEnvFile('.env.local')
} catch {}
export default defineConfig({
schema: 'prisma/schema.prisma',
migrations: {
path: 'prisma/migrations',
seed: 'node prisma/seed.ts',
},
datasource: {
url: env('DATABASE_URL_UNPOOLED'),
},
})
try/catch 不是多余的防御:Vercel 构建时没有 .env.local ,postinstall 里的 prisma generate 每次部署都会走到这里。
schema 只有一张表:
generator client {
provider = "prisma-client"
output = "../lib/generated/prisma"
importFileExtension = "ts" // 让 Node 能直接跑 seed,原因见《Prisma 7 把我会的写法全废了》
}
datasource db {
provider = "postgresql"
}
model Post {
id String @id @default(cuid())
slug String @unique
title String
description String?
content String
published Boolean @default(false)
publishedAt DateTime?
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
@@index([published, publishedAt])
}
几个字段的考虑:
slug唯一:它是文章 URL 的一部分,也是静态生成时的路由参数,后面 seed 的 upsert 也靠它。- 单独的
publishedAt,不用createdAt排序:草稿写完放几天再发是常态,按创建时间排序,新发布的文章会沉到后面。草稿没有发布时间,所以可空。 - 复合索引
[published, publishedAt]:列表页的查询是「已发布的,按发布时间倒序」。等值条件的字段在前,排序字段在后。 updatedAt自动维护:后来 sitemap 的lastmod、结构化数据的dateModified都用它。- 暂不加
tags:做到标签页再加,不提前建模。后来做首页热门列表时加了viewCount,也是用到时才加的。
output 必须显式写,Prisma 7 不再往 node_modules 里生成代码。生成产物加进 .gitignore ,在 package.json 里加 "postinstall": "prisma generate" ,保证 Vercel 构建时有 client 代码。
五、第一次迁移就建 pgvector
向量检索是后面阶段才做的事,但扩展在第一次迁移里就建了。原因是 shadow database。
prisma migrate dev 每次都会建一个临时的 shadow database,从头重放迁移历史,用来校验数据库状态。如果 vector 扩展是在控制台手动 CREATE EXTENSION 装的,shadow database 里就没有它,以后加向量字段时每次 migrate dev 都会失败。Prisma 文档的原话是:
If your project uses Prisma Migrate, you must install the extension as part of a migration. Do not install the extension manually, because it is also required by the shadow database.
做法是先只生成迁移文件、不执行:
pnpm prisma migrate dev --name init --create-only
在生成的 migration.sql 最上面加一行:
CREATE EXTENSION IF NOT EXISTS vector;
再执行 pnpm prisma migrate dev 。这次只建扩展,不建向量表,等用到时再加。
六、Prisma Client 单例
import { PrismaPg } from '@prisma/adapter-pg'
import { PrismaClient } from './generated/prisma/client.ts'
const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient }
function createPrismaClient() {
// 运行时走 pooled 端点
const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
return new PrismaClient({ adapter })
}
export const prisma = globalForPrisma.prisma ?? createPrismaClient()
if (process.env.NODE_ENV !== 'production') {
globalForPrisma.prisma = prisma
}
为什么要挂到 globalThis ?Next.js dev 模式下模块会被热更新反复求值。直接 export const prisma = new PrismaClient(...) 的话,每改一次代码就多建一个连接池,十几次热更新后数据库开始拒绝连接,表现是「改着改着连不上,重启就好」。挂在 globalThis 上,热更新之间复用同一个实例。
用 Egg.js 类比:app.model 挂在 application 上,进程内只有一份。Next.js 没有这样的应用级容器,只能手动用 globalThis 模拟。
生产环境不挂:模块只求值一次,没有收益;serverless 下全局对象的生命周期跟着函数实例走,挂上去反而容易让人误以为它能跨实例共享。
七、seed:把文章导入数据库
文章写在 content/posts/*.md ,开头是 frontmatter:
---
slug: nextjs-16-agents-md
title: Next.js 16 会往你项目里写一个文件,专门写给 AI 看
description: ...
draft: false
publishedAt: 2026-09-20
---
prisma/seed.ts 遍历这些文件,解析后写入数据库。几个设计决定:
frontmatter 手写解析,不引 gray-matter
frontmatter 只在 seed 时解析一次,字段固定 5 个,没有数组、没有嵌套、没有多行文本。20 行的解析器,比评估一个依赖的维护状态还快。
唯一要小心的是取第一个冒号,不能用 split(':') ,否则 title: Prisma 7: 断代升级 这种标题会被截断:
const i = line.indexOf(':')
meta[line.slice(0, i).trim()] = line.slice(i + 1).trim()
代价也写清楚:这不是 YAML 解析器。以后 frontmatter 需要数组或多行文本,就换正经的 YAML 库,而不是给这 20 行打补丁。
用 upsert,不用「先清空再插入」
seed 要能重复跑,改完文章再跑一次,结果要一致。两种幂等做法:
按 slug upsert | 先清空再插入 | |
|---|---|---|
| 幂等 | 是 | 是 |
保留 id | 是 | 每次换新 id |
| 以后关联了向量切片 | 安全 | 外键级联删掉切片,embedding 白算 |
第三行现在看不出差别,但以后每篇文章会关联一批切片和 embedding,向量是花钱算出来的。
开 log: ['query'] 看 upsert 实际发的 SQL:
INSERT INTO "public"."Post" (...) VALUES (...)
ON CONFLICT ("slug") DO UPDATE SET "title" = $8, "updatedAt" = $9
WHERE ...
RETURNING ...
它是一条语句,不是先 SELECT 再决定 INSERT 还是 UPDATE,所以没有并发竞态的窗口。ON CONFLICT ("slug") 依赖唯一索引,这也是 slug 必须 @unique 的原因。DO UPDATE SET 只更新 update 对象里的字段,createdAt 不会被改。
draft 和 published:默认不发布
frontmatter 里用 draft ,数据库里用 published ,seed 负责转换。
两个名字是故意分开的。写作侧,新文章天然是「还没写完」,Hugo、Jekyll、Astro 都用 draft 。查询侧要问的是「哪些能展示」,列表页、sitemap、RSS 都要带 where: { published: true } ,比 draft: false 这种双重否定好读得多。
转换时有一个方向问题。第一版写的是:
published: meta.draft !== 'true' // 漏写 draft 就直接发布
忘记标记的后果应该是「没发出去」,而不是「不该发的发出去了」。改成:
published: meta.draft === 'false' // 必须显式写 draft: false 才发布
默认值要倒向安全的一侧。
seed 不会自动触发
Prisma 7 的变化:「seeding is only triggered explicitly by running prisma db seed」。以前 migrate reset 会顺带重新 seed,现在不会了,重置之后要手动跑 pnpm db:seed 。
另外,文件是事实源,数据库只是投影。改了 frontmatter 不会自动同步,必须重跑 seed。我真撞到过一次:文件已经改成 draft: false ,页面上还是看不到文章,原因就是没重跑。
八、验证幂等
跑两次 seed,比较结果:
nextjs-16-agents-md
id : cmu9iv2rx0000q6xqwh2xbt31 ← 两次相同
published : true ← 文件里 draft: false
createdAt : 07:55:58.797Z ← 停在第一次
updatedAt : 08:07:01.152Z ← 推进到第二次
prisma-7-breaking-changes
published : false ← 文件里 draft: true
id 不变、createdAt 不变、updatedAt 推进,说明第二次走的是 ON CONFLICT DO UPDATE 分支,不是删了重建。
一篇已发布、一篇草稿的状态也是故意保留的:后面做列表页时,能直接验证「只查已发布」的过滤是否生效。
还没处理好的
本地连的是主库。 dev、preview、production 三个环境共用同一份连接串。库里只有几篇文章时问题不大,但一条 prisma migrate reset 就能清空线上数据。所以 migrate reset 故意没做成 npm script,需要时手打完整命令。真实内容多起来之后,应该切到 Neon 的分支库。
publishedAt 的时区。 new Date('2026-09-20') 按 ISO 规则解析成 UTC 零点,在东八区显示是当天 8 点。现在只用来排序没有影响,等页面上要显示日期时,要么 frontmatter 写完整时间,要么格式化时显式指定时区。
回头看,这一层没有一行是难写的代码,花时间的都是「为什么这样而不是那样」:为什么两个连接串、为什么扩展要进迁移、为什么 upsert、为什么默认不发布。每个决定背后都是一个之后会发生的场景:并发、热更新、向量切片、忘了标记草稿。