如何在 Next.js 项目中接入 SQLite 与 Prisma（2026 版）
Sawana Huang - Sun May 19 2024
按 2026 年官方文档重写的 SQLite + Prisma + Next.js 入门教程，带你完成初始化、迁移、Studio 验证，以及第一个真实查询。
这篇文章把 2024 年那版教程更新到了 2026 年 3 月当前还能跑通的做法。有几个地方现在已经变了：
create-next-app创建项目后通常已经自动安装好依赖，不需要再手动跑一次npm inpx prisma init现在默认并不是 SQLite，要显式传--datasource-provider sqlite- Prisma 现在会生成
prisma.config.ts，连接 URL 更适合放在配置和.env中，别再直接写死在schema.prisma里 - Prisma 是 ORM 和数据库工具链，不是“基于 GraphQL 的数据库”
如果你只是想在 Next.js 里尽快接一个本地数据库，这篇可以直接照着做。
先把流程摆出来
到 2026 年 3 月，如果你想在一个新的 Next.js 项目里使用 SQLite 和 Prisma，可以按这条顺序走：
- 用
create-next-app创建项目 - 安装 Prisma CLI、Prisma Client，以及 SQLite 适配器
- 用
npx prisma init --datasource-provider sqlite初始化 Prisma - 把
DATABASE_URL放进.env，并通过prisma.config.ts读取 - 定义 model，执行
prisma migrate dev - 在 Next.js 里创建一个可复用的 Prisma Client
SQLite 适合什么场景，不适合什么场景
SQLite 很适合这些场景：
- 本地开发
- 个人项目、原型验证、小型管理后台
- 读多写少的数据
- 不需要单独部署数据库服务的场景
SQLite 不适合这些场景：
- 部署在 Vercel 这类无状态 / serverless 环境里，还要求数据库长期持久化
- 多实例同时写入
- 明显会增长成多人共享生产数据库的应用
- 用户上传、交易、订单、协作这类高并发或高一致性场景
如果你一开始就知道项目最终会部署到云端并承接真实用户数据，那么 PostgreSQL 往往是更稳妥的起点。SQLite 更像是本地优先、单机优先的选择。
这篇会做到哪一步
我们会完成四件事：
- 在 Next.js 项目中初始化 Prisma + SQLite
- 创建第一份 schema 和 migration
- 用 Prisma Studio 检查数据库是否真的可用
- 在 Next.js 页面里发起一次真实查询
1. 创建一个新的 Next.js 项目
npx create-next-app@latest nextjs-sqlite-demo
cd nextjs-sqlite-demo如果你更喜欢先手动创建目录，也可以在空文件夹里执行：
npx create-next-app@latest .这里和很多旧教程不一样的一点是：create-next-app 默认就会安装依赖，所以通常不需要你再额外跑一次 npm install。
2. 安装 Prisma 与 SQLite 相关依赖
我们需要三类依赖：
- Prisma CLI：负责初始化、迁移、生成客户端
- Prisma Client：应用运行时真正用来查询数据库的客户端
- SQLite driver adapter：让 Prisma 使用 JS driver 连接 SQLite
npm install prisma @types/better-sqlite3 --save-dev
npm install @prisma/client @prisma/adapter-better-sqlite3 dotenv如果你用的是 TypeScript，@types/better-sqlite3 可以一起装上，省得后面补类型。
3. 初始化 Prisma，并明确指定 SQLite
npx prisma init --datasource-provider sqlite --output ../src/generated/prisma这里有两个重点：
--datasource-provider sqlite：明确告诉 Prisma 我们这次要用 SQLite--output ../src/generated/prisma：把生成出来的 Prisma Client 放进src/generated/prisma，后面在 Next.js 里更好 import
初始化完成后，你会看到类似这些文件：
prisma/
schema.prisma
prisma.config.ts
.env旧教程里常见的写法是先执行 npx prisma init，然后再手动改成 SQLite。这个思路现在依然能工作，但已经不是最直接的方式，因为 Prisma 当前默认初始化并不是 SQLite。
4. 配置数据库 URL，并把数据库文件放到 prisma/ 目录下
先打开 .env，把数据库地址改成：
DATABASE_URL="file:./prisma/dev.db"这样做的目的很简单：我们显式把数据库文件放到 prisma/ 目录下，避免它直接落在项目根目录。
然后确认 prisma.config.ts 类似下面这样：
import "dotenv/config";
import { defineConfig, env } from "prisma/config";
export default defineConfig({
schema: "prisma/schema.prisma",
migrations: {
path: "prisma/migrations",
},
datasource: {
url: env("DATABASE_URL"),
},
});接着确认 prisma/schema.prisma 至少有这两个块：
generator client {
provider = "prisma-client"
output = "../src/generated/prisma"
}
datasource db {
provider = "sqlite"
}你可以把它理解为：
.env：真正保存数据库地址prisma.config.ts：把地址喂给 Prismaschema.prisma：描述“我要连的是什么数据库”和“我要生成什么客户端”
5. 定义你的第一个数据模型
接下来，我们在 prisma/schema.prisma 里加入两个最经典的示例模型：
model User {
id Int @id @default(autoincrement())
email String @unique
name String?
posts Post[]
}
model Post {
id Int @id @default(autoincrement())
title String
content String?
published Boolean @default(false)
author User @relation(fields: [authorId], references: [id])
authorId Int
}如果你刚接触 Prisma，可以暂时把 model 理解成“表的声明方式”。
User是用户表Post是文章表posts Post[]和author User表示两张表之间的关系
6. 创建 migration，并显式生成 Prisma Client
npx prisma migrate dev --name init
npx prisma generate执行完成后，通常会多出这些内容：
prisma/
migrations/
20260314000000_init/
migration.sql
dev.db
src/
generated/
prisma/先看这三样：
prisma/migrations/.../migration.sql：本次迁移生成的 SQLprisma/dev.db：SQLite 数据库文件本体src/generated/prisma：可供应用 import 的 Prisma Client
有些旧资料会把 migrate dev 和 generate 混在一起讲。为了减少版本差异带来的困惑，我建议把 npx prisma generate 当成一个显式步骤，执行完迁移后手动再跑一次。
7. 在 Next.js 中创建可复用的 Prisma Client
如果只做到上一步，你已经有数据库了，但还没有在 Next.js 应用里真正用起来。
现在创建一个文件：src/lib/prisma.ts
import { PrismaBetterSqlite3 } from "@prisma/adapter-better-sqlite3";
import { PrismaClient } from "@/generated/prisma/client";
const globalForPrisma = globalThis as unknown as {
prisma?: PrismaClient;
};
function createPrismaClient() {
const adapter = new PrismaBetterSqlite3({
url: process.env.DATABASE_URL!,
});
return new PrismaClient({ adapter });
}
export const prisma = globalForPrisma.prisma ?? createPrismaClient();
if (process.env.NODE_ENV !== "production") {
globalForPrisma.prisma = prisma;
}这个文件做了两件事：
- 告诉 Prisma 使用 SQLite adapter
- 在开发环境里把 Prisma Client 缓存在全局变量上，避免 Next.js 热更新时反复创建实例
如果你的项目没有 src/ 目录，而是直接把 app/、lib/ 放在根目录，那么只需要把 --output 和 import 路径一起改掉即可。
8. 写一个真正查询数据库的页面
现在随便找一个页面，比如 src/app/page.tsx，写一个最小可运行示例：
import { prisma } from "@/lib/prisma";
export default async function HomePage() {
const users = await prisma.user.findMany({
include: {
posts: true,
},
orderBy: {
id: "asc",
},
});
return (
<main className="p-8">
<h1 className="text-2xl font-bold">SQLite + Prisma 已接通</h1>
<pre className="mt-4 overflow-auto rounded bg-slate-950 p-4 text-sm text-slate-100">
{JSON.stringify(users, null, 2)}
</pre>
</main>
);
}如果数据库里还没有数据，页面大概率会显示 []。这是正常的，说明查询已经成功，只是表里暂时是空的。
9. 用 Prisma Studio 验证数据库
npx prisma studio大多数情况下，它会启动一个本地页面，默认地址类似：
http://localhost:5555你可以直接在里面：
- 新建
User - 给某个
User关联Post - 再刷新你的 Next.js 页面看查询结果有没有变化
如果你的环境没有自动识别 prisma.config.ts，也可以显式写成：
npx prisma studio --config ./prisma.config.ts到这里，SQLite 不只是“创建成功”，而是已经真正接进 Next.js 应用了。
这篇文章修正了哪些旧误区
如果你是从旧教程一路搜过来的，这里把最容易踩坑的点再集中列一遍：
create-next-app通常已经自动安装依赖，不要重复npm installnpx prisma init当前默认不是 SQLite，要显式加--datasource-provider sqlite- 数据库 URL 更适合放在
.env+prisma.config.ts，不要直接把路径硬编码死在 schema 里 - Prisma 是 ORM / 工具链，不是 GraphQL 查询层
- 本地 SQLite 不适合作为 Vercel 上的持久化生产数据库
- 只把数据库创建出来还不够，最好补上一个真实查询，确认 Next.js 侧链路也通了
什么时候该从 SQLite 换到 PostgreSQL
如果你出现以下任一情况，就该认真考虑换数据库了：
- 项目已经不再是本地玩具，而是准备正式上线
- 需要多个实例同时访问同一份数据库
- 你要部署到 Vercel 这类无状态环境，并保留可写数据
- 业务开始涉及用户账户、订单、支付、协作、审计等真实生产数据
SQLite 并不“落后”，它只是场景不同。把它放在正确的位置上，它会非常省心；把它放在错误的位置上，它会让你后面迁移得更痛苦。
参考资料
- Next.js Installation
- Prisma Quickstart with SQLite
- Prisma CLI Reference: init
- Prisma SQLite Connector
- Prisma Migrate: Development and Production
- Prisma Studio
- Vercel Functions Runtimes