前阵子我把一个攒了很久的想法落成了代码项目代号就叫 t3code。这个名字没什么玄机纯粹因为它整条链路都跑在 T3 Stack 上——TypeScript Next.js Tailwind CSS tRPC Prisma 这一套组合。为什么愿意把这个代号和整套方案拿出来细讲因为我在搭建过程中踩过不少文档里没写清楚的坑也确认了这套技术栈在小团队协作里的实际体验端到端的类型安全确实能实打实提升开发效率而不是营销号吹出来的概念。这篇内容适合正在考虑用 T3 Stack 起步、或者已经初始化了项目但还没理清各模块关系的朋友也适合想了解 tRPC 和 Prisma 在生产环境怎么配合使用的开发者。我会从初始化讲起一路聊到数据库建模、认证中间件、部署优化最后分享一些只有真跑过项目才会知道的细节。1. 项目定位我为什么把一切都押在 T3 这套组合上1.1 T3 Stack 到底解决了什么问题先说清楚一件事T3 Stack 不是一个框架它是一套工具的共识。核心是把 TypeScript 的类型系统从头用到尾让前端、后端、数据库三层的类型尽量互通减少上下文切换时的心智负担。t3code 这个项目我选择了全套接入Next.js 负责页面和 API 路由tRPC 负责端到端类型安全的 API 调用Prisma 负责数据库访问Tailwind 管样式NextAuth 处理登录鉴权。这个组合最舒服的地方在于你在写数据库查询的时候IDE 已经知道返回的字段长什么样在组件里调用后端方法的时候参数的校验错误会在编译期就蹦出来根本拖不到浏览器控制台。我见过不少团队在 REST 和 GraphQL 之间反复横跳最后都用回了一种老办法前后端各写一套类型定义Api 接口靠手写文档维护。这种方式不是不能干只是每次字段变动都要同步好几个文件时间一长必然有一边忘记更新线上的报错就成了家常便饭。T3 这套组合的核心价值就是用编译器的力量强制类型一致把这类问题从靠自觉变成靠机制。1.2 t3code 适合什么场景不适合什么场景以我实际跑下来的体感这套组合最适合的是中后台系统、内部工具、个人全栈项目以及需要快速迭代的 MVP。因为信息密度高、复用性强你不需要为每个接口单独写 controller不需要维护 OpenAPI 文档一个 router 文件就是一份自解释的 API 契约。团队哪怕只有一个后端和一个前端沟通成本也能明显降下来。但如果你的项目需要被第三方大规模调用 API或者需要非常严格的 API 版本管理那纯 tRPC 就不太够用通常得在外面再包一层 REST 或 GraphQL 网关。还有一个我不太推荐用 T3 的场景是极其复杂的实时协作类应用tRPC 的 subscription 目前还是走 WebSocket 或 SSE生态和稳定性比专门做实时同步的方案差一些。所以选型的时候别只看火不火要看你自己的业务模型是不是适合这套类型安全优先的架构。1.3 初始化前我对项目骨架的预想正式动工前我把 t3code 需要的核心模块列了个清单内容管理后台、面向用户的前台页面、一个简单的权限体系、数据统计看板。这些模块都有共同特点——表单多、列表多、操作路径固定非常适合用 tRPC 的 query 和 mutation 把数据流收敛起来。同时我也提前确定了一个原则所有路由都放在服务端组件里调用客户端组件只负责交互状态。这样既能发挥 Next.js 的 RSC 优势又能让 tRPC 的调用路径更清晰。这些预想会直接影响后续 Initialization 时勾选哪些选项所以不建议上来就无脑默认全选。2. 初始化细节create-t3-app 每个选项背后的取舍2.1 创建项目与脚手架选项解析初始化 t3code 我用的自然是官方脚手架一条命令搞定npx create-t3-applatest t3code这条命令会引导你选择是否启用 Next.js、Tailwind CSS、tRPC、Prisma、NextAuth、ESLint、Prettier。很多人以为这里只是多选题实际上每个选项都会影响后续生成的项目结构和依赖树。以下是我根据 t3code 实际需求做的选择以及每项的理由选项选择理由Next.js是App Router 模式下体验 RSC 优势路由和渲染逻辑统一Tailwind CSS是快速搭 UI尤其在迭代原型阶段效率非常高tRPC是这是类型安全的核心没有不选的道理Prisma是数据库访问层搭配 TypeScript 和 tRPC 非常自然NextAuth是后续要做登录和权限基础认证不必自己造轮子ESLint是多人协作时统一代码风格降低 review 成本Prettier是格式化交给工具专注业务代码这里有一个值得展开说的点如果你确定项目不需要登录完全可以不勾 NextAuth后续手动加 provider 也不复杂。但如果你有这个需求却想省事建议从一开始就勾上因为 generate 出来的[...nextauth].ts文件结构是官方维护的比自己从零拼稳定得多。2.2 生成后的目录结构与职责划分初始化完成之后src/server和src/trpc两个目录会自动生成很多人第一次看会觉得多此一举其实这是 T3 特意设计的边界src/server/db.ts统一导出 Prisma Clientsrc/server/api/routers/放各业务域的 routersrc/server/api/trpc.ts里做 procedure 的基类封装。只要所有子 router 都基于这个基类创建就能统一控制鉴权、日志、错误处理。后面扩展业务的时候只需要在root.ts注册新 router三行代码搞定不需要四处散落初始化逻辑。目录结构看似只是文件分类的问题实际上决定了你在团队里怎么组织代码 review。我见过很多项目前期没分好层到后期只能靠约定去约束一旦新人加入就乱了。t3code 从一开始就按这个结构维护每个人新增功能时都知道router 放这边、组件放那边、schema 放这边这种秩序感在中期迭代时特别值钱。3. tRPC 全链路类型安全从数据库到组件的完整链路3.1 procedure 和 router 的基础写法tRPC 里两个最基本的概念是 router 和 procedure。router 相当于一个 API 命名空间procedure 则是具体可调用的端点。实际操作中我会把每一个业务动作拆成单独 procedure比如获取文章列表、 创建文章、更新用户昵称。下面是一个最简单的 query 示例import { protectedProcedure } from ~/server/api/trpc; export const postRouter { list: protectedProcedure .input(z.object({ page: z.number().min(1).default(1) })) .query(async ({ ctx, input }) { const posts await ctx.db.post.findMany({ skip: (input.page - 1) * 10, take: 10, orderBy: { createdAt: desc }, }); return { posts }; }), };在这个 procedure 里zod schema 被写在 input 的位置然后在 query 回调里能拿到类型完整的input和ctx。ctx里通常放着 Prisma Client 和当前 session只要在后端配置好了createContext前端调用的地方就能从返回的 queried data 拿到类型。整个过程完全不需要手动声明字段类型IDE 也会自动提示这就是类型安全真正落地后的体感。3.2 客户端调用与 React Query 的集成tRPC 的客户端侧封装在trpc/next和trpc/react-query两个包里。框架会自动提供api.post.list.useQuery()之类的 hooks底层则依赖 TanStack Query 管理请求状态。这意味着你天然拥有了 loading 状态、缓存、失效刷新这些能力不需要再额外引入请求状态管理库。在 t3code 的文章列表页我实际是这样用的use client; import { api } from ~/trpc/react; export function PostList() { const [page, setPage] useState(1); const { data, isPending } api.post.list.useQuery({ page }); if (isPending) return div加载中.../div; return ( div {data?.posts.map((post) ( article key{post.id} h2{post.title}/h2 p{post.content}/p /article ))} /div ); }这里值得注意的一点是useQuery接受的对象其实就是上面 zod schema 定义好的input如果你在前端传了额外字段TypeScript 会在编译期直接提示错误。我实际体验中编译期报错这件事比什么文档都有用团队新人甚至不用专门学习接口协议看着类型提示基本就能猜出后端要什么。3.3 mutation 的乐观更新和错误回滚写操作是 tRPC 里最容易绕晕的部分因为一套优雅的方案往往涉及 mutation、缓存更新、错误处理三条链路。我在 t3code 里做创建文章的时候用的是 React Query 的 onMutate 做乐观更新api.post.create.useMutation({ onMutate: async (newPost) { await utils.post.list.cancel(); const prev utils.post.list.getData(); utils.post.list.setData(utils.post.list.getInfiniteData(), (old) old ? [{ ...newPost, id: temp }, ...old] : [newPost] ); return { prev }; }, onError: (err, newPost, context) { utils.post.list.setData(utils.post.list.getInfiniteData(), context?.prev); }, onSettled: () { utils.post.list.invalidate(); }, });乐观更新的核心是给用户即时反馈但代价是如果后端返回失败你必须有能力把 UI 回滚到之前的状态。这里onError里做的就是利用 context 中保存的上一份数据恢复列表。这种写法其实不复杂但要理解 React Query 缓存和 tRPC 之间的协作关系第一次上手的人多半会卡在invalidate的时机上。我的经验是如果拿不准是否要做乐观更新先别做直接等请求完成再刷新数据也完全可以。等业务稳定了再优化交互比一上来就冒险折腾缓存回滚要稳妥得多。3.4 context 设计与鉴权注入tRPC 的 context 是在每次请求时创建的我通常会把数据库 session 放进去让每个 procedure 都能直接访问当前登录用户。默认的createContext大概是export const createTRPCContext async ({ headers }: { headers: Headers }) { const session await getServerAuthSession(); return { db, session, }; };这个过程有一个容易被忽略的顺序问题如果用getServerAuthSession()去拿 session性能开销会比较大因为它每次都会向 NextAuth 的数据库 session 表发起查询。在 t3code 里我通过配置 JWT 作为 session strategy 来缓解把用户信息编码进 JWT避免每个 tRPC 请求都查库。实测下来在冷启动之后单个请求的鉴权开销能低一个数量级。不过这种做法的代价是用户被踢下线后的 session 状态会有一段延迟具体的取舍看业务容忍度。4. Prisma 数据建模从 schema 到真实查询的坑与解法4.1 t3code 的基础模型设计数据库层面t3code 核心模型有两个User 和 Post。为了演示关联我故意设计成一篇 post 可以包含多个 tag而 tag 是独立表形成多对多关系。Prisma schema 里是这样写的model User { id String id default(cuid()) name String? email String unique posts Post[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Post { id String id default(cuid()) title String content String published Boolean default(false) author User relation(fields: [authorId], references: [id]) authorId String tags Tag[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Tag { id String id default(cuid()) name String unique posts Post[] }为什么 id 用cuid()而不是自增数字因为在分布式部署、第三方 API 对接或者数据导入导出时cuid 避免了数字型 id 的冲突问题而且 Prisma 对它支持得很好。不过你要注意cuid 类型是字符串在关系数据库里会占用更多空间索引效率略低于 bigint但对于这个量级的业务完全不是瓶颈。4.2 include、select 与 N1 查询问题Prisma 有个甜蜜陷阱include太方便了容易让人写出深层嵌套查询。一个典型的反面案例是在文章列表页用include: { author: true }而在另一个页面又需要author的 posts 列表。这样其实触发了大量关联查询尤其列表 N 条数据时应用层不需要的额外数据会拖慢响应。我处理这个问题的原则是查询时只 select 需要的字段能避免 include 就避免 include。比如文章列表页只需要用户昵称就只 selectauthor: { select: { name: true } }不要连 email 和所有令牌字段都拉回来。与此同时配合 Prisma 的relationLoadStrategy或者直接分两次查询能有效避免 N1。真实项目里让我印象最深的是一次列表页接口因为 include 了 tags 和 author 的完整信息页面加载时间从 200ms 涨到了 1.2s最后通过减字段和加索引修复回到 150ms 左右。这类优化做起来不复杂关键是得有排查的意识和耐心。4.3 迁移流程与团队协作注意事项schema 改了之后需要执行npx prisma migrate dev --name xxx生成迁移文件并同步数据库。团队协作时最忌两个人同时对同一个 schema 改出冲突迁移然后在 dev 分支互相覆盖。我在 t3code 项目里定了个规矩每个功能分支只改自己的业务域的表merge 前先migrate dev并且把迁移文件当作代码一样走代码 review。这样能最大程度避免迁移文件冲突。另外一个容易被忽略的事production 环境的数据库迁移不要在跑业务请求的时候执行。如果一定要在线迁移务必先备份数据并且尽量选择服务低峰期。Prisma 的 migrate deploy 默认会直接执行如果中途出错数据一致性会受到挑战。稳妥的做法是先在 staging 环境完整跑一遍再把同样的迁移文件应用到 production。5. NextAuth 认证集成登录流程与中间件保护5.1 配置 Provider 和 Session 策略t3code 里我用 NextAuth 做谷歌登录和服务端鉴权。因为只是内部工具没有复杂的企业 SSO 需求所以配置起来不麻烦export const authOptions: NextAuthOptions { providers: [ GoogleProvider({ clientId: process.env.GOOGLE_CLIENT_ID!, clientSecret: process.env.GOOGLE_CLIENT_SECRET!, }), ], session: { strategy: jwt, }, callbacks: { jwt({ token, user }) { return token; }, session({ session, token }) { return session; }, }, };这里需要解释一下 session strategy 的选择。如果选database模式NextAuth 会在自己的 Session 表里存 session 记录每次请求都查一次库而jwt模式是把用户信息编码到 JWT 里请求时只需解码省掉一次数据库查询。我在 t3code 里选的是 jwt原因很简单当前用户量不大安全诉求主要靠 JWT 签名保障不需要额外的服务端会话存储。代价是用户主动退出到 JWT 失效之间会有一段时间的滞后但对内部工具来说完全可以接受。5.2 中间件保护路由表的组织方式有了认证配置接下来就要保护页面。T3 的默认结构里会有一个middleware.ts文件里面用数组定义了需要登录才能访问的路由和默认跳转地址export const config { matcher: [/dashboard/:path*, /admin/:path*, /settings/:path*], }; export default withAuth(async (req) { // 这里可以做自定义逻辑比如按角色区分访问权限 });我建议把需要保护的路径统一放在一个约定字符串里而不是直接散落在各处。t3code 里我维护了一个protectedRoutes.ts的常量文件把所有保护路由定义成数组中间件读取这个数组。这样权限变更时只需要改一处配置并且不容易漏掉某个路径。5.3 服务端组件里如何读取服务端 Session在 Next.js 的 App Router 下服务端组件可以用getServerAuthSession拿 sessionimport { getServerAuthSession } from ~/server/auth; export default async function DashboardPage() { const session await getServerAuthSession(); if (!session?.user) { redirect(/api/auth/signin); } return divWelcome {session.user.name}/div; }这里有个细节如果页面同时用了中间件和页面内校验会不会重复我的习惯是中间件负责路由级拦截页面内再用 session 判断做细粒度控制。这样即使中间件配置漏了页面本身仍有兜底安全性是双保险的。6. 部署上线Vercel 之外的生产环境优化方案6.1 Vercel 部署的体验与限制t3code 最开始是直接推到 Vercel 部署的。过程非常顺滑连接 GitHub 仓库设置环境变量push 代码就自动构建上线。Vercel 对 Next.js 的支持确实没话说尤其是 Edge Middleware 和增量静态再生成。但使用中我也遇到了实际限制Serverless Function 的执行时长受平台限制某些计算量大的接口偶尔会超时同时冷启动的问题在低流量场景下能明显感知到。如果项目是个人项目或者访问量不大Vercel 是最省心的选择完全不用管运维。但如果访问量上来了或者接口响应时间不稳定建议考虑自托管方案。6.2 Docker 反向代理自托管的完整思路第二种方案是用 Docker 把 Next.js 应用容器化然后用 Nginx 或 Caddy 做反向代理。我帮朋友的项目做过这套具体的 Dockerfile 核心内容大致如下FROM node:20-alpine AS base WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build FROM node:20-alpine AS runner WORKDIR /app COPY --frombase /app/.next ./.next COPY --frombase /app/node_modules ./node_modules COPY --frombase /app/package.json ./package.json EXPOSE 3000 CMD [npm, run, start]这类自托管方案需要额外考虑的是数据库的访问方式和环境变量管理。t3code 的数据库如果也在同一台机器上建议用 Docker Compose 把 Postgres 和 Next.js 应用编排在一起用内网地址连接避免暴露公网端口。6.3 构建体积与冷启动的优化手段无论哪种部署方式Next.js 应用都有一个共同敌人最终的 JavaScript 包体积。T3 项目默认已经做了一定程度的自动代码分割但某些第三方库比如图表库、富文本编辑器可能会整体打进某个 chunk。我排查 t3code 首页加载时间时发现一个图表库的单独 chunk 占了 300KB按需加载后立竿见影降到了 40KB。另外如果使用 Vercel可以配置output: standalone来减小部署包的体积配合正确的构建选项冷启动时间能得到改善。自托管时还可以用 PM2 常驻进程保持 Node 进程不退出避免每次请求都经历完整的进程冷启动。我实测下来PM2 常驻模式下 API 响应时间会比 serverless 冷启动快 3~5 倍但代价是需要自己的服务器能力。6.4 数据库备份与迁移的常规操作最后提醒一句不管部署在哪里数据库备份都不能省。t3code 用的 Postgres我写了一个简单的 cron 任务每天凌晨备份一次并保留最近七天的备份文件0 2 * * * pg_dump -U t3code -d t3code_db | gzip /backup/t3code_$(date %Y%m%d).sql.gz这种方案虽然朴素但真实生产环境里比花哨的自动备份平台更可靠。定期做恢复演练也很重要别等出问题了才发现备份文件已经损坏。7. 上线后的性能调优与监控心得部署上线只是开始真正的工程师功夫都在上线后。t3code 上线一周后我通过日志发现两个问题一是某些热门文章列表接口的数据库查询没有走索引导致响应变慢二是 tRPC 的错误日志太薄缺乏现场信息排错困难。针对第一个问题我在 Prisma schema 里给常用查询字段加了index比如 Post 表的published字段和authorId字段组合索引model Post { // ... index([authorId, published]) }实际效果是这个查询从全表扫描变成了索引范围扫描接口耗时从 800ms 降到 60ms。很多新手容易忽略 Prisma 的索引声明觉得客户端查询够快就不管但数据量一上来差距就非常明显。针对第二个问题我改造了 tRPC 的错误处理中间件把 requestId、路由地址、参数摘要都统一打到结构化日志里。之后排查线上报错时可以通过 requestId 把日志和前端网络请求关联起来定位速度大幅提升。这种普通人看着不起眼、关键时刻救命的小改动我建议每个上生产环境的项目都尽早做。T3 Stack 这套组合并不神秘也不需要多高深的技术背景才能驾驭。只要你愿意按它的规则组织代码就会发现自己少写了很多收尾性的类型定义和胶水逻辑。t3code 从初始化到上线跑了大半个月性能问题、数据库建模问题、认证问题都遇到过但最终都能在文档加推理的范围内解决。希望这篇实战记录能帮你少走几步弯路尤其是那些初始化之后一头雾水的时刻照着这个流程一步步推下去基本能把项目稳定落地。