给 Next.js 博客接上数据库:Prisma 7 + Neon,从建表到导入文章

文章为什么存数据库而不是读文件、两个连接串各管什么、pgvector 为什么第一次迁移就要建、Prisma 单例防什么、seed 为什么用 upsert 并且默认不发布。一个博客数据层的每个决定和它的理由。

2026-10-10

这个博客的文章存在 Postgres 里,用 Prisma 访问。数据库是在 Vercel 后台通过 Marketplace 创建的 Neon 实例,环境变量由 Vercel 注入。

这篇按接入顺序,把数据层的每个决定和理由写下来:存哪里、怎么连、表怎么设计、迁移怎么做、客户端怎么建、初始文章怎么导入。

Prisma 7 和网上大多数教程(停在 Prisma 6)差别很大,装包和跑第一条命令时我连踩了几个坑,单独写在了《Prisma 7 把我会的写法全废了》里。这里只讲接入本身。

一、文章为什么存数据库

博客常见的做法是直接读 Markdown 文件。这个项目选了「文件写作、导入数据库、页面读数据库」,两个原因:

  1. 后面要做向量检索。 计划里有一个站内 AI 助手,要把文章切片、生成 embedding 存进 pgvector。正文迟早要进库,再从文件读一遍,就是维护两份事实源。
  2. 发布要有落点。 后台发布文章后要按需失效缓存,「发布」天然是一次数据库写入。读文件的话,这个动作没地方挂。

正文存纯 Markdown 字符串,不用 MDX。文章不需要嵌入 React 组件,也避免在服务端编译执行数据库里的代码;以后做向量切片,纯文本也更好处理。

代价是构建时多了数据库查询,这在后面做静态生成时会体现出来。

二、两个连接串

Neon 集成往 Vercel 注入了 18 个环境变量,只用其中两个:

用途变量端点
应用运行时DATABASE_URLpooled,hostname 带 -pooler
Prisma CLI(迁移等)DATABASE_URL_UNPOOLEDdirect,直连

应用为什么走连接池: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、为什么默认不发布。每个决定背后都是一个之后会发生的场景:并发、热更新、向量切片、忘了标记草稿。

AI 只依据本文内容回答,可能出错,请以原文为准。