20分钟打通 Next.js 与 PlanetScale MySQL从零库到线上商品列表【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js页面写好了数据往哪放本文用 Next.js 官方仓库里的with-mysql示例走一遍 Next.js 接入 PlanetScale MySQL 的完整流程Prisma 描述模型Driver Adapter 负责连库Server Component 取数渲染。跟着做你会得到一个能上线的商品列表页。这套组合怎么分工组件职责Next.jsApp Router页面与服务端渲染页面直接查库Prisma prisma/adapter-planetscale类型安全的数据访问查询经 PlanetScale 的 HTTPS 网关发出PlanetScale MySQL托管数据库免连接池运维支持分支Tailwind CSS v4页面样式的工具类这张 T 恤商品图就来自示例页面图片路径和名称正是数据库里存的那条种子数据。 动手前对一遍清单开工前确认这四件事有一个 PlanetScale 账号已安装 PlanetScale CLIpscale已安装 Node.js跑 Next.js 和 Prisma CLI 都要用当前目录就是你要放项目的地方CLI 装好后先执行pscale auth login。这一步会打开浏览器走 OAuth 授权凭据存在本地后续命令直接复用。数据放在哪建库与凭据先搞懂分支是什么PlanetScale 的一切建立在分支上。建库时会自带一个main分支其他分支从它派生可以独立改 schema、读写数据再通过部署请求合并回主分支。可以把它理解成数据库版的开发分支。这也解释了为什么上线前要做分支提升后文部署部分会讲。数据库怎么建指定 MySQL 引擎即可。库名会被后续所有命令引用起个有业务含义的名字pscale database create myshop --engine mysql凭据怎么建先在示例目录里把模板改名成真实的环境文件即mv .env.example .env再为分支创建一组凭据pscale password create myshop main dev-credentials为什么按分支建凭据同一分支可以挂多组凭据用名字区分用途开发、生产各一组以后可以单独轮换任意一组。CLI 会返回一张表关键是USERNAME、ACCESS HOST URL、PLAIN TEXT三个字段。⚠️ 明文密码只展示这一次立刻保存。丢了只能重新创建一组新的。也可以走控制台数据库概览页 → Settings → Passwords效果相同。连接串怎么拼连接串 ≈ 门牌 钥匙域名和库名是门牌用户名密码是钥匙。按模板拼好填进.env的DATABASE_URLmysql://USERNAME:PLAIN_TEXT_PASSWORDACCESS_HOST_URL/DATABASE_NAME?sslacceptstrict字段来源USERNAMECLI 返回的USERNAMEPLAIN_TEXT_PASSWORDCLI 返回的PLAIN TEXTACCESS_HOST_URLCLI 返回的ACCESS HOST URLDATABASE_NAME建库时起的名字?sslacceptstrict固定追加强制 TLS 加密连接这条DATABASE_URL被两边消费Prisma CLI 侧由 prisma.config.ts 读取应用运行侧读process.env.DATABASE_URL。模板 .env.example 预置的就是这套格式。两个注意点prisma.config.ts和种子脚本都在文件顶部import dotenv/config因为 Prisma 命令和种子脚本不走 Next.js 的环境变量加载.env要手动读。执行这些命令时当前目录必须在项目根目录否则找不到.env。项目怎么落地模板与关键文件示例位于 Next.js 仓库的examples/with-mysql目录已被create-next-app收录为模板一条命令带走整个项目# npm npx create-next-app --example with-mysql nextjs-mysql # yarn yarn create next-app --example with-mysql nextjs-mysql # pnpm pnpm create next-app --example with-mysql nextjs-mysql # bun bunx create-next-app --example with-mysql nextjs-mysql以 npm 为例会创建nextjs-mysql目录并装齐 package.json 里声明的全部依赖。哪些文件负责什么文件作用prisma/schema.prisma数据模型与生成器配置prisma/seed.ts种子脚本灌入演示数据prisma/data.ts预置的 3 个分类、4 件商品prisma.config.tsPrisma CLI 配置读连接串、指向种子命令lib/prisma.tsPrismaClient 单例与 Driver Adapter 接线app/page.tsx服务端取数并渲染的页面.env.exampleDATABASE_URL模板运行时与开发依赖怎么分运行时next/react/react-dom撑起页面框架prisma/client负责数据访问prisma/adapter-planetscale是 PlanetScale 适配器undici给适配器提供 fetch 实现。开发时prismaCLI、tsx跑 TypeScript 种子脚本、dotenv、tailwindcssv4 与tailwindcss/postcss外加 TypeScript 和类型声明。表和字段怎么来读懂 Schemaprisma/schema.prisma 的核心是两个模型。商品侧长这样model Product { id Int id default(autoincrement()) name String price Decimal image String categoryId Int category Category relation(fields: [categoryId], references: [id]) index([categoryId]) }Category侧是反向引用products Product[]与Product的categoryId构成一对多关系index([categoryId])让按分类查询走索引。几个细节值得停一下price用Decimal而不是浮点金额字段避免精度漂移种子脚本里也用new Prisma.Decimal(...)构造精确值见 prisma/data.ts。生成器是新版 TypeScript 版provider prisma-clientoutput指向../lib/generated/prisma。生成的客户端落在项目目录里应用和种子脚本都从/lib/generated/prisma/client导入不再藏在node_modules深处。datasource 里不写url连接串统一由prisma.config.ts提供datasource.url: env(DATABASE_URL)prisma db push、prisma generate等命令都读这份配置。relationMode prismaPlanetScale 默认场景下没有外键约束关系完整性由 Prisma 在应用层维护。真正建连接的是 adapterprisma/adapter-planetscale接收连接串把每条查询经 HTTPS 发给 PlanetScale 的 Serverless Driver 网关客户端本身不直接说 MySQL 协议。undici出现在运行时依赖里就是作为 fetch 实现传进适配器的。⚠️ 这套面向 PlanetScale 的 MySQL 兼容服务。若你用的是 PlanetScale Postgres驱动适配器和连接串格式都不同不要混用。怎么验证跑通了三条命令顺序不能乱。先说清楚每条在干什么generate按 schema 的output路径产出类型安全客户端是后面两步的前提db push把当前模型直接同步进数据库不生成迁移文件适合原型阶段db seed灌种子数据实际执行的是tsx prisma/seed.tspackage.json 的prisma.seed字段与 prisma.config.ts 的migrations.seed指向同一个脚本。npx prisma generate npx prisma db push npx prisma db seed种子策略是清空重写先deleteMany()清空两张表再用$executeRaw把AUTO_INCREMENT重置回 1最后createMany批量写入 3 个分类Hats / Socks / Shirts和 4 件商品。为什么要重置自增商品靠categoryId引用分类主键1/2/3先重置再插入外键引用才不会错位。清空重写意味着重复执行也安全。然后在项目根目录跑npm run dev浏览器打开 http://localhost:3000。你应该看到一个商品网格头盔、T 恤、袜子、卫衣每件带图片、名称、描述、价格和分类标签。数据怎么从库流到页面app/page.tsx 是一个async Server Component服务端直接执行prisma.product.findMany({ include: { category: true } })一次联表取出商品和所属分类再逐项交给Product组件渲染。浏览器只收到渲染好的 HTML不需要额外的 API 层。这就是 App Router 时代推荐的取数姿势。Prisma 单例为什么挂 globalThislib/prisma.ts 的关键几行const globalForPrisma globalThis as unknown as { prisma: PrismaClient | undefined } const prisma globalForPrisma.prisma ?? createPrismaClient() if (process.env.NODE_ENV ! production) { globalForPrisma.prisma prisma } export default prisma原因是开发模式下文件一变模块代码就会重新执行每次都new PrismaClient()就会不断新建连接最终撞上连接数上限。把实例挂到globalThis上就变成只建一次热更新后复用而生产环境模块只加载一次本就不需要缓存所以条件判断只在开发时生效。 怎么上线分支提升 Vercel上线前先把分支提升。为什么必须做main分支默认是开发角色只有被提升后才能承载生产流量pscale branch promote myshop main提升之后凭据二选一直接复用本地开发那组密码或用pscale password create新造一组生产凭据推荐。开发和生产各持一把钥匙任何一把泄露都可以单独轮换不影响另一边。接下来部署到 Vercel导入项目仓库在环境变量里加DATABASE_URL填入生产连接串包含生产分支可用凭据的那组。⚠️ 生产环境不要沿用仅限本地使用的分支凭据连接串保留?sslacceptstrict保住传输加密。还有一点可以放心页面全部是服务端渲染没有构建期连库的环节。部署完成后每次请求都由服务端实时查库改库即生效。 卡住了排错速查现象原因动作PrismaClientInitializationError连接失败连接串里有占位符没替换或域名后带了多余路径对照 CLI 返回的四个字段逐个核对保留?sslacceptstrict页面能打开但没有数据漏了db push或db seed先 push 建表再 seed 灌数据种子脚本报找不到.env变量命令不是在项目根目录执行的回到根目录重跑seed.ts与prisma.config.ts都靠dotenv/config读环境变量开发期报连接数超限某处直接new PrismaClient()绕过了单例统一从lib/prisma.ts导入复用全局实例明文密码找不回来创建时只展示过一次pscale password create新建一组更新连接串收尾可迁移的部分换成真实业务改的是schema.prisma里的模型和data.ts里的数据流程一行不动。描述模型、推送结构、灌入数据、服务端取数这四个动作就是主干。分支机制和凭据隔离是云数据库相对本地数据库多出来的两个习惯开发与生产共用一套服务却各持独立的钥匙可轮换、可审计。这套骨架搭完新项目接库的工作基本就算结束了。【免费下载链接】next.jsThe React Framework项目地址: https://gitcode.com/GitHub_Trending/next/next.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考