从零到上线Next.js 接入 PlanetScale MySQL 的完整实战指南【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.jsNext.js 官方仓库的with-mysql示例把 App Router、Prisma ORM 与托管数据库 PlanetScale MySQL 装进一个可运行的电商商品列表里。跟着走一遍你能拿到一套云端建库 → 本地跑通 → 部署上线的完整 MySQL 接入流程而且每个环节都知道它为什么这么设计。先看地图谁负责什么这套示例的分工非常克制每个文件只干一件事路径职责prisma/schema.prisma定义 Product / Category 模型与客户端生成器prisma/data.ts3 个分类、4 件商品的种子数据prisma/seed.ts清空旧数据并批量灌入种子prisma.config.ts为 Prisma CLI 提供 schema 路径与连接串来源lib/prisma.ts运行时数据库客户端全局单例封装app/page.tsx服务端组件直接查库渲染商品网格components/Product.tsx单张商品卡片.env.exampleDATABASE_URL连接串模板技术组合是 Next.jsApp Router Prisma新版 TypeScript 客户端prisma/adapter-planetscale驱动适配器 Tailwind CSS v4。适配器把 SQL 通过 HTTPS 发往 PlanetScale 网关所以运行时依赖里才有undici——它给适配器提供 fetch 实现客户端本身不走 MySQL 协议。认证 CLI 并建库把引擎类型和默认分支定下来 动手前先装好 PlanetScale CLI用pscale auth login完成浏览器授权之后所有命令都靠这份本地凭据。建库命令很短pscale database create DATABASE_NAME --engine mysql输出里会告诉你数据库创建成功。值得注意的隐藏事实是建库同时自动生成了一个名为main的分支PlanetScale 的 schema 变更都发生在分支上main就是后续所有操作的起点。引擎类型必须在建库时用--engine mysql钉死Postgres 是另一套模板两者的适配器和连接串格式完全不通用事后换不掉。拉下模板工程一条命令装齐全部依赖凭据有了接下来把代码拉下来npx create-next-app --example with-mysql nextjs-mysqlyarn / pnpm / bun 也有对应写法。执行完会在nextjs-mysql目录里装好 package.json 声明的全部依赖运行时是next、react、prisma/client、prisma/adapter-planetscale、undici开发侧是prismaCLI、tsx跑种子脚本、dotenv加载.env和 Tailwind v4。依赖看着不多但每个都有明确职责这也是后面排查问题时的排查清单。生成凭据拼连接串明文密码只展示一次先复制模板文件mv .env.example .env然后给main分支创建一组凭据pscale password create DATABASE_NAME main PASSWORD_NAME输出会长这样——明文密码只展示这一次务必当场保存NAME USERNAME ACCESS HOST URL ROLE PLAIN TEXT PASSWORD_NAME xxxxxxxxxxxxx xxxxxx.us-east-2.psdb.cloud Can Read Write pscale_pw_xxxxxxx把四个字段拼进.env的DATABASE_URL参数来源说明USERNAME输出的USERNAME数据库用户名PLAIN_TEXT_PASSWORD输出的PLAIN TEXT只出现一次的明文密码ACCESS_HOST_URL输出的ACCESS HOST URL访问域名末尾别加斜杠DATABASE_NAME建库时的名称目标库名?sslacceptstrict固定追加强制 TLS同一分支允许多组凭据PASSWORD_NAME就是给这组凭据贴的用途标签——开发一组、生产一组轮换时互不影响。这条连接串会被两边消费Prisma CLI 从 prisma.config.ts 的env(DATABASE_URL)读应用运行时从process.env.DATABASE_URL读所以格式拼错一次两边同时报错。看懂数据模型连接串为什么不写进 schema打开 prisma/schema.prisma 会看到两个模型和一处刻意的留白generator client { provider prisma-client output ../lib/generated/prisma }客户端输出到lib/generated/prisma而不是传统的node_modules/.prisma因此应用和种子脚本都从/lib/generated/prisma/client导入类型生成产物跟着代码库走datasource块里没有url连接串统一由 prisma.config.ts 提供。这是新版 Prisma 的推荐做法schema 只描述结构环境相关的信息集中到一处改库名不用动 schemarelationMode prisma表示外键完整性由应用层维护适配 PlanetScale 不允许传统外键约束的默认场景price用Decimal而不是浮点数种子数据里配合new Prisma.Decimal(19.95)构造避免货币精度丢失。模型本身是一对多Product通过categoryId引用Category并加了index([categoryId])按分类筛选商品时走索引。推模型灌种子三条命令把空库变成商品库凭据配好后按顺序执行npx prisma generate # 按 schema 生成类型安全的客户端 npx prisma db push # 把模型直接同步成数据库表结构 npx prisma db seed # 写入演示数据db push不生成迁移文件适合原型阶段想留迁移历史就换成migrate系列命令。db seed实际执行的是 package.json 里prisma.seed声明的tsx prisma/seed.ts。种子脚本的策略是幂等重建先deleteMany()清空两张表再用$executeRaw把AUTO_INCREMENT重置为 1然后createMany批量写入 data.ts 里的 3 个分类和 4 件商品。重置自增是必要的——商品通过categoryId: 1/2/3硬关联分类主键不重置的话第二次灌数据时外键就会指向不存在的 id。脚本重复执行永远安全这对你调试期间反复灌库非常友好。跑通本地页面单例防止连接爆炸npm run dev访问http://localhost:3000能看到渲染出来的商品网格数据流向是 app/page.tsx 这个 async 服务端组件直接执行prisma.product.findMany({ include: { category: true } })一次联表取出商品和所属分类再逐项传给Product卡片组件。没有中间的 API 层客户端只收到 HTML——这是 App Router 推荐的取数姿势。真正值得逐行看的是 lib/prisma.tsconst prisma globalForPrisma.prisma ?? createPrismaClient(); if (process.env.NODE_ENV ! production) globalForPrisma.prisma prisma;为什么非要挂在globalThis上因为 Next.js 开发模式下每次文件变更都会重新执行模块代码如果每轮都new PrismaClient()相当于每次保存都新开一条数据库连接连接数很快顶到上限。把实例挂到全局后热更新只创建一次后续全部复用生产环境模块只加载一次所以只在非生产环境才写全局。部署前提升分支生产流量只走被提升的 main 本地跑通后上线前还差一个数据库动作pscale branch promote DATABASE_NAME main在 PlanetScale 里main分支默认是开发角色只有被提升为生产分支后生产流量才有资格访问它。不提升就直接部署线上请求会因为没有可用的生产凭据路径而失败。提升后你可以复用之前那组密码也可以新跑一次pscale password create给生产单独配一组——推荐后者开发和生产凭据隔离出问题时能立刻轮换生产而不动本地。最后是部署平台侧把项目导入部署平台在环境变量里填上生产DATABASE_URL即可。由于页面全是服务端渲染构建期不需要连库每次请求时实时查 PlanetScale。排错清单现象、原因与处置 按出现频率排序现象原因处置PrismaClientInitializationError/ 连接失败连接串四个字段没替换全或域名末尾多了路径对照 CLI 输出逐字段核对保留?sslacceptstrict页面是空的没有商品只跑了generate没跑db push和db seed补跑后两条命令种子可重复执行种子脚本报找不到DATABASE_URLdotenv/config依赖当前目录是项目根在nextjs-mysql根目录执行命令开发期连接数超限绕过单例直接new PrismaClient()统一从 lib/prisma.ts 导入线上 401 或连不上库分支没提升或用了开发凭据访问生产pscale branch promote并换生产连接串提示连接串的四个字段都来自pscale password create的同一次输出缺一个都连不上保存密码的那步输出是唯一窗口丢了只能重新password create一组新凭据。如何迁移到自己的项目这套骨架可以直接当模板用替换点集中在三处模型改 prisma/schema.prisma 为你的业务表保留prisma-client生成器与prisma.config.ts的连接串外置写法重新prisma generatedb push种子数据把你的初始数据放进prisma/data.ts照抄 seed.ts 的清空 → 重置自增 → 批量写入流程保证可重复执行取数与渲染在服务端组件里 import lib/prisma.ts 导出的单例实例做查询不要自己new客户端。环境差异只在凭据本地一组、生产一组连接串格式不变。把这三层解耦记牢之后换数据库供应商时你只需要换适配器和连接串业务代码一行不动。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考