T3 Stack 全栈指南：Next.js + TypeScript + tRPC + Prisma 一体化脚手架

这次我们来看 T3 Stack。如果你的项目需要同时搞定前端页面、后端接口、数据库访问和类型校验，直接在 Next.js 里自己拼技术选型，其实是一件很费精力的事：路由怎么组织、接口层用什么、ORM 选哪个、类型怎么保证前后端一致。T3 Stack 就是为这个问题给出的组合答案。它由 t3.gg 的 Theo 等人在社区中推广，落地形式是 create-t3-app 这个开源脚手架。T3 Stack 不是新的框架，而是把 Next.js、TypeScript、tRPC、Prisma、Tailwind CSS、NextAuth 这些成熟工具，按一套默认约定组合起来，让你一条命令拿到一个可运行的全栈项目骨架。

核心特点可以快速列一下：第一，一条命令初始化项目，并且默认开启 TypeScript 严格模式，类型约束从第一行代码就开始生效；第二，用 tRPC 做接口层，前端调用后端方法时不需要手写 REST URL，前后端类型由编译器整体推导，接口变更不靠文档提醒，而是靠类型报错直接暴露；第三，ORM 可以在 Prisma 和 Drizzle 之间选择，建表、迁移、查询都纳入了工程化流程；第四，UI 层默认集成 Tailwind，样式迭代速度快，写页面不需要频繁切换 CSS 文件；第五，整个链路看起来重，但实际开发不需要高配 GPU，普通开发机就能跑，对显卡完全没要求。

这篇文章会带你完成：环境准备与版本检查、使用 create-t3-app 初始化一个全栈项目、读懂 T3 Stack 的项目目录、开发一个 tRPC 接口并用前端页面验证、接入 Prisma 做数据建模和数据库迁移、跑一次全栈联调测试、观察开发服务器的资源占用、整理常见报错排查清单。内容偏实战，直接按“能不能用、怎么跑通、失败怎么查”的顺序来写。

1. 核心能力速览

T3 Stack 的定位不是“面试框架”，而是解决一个非常具体的问题：在一个 TypeScript 全栈项目里，如何让前端到后端再到数据库的整条链都类型安全。它的选择不一定是最新潮的，但一定是当前社区里验证过的组合。如果你的目标是快速做一个带数据库交互的 Web 应用，同时希望代码结构干净、后续方便维护，这个技术栈可以节省大量选型和配置时间。

2. 适用场景与使用边界

T3 Stack 适合以下几类场景：第一，快速原型和全栈工具，比如内部管理后台、报表系统、自动化配置页面，这类项目核心是“前端表单 + 后端接口 + 数据表”的标准组合，用 T3 Stack 默认结构非常合适。第二，中小型应用，团队人数不多，前端和后端由同一个人或同一个小团队维护，TypeScript 全栈可以让前后端共用类型定义，减少联调成本。第三，学习 React 全栈，想理解 Next.js App Router 怎么做服务端渲染、tRPC 怎么把函数调用变成 HTTP 请求、Prisma 怎么把 TypeScript 对象映射成 SQL，T3 Stack 是一个清晰的参考资料。

但也有不适合的情况。如果项目已经有一个独立的 Java、Go、Python 后端，只缺一个前端工程，那 T3 Stack 里的 tRPC 可能和现有后端冲突，强行接入会绕很多弯；如果做的是纯静态博客、落地页，不需要数据库和接口，直接使用 Next.js 基础模板更轻；如果对前端包体积极端敏感，比如希望首屏加载尽量小，那 tRPC 客户端和全套依赖会带来额外体积，需要评估收益是否大于成本。

使用边界上要特别注意三点。create-t3-app 是开源项目，生成的代码你拥有，但上游依赖各自有许可证，商用前建议检查依赖列表的授权情况。项目会生成.env文件，里面可能放数据库连接串和 NextAuth 密钥，这个文件不能提交到 Git，否则等于把数据库密码公开。如果项目将来要面向真实用户，尤其是涉及用户资料、订单、手机号等隐私数据，必须做鉴权、访问控制、操作日志和隐私合规审查，不能只开着公开接口方便调用。

顺手提醒一句：本地写演示项目时，数据库用测试数据就好，不要拿真实用户信息去填充开发库。正式发布前把开发数据清理一遍，避免测试数据被搜索引擎抓走或泄露。

3. T3 Stack 本地部署环境准备

开始之前，先确认本机环境。T3 Stack 的安装工具是 Node.js，所以第一步是确认 Node 版本。建议使用 Node.js 18 或更高版本，具体版本要求以 create-t3-app 官方文档为准。可以使用下面命令检查：

node -v npm -v

如果你习惯用 pnpm，可以额外安装 pnpm。pnpm 对依赖的磁盘占用控制更好，T3 社区中也比较常见：

npm install -g pnpm pnpm -v

数据库方面，实验阶段推荐 SQLite。SQLite 是一个文件数据库，不需要单独安装数据库服务，Prisma 会直接操作本地文件，最省事。等应用上线，再切换到 PostgreSQL 或 MySQL。这一点对快速跑通流程非常重要：你不需要先装一个数据库，建库、配账号、开端口，直接初始化项目就能开始操作。

接下来确认网络能正常访问 npm registry。如果安装依赖时经常超时，可以在项目目录下建一个.npmrc文件，或者执行一次性的 registry 配置，将 npm 源切换到国内镜像。这属于常规网络优化，不是特殊工具：

npm config set registry https://registry.npmmirror.com

最后检查磁盘空间。Node 项目安装依赖通常会占用几百 MB 以上，不同依赖版本差异较大，以实际机器为准。至少预留 1GB 以上空间会更稳。不需要 GPU，不需要 CUDA，不涉及显存，这一点和 AI 模型类项目不同。

4. 使用 create-t3-app 初始化项目

打开终端，进入你准备存放项目的目录，执行：

pnpm create t3-app@latest my-t3-app

如果使用 npm：

npm create t3-app@latest my-t3-app

执行后，create-t3-app 会让你选择需要启用的模块，常见选项包括 TypeScript、Tailwind CSS、tRPC、Prisma、Drizzle、NextAuth。如果你只是想快速体验全套流程，建议开始先把核心选项打开。这样会生成带 Tailwind、tRPC、Prisma 和 NextAuth 的完整模板。如果你只想做最小接口练习，也可以只选 tRPC 加 Prisma，后续再手动补其他模块。

交互过程中还会询问项目名称、是否使用 Git 初始化等。项目名可以直接用终端参数指定，不过要在交互提示里确认。初始化完成后看到提示信息，说明项目骨架已经生成。

进入项目目录，确认依赖已经安装完毕。不同版本行为不同，如果初始化过程中没有自动安装依赖，则手动执行：

cd my-t3-app pnpm install

随后启动开发服务器：

pnpm dev

启动成功后，浏览器打开 http://localhost:3000 。第一次访问会看到 T3 Stack 默认首页，页面主体是模板介绍和一些示例区块。这一步如果页面渲染正常，说明 Next.js、Tailwind、tRPC 的基础链路已经跑通。

5. 项目结构与核心目录说明

T3 Stack 生成的项目目录比普通 Next.js 模板更规整。下面是一个常见结构示例，不同版本会有些微差异，但核心目录基本保持一致：

my-t3-app/ ├── prisma/ │ ├── schema.prisma │ └── dev.db ├── src/ │ ├── app/ │ │ ├── api/ │ │ ├── layout.tsx │ │ └── page.tsx │ ├── server/ │ │ ├── api/ │ │ │ ├── root.ts │ │ │ ├── routers/ │ │ │ │ └── post.ts │ │ │ └── trpc.ts │ │ └── db.ts │ ├── trpc/ │ │ ├── react.tsx │ │ └── server.ts │ └── styles/ │ └── globals.css ├── .env ├── .env.example ├── package.json └── tsconfig.json

接下来逐个说明关键文件的作用。prisma/schema.prisma是数据库模型定义文件，所有的数据表结构都在这里用 Prisma Schema 语法声明。改完 schema 后，执行迁移命令就会在数据库里生成对应的表。.env存放环境变量，最重要的是DATABASE_URL数据库连接串和 NextAuth 需要的密钥；.env.example是提交到 Git 的示例文件，只放变量名不放真实值，方便其他开发者复制后填写。

src/server/api/trpc.ts是 tRPC 初始化核心文件，里面会创建 tRPC context、router、procedure 等基础对象。src/server/api/root.ts是根路由，所有业务 router 都要挂载到这里，前端才能通过api.xxx.yyy调用。src/server/db.ts负责初始化 PrismaClient 实例，后续所有数据库查询都通过上下文里的ctx.db来执行。src/trpc/react.tsx是前端 React 绑定，包装了 tRPC 客户端，并提供api对象给组件调用。

理解这个结构之后，新增一个业务模块的基本路径就是：在prisma/schema.prisma里加 model，在src/server/api/routers/下新建 router 文件，把 router 挂载到src/server/api/root.ts，再在前端组件里调用对应 procedure。整个过程不需要手写 Controller、Service、URL 映射，路径短且清晰。

6. tRPC 接口开发与 API 验证

了解了目录结构后，现在实际开发一个 tRPC 接口。T3 Stack 默认的root.ts里通常有一个示例 procedure，可以在它的基础上扩展。下面是一个常见的hello接口定义，输入一个 name 参数，返回问候语和时间戳：

// src/server/api/root.ts import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; export const appRouter = createTRPCRouter({ hello: publicProcedure .input(z.object({ name: z.string().min(1) })) .query(({ input }) => { return { message: `Hello, ${input.name}!`, now: new Date().toISOString(), }; }), }); export type AppRouter = typeof appRouter;

这里有两个关键点。第一，input用 Zod 声明，运行时校验和 TypeScript 类型推导来自同一个定义，不会出现“校验规则和类型不一致”的问题。第二，query表示这是一个查询操作，适合读数据；如果是要写数据，通常用mutation。当你把文件保存好，Fast Refresh 会自动更新类型，前端立刻就能感知到接口签名。

前端调用方式很直接。在客户端组件中使用api.hello.useQuery：

"use client"; import { api } from "~/trpc/react"; export function HelloBox({ name }: { name: string }) { const hello = api.hello.useQuery({ name }); if (hello.isLoading) { return <div>加载中...</div>; } if (hello.isError) { return <div>请求失败：{hello.error.message}</div>; } return <div>{hello.data.message}</div>; }

把这个组件放进src/app/page.tsx后，浏览器访问首页，页面应该能看到“Hello, xxx!”的输出。如果显示加载中，再看终端日志；如果显示请求失败，优先检查 tRPC Provider 是否已经在根布局中挂载。T3 Stack 模板默认会在app.tsx或RootLayout中提供 Provider，自己新建组件时不要漏掉这层包裹。

如果不想走 tRPC 页面链路，也可以加一个独立的 Next.js Route Handler 做健康检查。这个接口适合用于部署后的连通性验证，不依赖 tRPC 前缀，直接通过 HTTP 返回 JSON：

// src/app/api/health/route.ts import { NextResponse } from "next/server"; export async function GET() { return NextResponse.json({ status: "ok" }); }

启动开发服务器后，可以用浏览器或 curl 验证：

curl http://localhost:3000/api/health

能收到{"status":"ok"}说明 Next.js 应用本身工作正常。

7. Prisma 数据模型与数据库迁移

tRPC 解决的是接口层类型安全，要真正让数据落库，还需要数据库表。T3 Stack 默认集成了 Prisma，数据库模型定义在prisma/schema.prisma。以 SQLite 为例，简单设计一个 Post 模型：

// prisma/schema.prisma generator client { provider = "prisma-client-js" } datasource db { provider = "sqlite" url = env("DATABASE_URL") } model Post { id String @id @default(cuid()) title String content String createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

修改完 schema 后，在项目根目录执行迁移命令：

pnpm db:migrate

如果 create-t3-app 的模板没有提供db:migrate脚本，可以直接使用 npx：

npx prisma migrate dev --name init

迁移成功后，Prisma Client 会自动重新生成。此时数据库里会出现Post表，接下来就可以在 tRPC router 里写 CRUD 逻辑。新建src/server/api/routers/post.ts：

// src/server/api/routers/post.ts import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; export const postRouter = createTRPCRouter({ create: publicProcedure .input( z.object({ title: z.string().min(1), content: z.string(), }) ) .mutation(async ({ ctx, input }) => { return ctx.db.post.create({ data: { title: input.title, content: input.content, }, }); }), getAll: publicProcedure.query(async ({ ctx }) => { return ctx.db.post.findMany({ orderBy: { createdAt: "desc" }, }); }), });

然后在根 router 中挂载：

// src/server/api/root.ts import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; import { postRouter } from "~/server/api/routers/post"; export const appRouter = createTRPCRouter({ post: postRouter, }); export type AppRouter = typeof appRouter;

保存文件后，开发服务器会自动重新生成类型。前端组件里就可以调用api.post.getAll.useQuery()查询列表，调用api.post.create.useMutation()写入数据。这里体现出的优势是：数据库表字段、后端入参、前端组件变量，三处类型由同一个链路推导出来，少了手动对字段名的环节。

数据库迁移是整个流程中最容易出问题的一步。常见错误包括：.env里DATABASE_URL没配置或格式错误；Prisma schema 语法不对；迁移命令执行时数据库文件被其他程序占用。排查时先看DATABASE_URL是否指向了正确的file:./db.sqlite路径，然后看终端报错信息是连接问题还是 schema 语法问题。

8. 全栈联调与功能测试

接口和数据库都就绪后，可以做一次完整的全栈联调。测试目标很简单：前端提交一个 Post，刷新后内容还在，说明数据确实写库成功。

首先在页面中写一个简单的 Post 列表和创建表单组件：

"use client"; import { useState } from "react"; import { api } from "~/trpc/react"; export function PostList() { const posts = api.post.getAll.useQuery(); const createPost = api.post.create.useMutation({ onSuccess: () => { void posts.refetch(); }, }); const [title, setTitle] = useState(""); const [content, setContent] = useState(""); return ( <div> <input value={title} onChange={(e) => setTitle(e.target.value)} placeholder="标题" /> <input value={content} onChange={(e) => setContent(e.target.value)} placeholder="内容" /> <button onClick={() => { createPost.mutate({ title, content }); }} > 创建 Post </button> <ul> {posts.data?.map((post) => ( <li key={post.id}> <strong>{post.title}</strong> : {post.content} </li> ))} </ul> </div> ); }

联调测试的预期结果包括：页面一打开就显示数据库里已有的 Post 列表；输入标题和内容后点击按钮，新的 Post 出现在列表顶部；刷新页面后新数据不掉。这三个标准都满足，说明本地开发链路是通的。

如果想要验证批量操作，比如快速生成 10 条测试数据，可以在项目里写一个脚本。T3 Stack 本身没有内置批量任务队列，但脚本方式足够覆盖开发阶段的批量造数需求。先安装 tsx：

pnpm add -D tsx

然后创建scripts/seed.ts：

// scripts/seed.ts import { PrismaClient } from "@prisma/client"; const prisma = new PrismaClient(); async function main() { const posts = Array.from({ length: 10 }, (_, i) => ({ title: `批量任务 ${i + 1}`, content: `这是第 ${i + 1} 条测试内容`, })); const results = await Promise.allSettled( posts.map((data) => prisma.post.create({ data })) ); const successCount = results.filter((r) => r.status === "fulfilled").length; console.log(`成功写入 ${successCount} 条`); } main().finally(() => prisma.$disconnect());

运行脚本：

npx tsx scripts/seed.ts

SQLite 对并发写入比较敏感，如果Promise.allSettled并发写导致database is locked报错，可以把批量逻辑改成串行 for 循环，或者减少每次批量写入的条数。生产环境遇到高频写入场景，建议直接换 PostgreSQL，SQLite 更适合单机、低并发的开发阶段和使用场景。

9. 资源占用与性能观察

T3 Stack 不涉及 GPU 和显存，性能观察主要看 CPU、内存、磁盘和数据库响应时间。开发模式下，Next.js 编译是资源开销的大头，首次启动会比较慢，后续页面访问会快很多，这是正常的。你可以打开任务管理器或活动监视器，找到 node 进程，观察内存占用。不同项目依赖数量不同，内存占用会有差异，以本机实际为准，如果发现内存长期异常上涨，再排查是否有循环请求或 Prisma 连接未释放。

在 Linux 或 macOS 上，可以使用ps命令查看 node 进程：

ps aux | grep node

关注的是内存列和 CPU 列。项目刚启动时 CPU 占用可能较高，因为 Next.js 要做模块编译；页面编译完成后 CPU 会降下来。如果开发服务器长期高频占用 CPU，考虑是不是有无限触发的 tRPC 查询、页面里循环调用了接口，或者某个组件刷新频率过高。

影响性能的几个关键因素要提前知道。数据库查询是最常见的瓶颈，Prisma 查询如果没有限制返回条数，数据量大了以后会越来越慢；给列表查询加上take参数和排序索引很有必要。tRPC 的输入输出数据量大时，序列化和传输时间会增加，建议不要把整个大对象直接返回给前端。前端组件如果用客户端组件包裹了太多内容，会导致浏览器执行过多 JavaScript，尽量把静态部分放到服务端组件里。

构建生产包的内存和耗时也要有预期。执行pnpm build时，Next.js 会做全量编译，内存占用会高于开发模式。如果项目变大，可以考虑调整 Next.js 构建缓存配置，或者把重型查询改成分页加载。这些优化不是 T3 Stack 专属，但在这个全栈架构下很有效。

10. 常见问题与排查方法

以下表格整理了 T3 Stack 开发过程中的常见问题，覆盖初始化、启动、数据库、tRPC、构建等阶段。

遇到问题时，第一步永远先看终端输出。Next.js 开发模式的报错信息通常会把错误堆栈和对应文件路径直接打在终端里，比在浏览器里猜根因高效得多。如果终端没有输出，再看浏览器控制台和 Network 面板，确认请求是 pending、还是 500、还是根本没发出。

11. 最佳实践与使用建议

第一，第一次运行 T3 Stack 时不要急着写业务代码，先把最简链路跑通。项目初始化成功，访问默认首页正常，api.hello能返回数据，然后再引入 Prisma 和数据库。这样每一步都只引入一个变量，出问题时定位范围小。

第二，保持目录职责清晰。数据库模型放到prisma目录，tRPC router 放到src/server/api/routers，前端页面组件放到src/app，全局样式放到src/styles。T3 Stack 已经把这套结构搭好了，不要为了“快”把所有逻辑堆到page.tsx里。项目一旦变大，目录混乱带来的维护成本会迅速上升。

第三，环境变量管理要严格。不要把真实密钥直接写进.env后提交到 Git，也不要把.env改成 npm 包发出去。项目仓库里维护一个干净.env.example，每个新的环境变量都要在示例文件里登记。团队成员拿到项目后，复制示例文件并本地填写自己的密钥，这是最基本的协作规范。

第四，数据库迁移需要纳入版本管理。每次修改schema.prisma后生成的迁移文件要提交到 Git，这样其他开发者执行pnpm db:migrate才能得到相同结构的表。如果迁移文件丢失，数据库结构只能手工对齐，容易出线上事故。

第五，使用 Zod 校验所有外部输入。tRPC 的input()不是可选的装饰，而是接口安全的一道防线。哪怕内部项目，也要对 title、content 这些字段做长度和类型校验，后端不要相信前端传来的任何数据。

第六，批量任务要加日志和失败重试。上文中的 seed 脚本是简单示例，真实生产环境如果要做批量数据导入，通常要记录每个任务的成功失败状态、失败原因、重试次数，并用队列方式控制并发，避免大量请求同时打到数据库。

第七，上线前做安全检查。如果接口涉及用户资料、文件上传、支付信息等敏感数据，必须配置鉴权。T3 Stack 默认带 NextAuth 选项，但需要认真配置 session 策略和访问控制，不能只停留在“能登录”的状态。发布到公网后，建议限制管理后台的访问 IP，并定期检查日志。

最后，保留一套最小可运行模板。我建议在团队里维护一个精简版 T3 Stack 基线项目，里面只有认证、数据库连接、健康检查接口和基础布局，新业务从这套基线复制，而不是让每个开发都重新从交互式的 create-t3-app 开始选择一遍模块。

12. 总结与下一步

T3 Stack 最值得尝试的地方是类型安全链路。从 React 组件调用 tRPC，到后端 router 的参数校验，再到 Prisma 数据库模型，TypeScript 类型和运行时校验贯穿了整条数据流。对这种开发方式不熟悉的人，第一次体验会非常明显：因为前端一个字段写错，编译器直接告诉你问题在哪，而不是等到运行时才发现接口 500。

按本文的顺序，最先应该验证的就是 project 初始化后访问默认首页，然后加一个简单的 hello 查询；这个链路能跑通，说明环境没有问题，后续加数据库和业务路由才有意义。最容易踩的坑基本集中在 Prisma 数据库连接串、tRPC 类型缓存不同步、环境变量缺失这三类，遇到报错不要慌，先看.env，再清一次.next和node_modules/.cache，通常能解决大部分开发期问题。

接下来可以考虑的方向：接入 NextAuth 增加登录和权限控制；把 SQLite 切换成 PostgreSQL，部署到服务器或 Vercel；用 Drizzle 替换 Prisma 体验更轻量的查询方式；把 tRPC 的调用方式封装成独立 client，供非 React 场景使用。如果团队已经有现成的后端服务，也可以只拿 T3 Stack 做前端项目，把 tRPC 部分换成纯 HTTP 调用，保留 Tailwind 和 Next.js 的开发体验。

这篇内容是按“能否跑通、怎么部署、怎么验证、怎么排错”的思路来写的。T3 Stack 本身不是复杂框架，但它的组合项多、目录约定细，照着上面流程操作一遍，比单纯看文档能更快建立整体概念。建议收藏备用，下次初始化全栈项目时，直接按这个清单走。