最近手头的全栈项目做了一轮技术复盘我又把 T3 Stack 相关的一套代码实践很多人直接称为t3code整体过了一遍。简单说t3code 指的就是围绕 T3 Stack 生态写出来的那套工程代码——从脚手架、路由、数据库访问到前端调用全部用 TypeScript 串起来形成一个端到端类型安全的闭环。这篇文章我想从头聊清楚这套技术组合到底解决了什么问题怎么用它快速搭一个可维护的全栈项目以及我在实际项目中踩过、查过、绕过的一堆坑。如果你正在做全栈选型、准备用 Next.js 起步、或者团队里已经有人在推 TypeScript 但还没把前后端打通这篇文章应该对你有用。我不讲太多口号式的“最佳实践”只讲我实际动手时怎么理解、怎么配置、怎么避坑。1. T3 Stack到底在解决什么问题1.1 从命名说起T3不是新框架而是一套纪律先说清楚 T3 这个名字。它最早来自开发者 Theo 的个人博客域名 t3.gg后来社区把 TypeScript、Tailwind CSS、tRPC 这三个以 T 开头的核心工具凑在一起再加上 Next.js、Prisma、NextAuth.js 作为常用搭档就形成了大家常说的 T3 Stack。create-t3-app 就是把这套组合打包的一个脚手架。很多人第一次听到“T3 Stack”会以为是一个新框架其实不是。它更像一套代码组织纪律前端是 Next.js样式用 Tailwind数据访问用 PrismaAPI 层用 tRPC认证用 Auth.js然后整个链路里的类型系统都由 TypeScript 统一。create-t3-app 的作用不是像 Next.js 那样给你一个运行时而是把这些经过了大量项目验证的选择固化成一份开箱即用的默认工程模板。我个人的理解T3 的核心信条是“先端到端再说优化”——不要过早引入微服务、消息队列、复杂的 BFF 层先把一个单体全栈应用用最直接的方式跑通让数据从数据库一直流到 UI全程类型可追溯。等到规模确实撑不住了再按需拆。1.2 它真正解决的三个核心痛点第一个痛点是前后端类型脱节。传统全栈项目里后端定义好 REST 接口前端对着文档或者 Swagger 联调任何一个字段改名、类型变更都可能出现前端已经编译报错而文档还没更新的情况。tRPC 的方案是把服务端路由封装成一个个 procedure前端直接以“调用本地函数”的方式调用类型完全由 TS 静态推断出来。相当于你不需要额外维护一份 API 类型定义文件类型源只有一个。第二个痛点是样板代码过多。如果走 OpenAPI 路线你要维护 schema 定义、生成客户端、处理鉴权、手动写 loading 和 error 状态如果走 GraphQL你又得维护 resolver、fragment、codegen 那一大套。tRPC 把这一层压缩到很小——你只需要写好 router 和 procedure前端通过生成的 hooks 直接调用连请求路径和序列化细节都不用自己管。第三个痛点是选型困难。现在全栈方向的技术选型太多了同样是 Next.js 项目有人用 REST OpenAPI有人用 GraphQL有人用 server actions有人用 React Query 直接手写 fetch。create-t3-app 的价值在于给你一个默认合理、社区验证过的组合让你不用在项目第一天就陷入“这个库要不要上、那个数据库行不行”的争论。举个生活化的类比REST 就像去餐厅吃饭你按菜单点菜后厨上菜中间靠服务员传话菜单翻译得不到位就可能上错菜tRPC 更像是你和后厨直接说同一种语言你说“我要一份少盐的炒饭”对方直接就能理解不需要经过一个翻译层。当然这不是说 REST 不好而是在团队规模小、追求迭代速度的场景里少一层翻译就少一层出错概率。1.3 核心技术组合速览用表格整理一下这套组合里每个角色的定位模块推荐选型承担职责为什么选它Next.js应用框架页面、路由、服务端渲染、API路由托管React生态成熟社区大同时支持 Server ComponentTypeScript类型系统全链路类型统一从数据库到 UI 的类型源头编辑器提示体验好Tailwind CSS样式方案原子化样式减少 CSS 文件心智负担不用维护一堆 class 命名迭代 UI 速度快tRPCAPI 层服务端 procedure 定义与前端 hooks 生成端到端类型安全无需 codegenPrismaORM数据库访问与 schema 管理模型定义即类型来源迁移流程简单NextAuth.js认证登录态、会话、OAuth与 Next.js 整合度高session 类型可以透传这套组合里的每一个都不是“唯一正确”但它们的共同点是类型系统沟通顺畅。Prisma schema 生成数据库类型tRPC 的 procedure 接收和返回这些类型前端 hooks 再把它们暴露给组件你在组件里写代码时一个字段拼错了编辑器直接报错这个体验一旦用上就很难回头。2. 用create-t3-app快速起步2.1 初始化命令与选项思路起步命令非常简单在 Node.js 18 环境下执行npm create t3-applatest接下来会让你输入项目名称、选择是否初始化 Git、然后是一堆交互式选项。它会问你需要哪些包一般默认会勾选 Next.js、Tailwind CSS、tRPC、Prisma、NextAuth.js。下面还有几个关键问题使用 App Router 还是 Pages Router新项目建议 App Router已经在维护老项目的话可以选 Pages。使用 Prisma 还是 Drizzle如果你刚入门Prisma 的默认体验更顺Drizzle 更适合追求 SQL 手感、不想被 ORM 绑架的团队。使用 NextAuth.js只有当你的项目确实需要登录、权限时再勾上不然初始代码里会多出一堆 auth 相关文件和表结构。我给新手的建议是第一次用直接全默认选项过一遍先把工程跑起来感受一下目录结构和代码流转再考虑替换某一部分。因为 T3 这套默认组合的互相配合是经过验证的你上来就换掉其中一个反而可能踩到版本兼容的坑。2.2 初始化后的目录结构与约定项目初始化完成后你会看到这样的核心目录不同版本略有差异但大致保持一致├── prisma/ │ └── schema.prisma ├── src/ │ ├── app/ │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ └── root.ts │ │ └── auth.ts │ ├── trpc/ │ │ ├── react.tsx │ │ └── server.ts │ └── env.js ├── .env.example └── package.json我特别想解释几个关键文件的约定因为它们影响后面所有的开发节奏src/server/api/root.tstRPC 的根路由所有子路由在这里汇总前端拿到的 API 类型就是从这里推断出来的。src/trpc/react.tsx把 tRPC 客户端和 React Query 绑定生成可以直接在组件里用的 hooks。src/env.js环境变量运行时校验启动阶段就会提示你哪些变量缺失避免在代码里到处查process.env。prisma/schema.prisma数据库模型定义同时是类型系统的数据源头。这套“约定优先”的设计最大的收益是团队协作成本低。新人接手项目时不用翻一堆文档也能猜到新功能 先在 schema 加模型 - 写一个 router - 在页面里调 hook。我带了两个实习生做过一个内部工具项目第一天给他们讲完这个循环第二天他们就能自己加功能了这种流畅度在传统前后端分离的项目里很难达到。3. 核心环节实现让类型从数据库一路流到按钮3.1 从Prisma Schema到tRPC Router先说最核心的链路——数据库模型怎么变成 API。比如我们要做一个待办事项功能先在schema.prisma里定义模型model Todo { id String id default(cuid()) title String done Boolean default(false) createdAt DateTime default(now()) userId String user User relation(fields: [userId], references: [id]) }保存并执行npx prisma db push或npx prisma migrate dev后Prisma Client 就会生成对应的类型。接着在 tRPC 里写一个路由import { createTRPCRouter, publicProcedure } from ~/server/api/trpc; import { z } from zod; export const todoRouter createTRPCRouter({ all: publicProcedure.query(async ({ ctx }) { return ctx.db.todo.findMany({ orderBy: { createdAt: desc }, }); }), toggle: publicProcedure .input(z.object({ id: z.string() })) .mutation(async ({ ctx, input }) { const todo await ctx.db.todo.findUnique({ where: { id: input.id } }); if (!todo) throw new Error(待办不存在); return ctx.db.todo.update({ where: { id: input.id }, data: { done: !todo.done }, }); }), });你注意看这个todoRouter的类型会被推送到前端。前端不用再写任何interface Todo { ... }也不用定义请求和响应类型。因为ctx.db.todo.findMany()返回的类型已经由 Prisma 生成tRPC 会原样保留这个类型信息。为什么这里要用 zod 而不是手写类型判断因为 zod 不仅能在运行时校验输入还能在编译期推导出input的静态类型。一个z.object({ id: z.string() })写下去前端调用toggle时传入的参数类型就被精确限制住了多传字段、传错类型都会在编辑器里直接标红。3.2 前端调用链路的类型体验接下来是前端组件里怎么用。初始化后的src/trpc/react.tsx已经把 tRPC 的 hooks 和 React Query 整合好了你可以在任意客户端组件里这样调用use client; import { api } from ~/trpc/react; import { useUtils } from ~/trpc/react; // 假设 project 配置里有简化导出 export function TodoList() { const utils api.useUtils(); const { data: todos, isLoading } api.todo.all.useQuery(); const toggle api.todo.toggle.useMutation({ onSuccess: () { void utils.todo.all.invalidate(); }, }); if (isLoading) return div加载中.../div; return ( ul {todos?.map((todo) ( li key{todo.id} input typecheckbox checked{todo.done} onChange{() toggle.mutate({ id: todo.id })} / span{todo.title}/span /li ))} /ul ); }这里的useQuery和useMutation会根据你定义好的todoRouter自动推断出入参和返回值的类型。比如toggle.mutate({ id: todo.id })如果写成了{ idd: todo.id }编辑器立刻会报错。这种体验很像在调用一个本地异步函数而不是在拼接 HTTP 请求。如果你要做分页或者无限加载tRPC 也提供了对应包装api.todo.infiniteFeed.useInfiniteQuery()。它和useQuery的唯一区别在于你需要额外处理getNextPageParam类型同样全程自动推断。我实测下来这类“查列表 翻页 变更后失效”的场景T3 这套组合写起来比手写 REST 客户端清爽很多尤其是在项目后期频繁调整字段时改一处模型定义前端类型遍会自动跟着更新。3.3 Server Component 与 Client Component 的边界这是不少新手在 T3 项目里最容易乱的地方有了 tRPC是不是所有数据都该在客户端组件里取其实不是。T3 同时支持在 Server Component 里直接用 Prisma 查库也支持在 Client Component 里用 tRPC 调接口它们的适用场景很不一样。我的实践原则是这样页面初次渲染需要的数据、SEO 相关的数据、不需要频繁交互的数据尽量在 Server Component 里直接查询。比如博客文章详情、商品详情页、用户资料首页这些数据一次渲染到位没必要多走一层 API。反过来需要用户操作后刷新、需要分页加载、需要根据输入动态变化的列表型数据就用 tRPC 在客户端组件里取配合 React Query 的缓存和失效机制体验会很顺手。有人会担心Server Component 里直接查数据库是不是把后端逻辑泄露出去了其实不会。Server Component 的代码只在服务端执行不会打包到客户端。它和你写一个 API route 再在服务端 fetch 相比反而少了一次网络往返。T3 项目里常见的做法是把数据库访问封装在src/server目录下的模块中页面组件只负责调用这些模块从结构上保持清晰。再补充一点我的实测感受在 App Router 刚流行的时候我试过几乎所有数据都用 tRPC 在客户端取结果页面瀑布请求特别多LCP 性能评分很难看。后来把首屏静态数据迁移到 Server Component交互数据仍走 tRPC性能问题就缓解了很多。两种方式不是互斥的选对边界比选对库更重要。4. 实战避坑我在T3项目里踩过的坑4.1 认证会话相关的坑先说最常踩的会话拿不到。T3 项目用 NextAuth.js 做认证后很多人发现客户端组件里能正常拿到 session但 Server Component 或 API route 里用getServerSession拿到的却是 null。原因通常是 auth 配置没被正确传入或者你在app/api/auth/[...nextauth]/route.ts里没有导出GET和POST处理函数。我的建议是统一封装一个getServerAuthSession函数把 authOptions 集中管理起来然后在所有需要鉴权的地方都调用这个函数不要在业务代码里直接手动解析 cookie 或者 token。另外要注意authOptions里的 providers 回调签名一旦写错OAuth 登录流程会静默失败日志也不明显。如果你用 Playwright 做端到端测试还会遇到一个经典问题浏览器上下文里没有登录态所有依赖会话的页面都跳回登录页。我当时的解决方法是在测试初始化阶段调用 NextAuth 的getSession接口拿 token然后通过page.context().addCookies()注入 cookie而不是在测试里真的去走一遍 OAuth 流程这样稳定很多。4.2 tRPC与Next.js缓存/热更新的纠缠第二个高频坑是mutation 执行成功后页面列表不刷新。T3 默认把 React Query 和 tRPC 绑定你需要在 mutation 的onSuccess里调用invalidate()让相关 query 重新请求。很多人忘了这一步就以为 tRPC 的缓存有问题。但如果你在 Server Component 里也渲染了同一份列表那就不只是invalidate()能解决的事了。Server Component 的渲染结果可能被 Next.js 缓存客户端怎么刷新都没有变化。我的做法是列表页面如果既有 Server Component 首屏又有客户端交互更新就在 mutation 成功后额外调用router.refresh()它会让服务端组件重新渲染、客户端拿到最新 payload。这两个动作配合起来页面才能做到“既快又新”。还有一点容易忽略Next.js 14 以上对fetch请求默认有缓存策略比如force-cache如果你在 Server Component 里用原生 fetch 调第三方接口更新频率很低的数据可能一直显示旧值。需要实时数据的地方加上cache: no-store或者next: { revalidate: 5 }具体看数据新鲜度要求。4.3 类型推断不生效的常见原因第三种坑是类型突然“失灵”。明明 router 里定义好的 procedure前端调用却显示 any 或者报类型错误。我查过的原因里最常见的是第一你把ctx.db的类型手写成了any或者给某个 procedure 的返回值加了as any。只要有一处 anytRPC 的推断链就会断裂后面全变成 any。遇到这种问题先全项目搜索any把每一个都替换成具体类型。第二prisma 模型修改后没有重新生成 client。npx prisma generate必须跑否则 tRPC 拿到的还是旧类型。尤其是多人协作时队友改了 schema 并 push 到数据库你本地没 pull 也没 generate就会出现诡异错位。第三zod schema 与数据库实际模型不一致。比如你 schema 里写的z.string().optional()但数据库字段是必填运行时会出现校验错误。这类问题要在开发早期用 zod 的safeParse加日志确认一下输入内容别等到线上才暴露。4.4 常见问题速查表用一个表格把这些高频问题汇总一下问题现象常见原因解决办法客户端拿不到sessionNextAuth配置未正确导出或authOptions未集中统一封装getServerAuthSession检查route handler导出mutation后列表不刷新缺少invalidate或Server Component缓存onSuccess里调invalidate必要时调用router.refresh()类型全部变成any某处as any或ctx.db类型错误全项目搜any删干净重建类型链Prisma模型改了但类型没变没有重新generate执行npx prisma generate确认client路径正确页面数据一直旧Next.js fetch默认缓存按需加no-store或revalidate或改用tRPC查询OAuth登录静默失败providers回调签名有误看日志逐provider排查先本地邮箱密码登录验证这张表不是万能的但覆盖了我个人项目里 80% 的日常问题。排查思路上有一条主线先确认类型链路有没有断再确认缓存策略有没有挡住最后才是业务逻辑问题。5. 选型边界与演进方向5.1 什么项目不适合一上来就上T3全家桶T3 很好用但也不是所有场景都适合。如果你要做的核心是一个纯后端 API 服务、数据平台的后台任务、或者面向大量第三方客户开放的公共 OpenAPI那 tRPC 的收益就小一些——因为前端是你的客户不太可能和你共享一套 TypeScript 类型。这种情况更适合你单独维护一个 OpenAPI 文档和对应的 SDK 生成流程。另外如果团队里大部分人习惯的是 Java、Python 写后端前端和后端的人协作模式已经是固定的“接口文档驱动”那引入 T3 需要先说服大家接受一个新的数据流习惯不然团队摩擦会抵消类型安全带来的收益。还有如果你依赖非常小众的数据库、或者数据库操作需要大量原生 SQL 的高级特性Prisma 中间层有时会变成限制Drizzle 那类更贴近 SQL 的工具可能更适合你。5.2 演进换掉一部分保留“类型安全”主线T3 不是一成不变的。很多从 T3 起步的项目发展到一定阶段后会把某些组件拆出去。比如样式方案团队可能因为设计系统需要改用 CSS Modules 或者其他的原子化方案数据库层有人会从 Prisma 换成 Drizzle用更接近 SQL 的写法来写复杂查询API 层有人会在部分场景改用 Server Actions减少显式的 API 调用。我的建议是换之前先想清楚你换的理由是什么而不是因为“网上说XXX更香”。类型安全这条主线一旦丢失换成任何方案都会觉得别扭。比如你换掉了 tRPC前端调用外部 API至少要保证有一个清晰的类型生成流程——要么 OpenAPI codegen要么手写类型定义并持续维护。只要类型链路不断项目的长期可维护性就有保障。从另一个角度看T3 更像是一套“最佳实践快照”。技术栈本身会演进create-t3-app 的选项里已经出现了 Drizzle、Playwright、Tailwind v4 等更新选择。你把它当作起点比把它当作终点要更健康。我自己做了几年全栈项目最大的体会是工程效率未必来自某个炫酷的技术而是来自“类型系统把错误挡在编译期”这种看似朴素的纪律。T3 这套组合最打动我的是把这条纪律落到了每个环节——数据库模型、API 入参出参、React 组件调用全都在一个类型体系里闭环。如果你是第一次搭全栈项目先按 create-t3-app 的默认选项完整跑一遍不要急着加插件、换库等真正遇到瓶颈时你会比一开始就乱改默认配置的人更清楚问题出在哪。写到最后再分享一个小技巧在你的 tRPC router 里给 procedure 命名时尽量按照“资源 动作”的方式比如todo.all、todo.toggle、todo.create。这个习惯看起来一点不起眼但项目大起来之后前端代码里大约能看懂每个 API 在做什么团队成员 review 起来也会顺利很多。祝你在 t3code 这条路上少踩坑多写爽代码。
