1. 前后端类型断层传统REST方案的老问题在哪这两年我经手过不少全栈项目从早期的Express Vue、到后来的NestJS React再到现在的Next.js tRPC。要说哪种组合给我的印象最深反而是每换一次方案前面那套的痛点就变得更清晰一次。今天想聊的这套东西圈内习惯叫它T3 Stack——Next.js TypeScript Tailwind CSS tRPC再加上Prisma和NextAuth基本都是TypeScript生态里最热的那几件。标题写成t3code其实就代表用这套技术栈落地的一整套写码实践。先说最让我难受的老问题类型断层。以前做前后端分离接口文档写一份前端再照着文档自己定义一份类型后端又要保证返回结构跟文档一致。一个接口字段改个名字前端跑起来才发现列表页崩了。运气好一点编译期能查到运气不好运行到某个页面点击按钮才报错。这种两头各自维护一份类型的模式本质上是在给团队增加翻译成本。我见过最夸张的项目一个ListUser接口前端翻了三份文档、两个版本的历史变更记录才确认返回字段到底是avatarUrl还是avatar_url。tRPC的解题思路很直接后端用TypeScript写一个函数前端直接调用这个函数类型自然跟着走。你不需要生成SDK不需要维护OpenAPI定义也不需要写一堆axios封装。类型是同一份代码推导出来的字段改了编辑器立刻红波浪线告诉你哪里要改。很多人第一次听完觉得不可思议说白了就是把远程调用伪装成本地调用把跨进程的类型不一致压缩成函数签名天然一致。这篇文章打算从一个极简的Todo应用出发完整走一遍T3 Stack的初始化、数据建模、接口编写、前端调用、认证接入、部署上线全流程。适合两种人看一种是正在选型全栈方案的开发者想搞清楚这套组合跟传统REST方案的差异另一种是已经搭过脚手架但没跑通完整业务逻辑的新手想看看一个真实业务里tRPC怎么组织、Prisma怎么建模、认证怎么接。内容不会只扔代码每个关键选择我都会讲清楚为什么这么做、坑在哪里以及我踩过的几个不大不小的雷。2. 从create-t3-app开始脚手架到底替你干了什么2.1 初始化流程与选择项T3 Stack.json 这个脚手架是社区维护的官方推荐入口一条命令就能启动npm create t3-applatest执行之后它会交互式问你选哪些模块我的建议是初期全选。Next.js、Tailwind、tRPC、Prisma、NextAuth这五个是这套组合的完整形态后三个不选的话后面想补反而要手动改一堆配置文件。尤其是tRPC和Prisma它俩是搭档关系建议不要分开选。初始化完成之后的目录结构跟我以前用CRA或Vite建的React项目很不一样。最大的变化是多了src/server/这个目录里面专门放服务端代码。第一次看这个目录的人往往会懵前端项目里为什么会有服务端这正是T3的核心思路——用了Next.js的API路由能力把后端逻辑直接塞回同一个项目里。简单说你的数据库查询、业务逻辑、接口处理都在src/server/里页面组件在src/app/里两边通过tRPC这座桥互相调用。src/ ├── app/ │ ├── api/ │ ├── layout.tsx │ ├── page.tsx │ └── ... ├── server/ │ ├── api/ │ │ ├── root.ts # tRPC 根路由所有子路由装配到这里 │ │ └── routers/ │ │ ├── post.ts # 示例路由基于 Post 表 │ │ └── ... │ ├── auth.ts # NextAuth 配置 │ └── db.ts # Prisma Client 单例我建议拿到脚手架之后先不要急着删示例代码而是花十分钟读一遍post.ts那个路由文件的完整写法它几乎涵盖了一个最小tRPC路由的所有要素输入校验、数据库查询、返回结构。等理解了这些再把示例删掉换自己的业务模型会顺畅很多。2.2 目录结构背后的设计逻辑那为什么示例路由叫post.ts而不是todo.ts因为脚手架默认建了一张Post表。很多新手初始化后第一件事就是改表名结果把关联关系改乱了反而不如留着示例表先跑通一遍。我的做法是直接用它当测试表先验证写到数据库→tRPC查出来→前端渲染这条链路通了再删掉重写。src/server/db.ts里的内容也要留意。脚手架生成了一个Prisma Client单例而不是每次查询都new PrismaClient()。这个细节在开发环境感觉不出差异但在生产环境的热重载机制下如果不做单例处理每次代码变更都会创建新的数据库连接最终把连接池打爆。这种错误报错信息也很迷惑常常显示成数据库连接数超限新手排查半天甚至怀疑是数据库容量不够。2.3 Tailwind CSS与样式取舍T3默认带Tailwind。如果你之前只用过CSS Modules或者styled-components第一次接触Tailwind可能会不习惯——类名全堆在className里视觉上确实有点脏。但用过一段时间会发现它最大的优势不是写样式快而是不需要设计组件库也能保持风格统一。间距、颜色、字号都有设计令牌约束不容易出现一个人写24px、另一个人写26px这种漂移。我个人的风格是ToDo应用不用任何UI组件库完全靠Tailwind的原型能力搭界面两三百行代码就能做一个看起来还行的管理界面。等业务变重再考虑引入shadcn/ui这类无头组件库也不迟。对于刚入门的人我建议先别急着加组件库T3 Stack的默认组合已经很完整多一个库就多一个心智负担。3. 写第一个tRPC路由从一张Todo表开始3.1 Prisma数据模型设计与迁移示例跑通之后删掉Post相关代码开始建Todo表。先打开prisma/schema.prisma定义模型model Todo { id String id default(cuid()) title String completed Boolean default(false) createdAt DateTime default(now()) updatedAt DateTime updatedAt }字段看起来很简单但是有几个选择值得说明。cuid()是Prisma常用的默认主键生成方式相比自增数字主键cuid在分布式环境下不会冲突也能防止别人通过递增ID猜测你的数据量。Boolean default(false)这种写法也不只是建表时的默认值Prisma在后续每次插入时都会生效比在业务代码里手动赋初值可靠得多。模型改完之后执行迁移npx prisma migrate dev --name init_todo这条命令会做两件事生成SQL迁移文件并且重新生成Prisma Client。有两点要提醒一是开发环境中改表结构一定要用migrate dev它会自动同步数据库结构二是如果你改了schema但忘记重新生成Client代码里永远拿不到新字段的类型。我吃过这个亏改了model之后直接去写路由编辑器一直报类型错误折腾了十分钟才发现忘了跑命令。3.2 zodtRPC的输入校验基石T3 Stack默认引进了zod这是整个方案里不能省略的部分。tRPC定义了输入校验的三个层次不校验、手动校验、zod校验。不校验的代码最简洁但等于对调用方完全信任手动校验写起来很啰嗦而且容易漏边界。zod的写法最接近声明式const createTodoInput z.object({ title: z.string().min(1, 标题不能为空).max(100), }); export const todoRouter createTRPCRouter({ create: protectedProcedure .input(createTodoInput) .mutation(async ({ ctx, input }) { return ctx.db.todo.create({ data: { title: input.title, userId: ctx.session.user.id, }, }); }), });这个例子里的input经过两层验证先由zod解析并规范化再作为类型安全的参数传给mutation函数。输入格式不对时tRPC会在请求处理的最前端就抛错根本不会进到数据库操作那一层。这种入口即校验的模式比在业务代码里写if (!title) { throw new Error() }要干净很多也更难遗漏。3.3 Router、Procedure、Query与Mutation的选择tRPC里有两个基础概念我花了好一阵子才完全理解它们的分工Router和Procedure。Router好理解就是一组Procedure的集合类似传统后端里Controller的定位。但Procedure的抽象比Controller的method要细一些它其实就是一个可被远程调用的函数单元再通过.query()或.mutation()区分用途。官方建议的划分方式是所有写操作增删改用mutation所有读操作查列表、查详情用query。原因也很朴素tRPC的query天然带有缓存标记react-query会默认缓存query结果如果写操作也用query会出现刷新页面数据不更新的错觉。从路由组织上我习惯按业务模块拆Router再在root.ts里合并export const appRouter createTRPCRouter({ todo: todoRouter, auth: authRouter, });前端调用的时候就是api.todo.getAll、api.todo.toggle这种语义化路径。范式一旦固定下来项目中几百个接口的组织方式都是同一个套路新人进来很好上手。3.4 前端调用没有fetch也没有axios这是tRPC让我第一次觉得前后端分离这个词有了新的解释。在前端组件里调用接口不需要封装axios实例也不需要写/api/todo/getAll这种路径字符串const utils api.useUtils(); const { data: todos, isLoading } api.todo.getAll.useQuery(); const createTodo api.todo.create.useMutation({ onSuccess: () { utils.todo.getAll.invalidate(); }, });代码里没有URL、没有HTTP动词、没有序列化。api.todo.getAll.useQuery()本身就是一个类型安全的远程函数调用。返回的data字段是什么类型完全由后端路由函数的返回值推导出来。我后来查过tRPC的实现它内部还是走HTTP协议只是把序列化和反序列化都藏起来了。理解这一点很重要它不是一个魔法而是一层封装严实的RPC协议。4. 认证与多用户从示例项目变成真实产品4.1 为什么要接入认证而不是每个人用同一份数据一个只有一张Todo表的应用认证是可选项不是必选项。但如果打算把Todo应用做成真正可用的产品——让每个人登录后只能看到自己的Todo那认证就是刚需。T3 Stack默认引入NextAuth现在叫Auth.js跟tRPC的结合方式是整条链路上比较精妙的地方。更关键的一条经验最早的版本里我拖了很久没接认证所有数据都挂在同一个用户下测试的时候觉得还挺方便不用每次登录。结果等要接认证时发现数据模型里早就不存在userId字段迁移就得写数据转换脚本或者干脆重置数据库。这个决策越晚做代价越高。我现在做任何新项目第一版数据模型就会考虑用户维度哪怕暂时不做多租户也先把userId字段加进去。4.2 配置Provider与Session类型扩展脚手架自带NextAuth的基础配置但Provider还要自己填。下面是一个Google Provider的配置示例export const authOptions: NextAuthOptions { providers: [ GoogleProvider({ clientId: process.env.GOOGLE_CLIENT_ID, clientSecret: process.env.GOOGLE_CLIENT_SECRET, }), ], callbacks: { session({ session, user }) { if (session.user) { session.user.id user.id; } return session; }, }, };这里的坑藏在最后一行。默认的Session对象里其实没有id字段如果不手动扩展Session类型你在前端组件里访问session.user.id编译器会直接抛错。T3脚手架的src/types/next-auth.d.ts里预留了这个扩展点declare module next-auth { interface Session { user: { id: string; name?: string | null; email?: string | null; }; } }这个过程必须你自己补因为NextAuth官方只提供基础类型不会帮你假设业务里需要一个id。我第一次跑通全流程后回头整理代码时发现这个类型声明就是T3里的一个高效约定它让前端调用session.user.id时可以畅通无阻。4.3 保护路由页面层与服务端层的双重手段认证接上之后要面对的问题就是哪些页面是登录后才能看的。最简单的做法是页面层判断Session是否存在不存在就跳转登录页if (!session) { return LoginPage /; }但它只挡了UI层API层还是敞开的——懂技术的人可以直接用curl或Postman调用后端接口绕过前端的Session检查。所以关键在于服务端保护。tRPC的做法是使用中间件。T3脚手架里预置了protectedProcedure它先判断Session是否有效再决定是否放行export const protectedProcedure createTRPCProcedure() .use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: ctx.session } }); });有了这个中间件路由里涉及用户数据的操作基本都要用protectedProcedure而不是通用procedure。一个重要提醒中间件的判断最好放在代码最顶层不要只包一层if就算完。我有一次写了路由之后忘了在中间件里返回next()放进来的请求直接没有走后续流程排查问题时花了几个小时才发现是中间件的返回值结构有问题。4.4 最容易踩的坑登录成功但Session一直为空这个坑我印象很深。在本地跑得好好的部署到线上之后发现用户登录成功了但页面上一直显示未登录状态。排查到最后原因在于NEXTAUTH_URL环境变量没配置或者配错了——线上环境的回调URL指向了错误域名Session Cookie自然就写不到浏览器里。解决方式很简单在.env文件中确保NEXTAUTH_URL与当前域名完全一致如果用Vercel部署还要加一行NEXTAUTH_SECRET它是Session加密的密钥线上环境必须单独设置如果前端和后端代码部署在不同域名下还要处理Cookie跨域这个复杂度翻倍T3方案下尽量避免这种架构。提示一旦出现登录后刷新就掉登录态第一反应先去检查环境变量而不是反复调试认证代码。我见过的Session丢失问题百分之八十出在配置上而不是代码上。5. 数据返回的结构化缓存、失效与错误处理的进阶玩法5.1 react-query帮我们做了什么tRPC底层默认集成了react-query这应该是T3 Stack里被低估的部分。很多人只把它当成调用接口的工具却不了解它在背后自动加了多少东西。最直接的好处是缓存。同一个query在多个组件里调用react-query会合并请求并在一定时间内复用结果不会因为两个组件同时渲染而发出重复请求。另一个好处是状态管理。以前手写接口调用还得自己维护loading、error、data三个状态。react-query把这套封装成了标准的返回值const { data, isLoading, isError } api.todo.getAll.useQuery();组件里只需要判断这几个状态把对应的UI渲染出来就行。多个组件的状态同步、请求取消、错误重试react-query都给你处理好了。刚开始可能觉得这有什么特别的等你手写过一段时间REST调用再回来就能体会出差距了。5.2 乐观更新修改之后不刷新也能立即看到结果在线应用里最常见的需求是勾选一个Todo的完成状态期望界面马上反馈而不是等请求返回再重新拉取列表。react-query提供了乐观更新机制tRPC的封装也能无缝对接。我的实现思路是const toggleTodo api.todo.toggle.useMutation({ onMutate: async ({ id, completed }) { await utils.todo.getAll.cancel(); const previous utils.todo.getAll.getData(); // 提前在缓存里更新该 Todo 的状态 utils.todo.getAll.setData(undefined, (old) old?.map((todo) (todo.id id ? { ...todo, completed } : todo)) ); return { previous }; }, onError: (_, __, context) { // 请求失败时回滚缓存 if (context?.previous) { utils.todo.getAll.setData(undefined, context.previous); } }, onSettled: () { // 最终重新拉取服务器数据保证一致性 utils.todo.getAll.invalidate(); }, });这段代码值得反复琢磨。核心思想就是先把UI改成目标状态同时记住旧数据一旦请求失败就回滚。这样用户感知到的操作延迟几乎为零网络慢的时候体验特别好。不过要提醒一句乐观更新不是万能的涉及金额、库存之类强一致性的数据务必慎用。5.3 zod校验失败与TRPCError的错误分类错误处理是最容易被忽略的环节。传统REST方案中错误可能是401、403、404、500等各种状态码前端得写一堆判断。tRPC把它收敛成一层统一结构TRPCError自带code字段比如UNAUTHORIZED、NOT_FOUND、BAD_REQUEST。前端可以通过error.data?.code拿到结构化错误。另外一个细节zod校验失败的时候默认错误信息已经比较友好但你可以自定义。比如上面那个标题校验如果希望错误消息是中文可以写成title: z.string().min(1, 标题不能为空).max(100, 标题最多100个字)这些信息会原样透传到前端error.message里。省去了后端回复英文错误、前端再映射成中文提示的那套流程。提示生产环境下tRPC默认会隐藏内部错误详情避免泄露堆栈信息。如果你在调试线上问题记得在日志里记录error.stack而不是只依赖tRPC返回给客户端的内容。6. 部署视角开发时一切正常上生产为什么会挂6.1 Vercel环境下的环境变量差异与构建流程T3 Stack默认打包在Vercel上部署过程本身很简单项目推到GitHub、导入Vercel、点击部署但真正的坑恰恰藏在简单里。最大的差异是环境变量。本地开发时.env文件存放在项目根目录Next.js启动时会自动读取但部署到Vercel后.env文件不会上传所有变量必须在Vercel后台配置。如果漏配了DATABASE_URL或者NEXTAUTH_SECRET构建可能还能通过但运行时一定炸。我在生产环境踩过的两次雷一次是漏配GOOGLE_CLIENT_SECRET导致登录按钮直接报错另一次是NEXTAUTH_URL指向了localhostSession彻底失效。提示Vercel的Environment Variables面板里有个Preview和Production环境区分配置时注意选择正确的环境。有些人只在Production里配了变量结果Preview分支构建时依赖的变量缺失预览链接打不开。6.2 tRPC环境下的serverless调用环境Vercel的Serverless函数有一个特性每个请求可能分配到不同的Node.js实例实例之间不共享内存。这对tRPC是一个潜在的问题——如果你在模块顶层创建了一个需要状态的对象它可能只存活在当前实例里。解决方案是把每次请求的上下文显式传递进去。Vercel上的T3项目createContext函数会在每个请求到达时重新执行把Session和DB连接封装到Context里。这样即使实例切换到另一个进程数据取数也不会丢失状态。export const createTRPCContext async (opts: CreateNextContextOptions) { const session await getServerSession(authOptions); return { db, session, }; };这段代码保证了每个请求都从当前Session和数据库连接池获取自己的上下文而不是依赖某个全局可变对象。不写这个你在本地数据正常、生产环境偶发找不到Session大概率就是这个原因。6.3 数据库迁移prisma migrate deploy才是在生产该用的命令开发环境中用prisma migrate dev它同时帮你更新数据库结构和生成Client生产环境则完全不同要用npx prisma migrate deploy这个命令只会执行还没跑过的迁移文件而不会生成或修改任何本地内容保证生产环境的数据库结构跟迁移历史一致。很多新手把migrate dev直接用在CI或服务器的部署流程里这很危险——migrate dev在某些条件下会尝试重置数据库。另外生产环境的数据库连接串建议放在构建环境变量里而不是写死到代码。大多数数据库服务提供直接从控制台获取连接串的能力按需填到Vercel的环境变量面板就行。6.4 一套我实际使用的部署验证清单部署上线前我会按这个清单过一遍.env文件里的所有变量在Vercel后台都有对应配置NEXTAUTH_SECRET已设置且与本地不同也别直接用本地值DATABASE_URL指向正确的生产数据库没有包含本地开发库的信息所有OAuth Provider的回调URL更新为线上域名Google控制台、GitHub OAuth应用都要改执行过一次prisma migrate deploy确认数据库表结构与迁移文件一致登录流程完整走一遍登录→刷新页面→登录态保持→退出登录检查tRPC错误提示故意传一个非法输入确认前端能收到错误信息而不是白屏这七项都通过了我才会把项目状态改成可上线。中间任何一项触雷后面的用户反馈往往来得又快又不好受。7. 最后再分享一点关于选型的个人体会如果你正在纠结要不要从传统REST方案切换到T3 Stack我的看法是团队里所有人都在用TypeScript写业务那T3的收益是立竿见影的——接口文档省了、类型同步成本大幅降低、前后端联调用一个文件就能说清楚。但如果团队里有人不熟悉TypeScript或者项目的核心逻辑强依赖复杂的服务端架构那T3方案并不会有太多加成反而可能引入新的学习成本。从我个人实践来看T3 Stack最舒服的落点是在中小型全栈项目——几个月的创业产品、内部工具、个人项目的MVP阶段。这种项目迭代快、需求变动频繁类型安全和开发效率的直接收益最为明显。等到项目成长到需要独立的API网关、多团队并行开发、或者前后端分离部署的阶段再考虑引入更重的分层也不迟至少前期的业务已经验证了核心逻辑跑得通。最后如果你想上手试试我建议别沿用官方示例的Post表而是从创建Todo模型开始一步步把登录、增删改查、部署全部跑通过一遍。这套流程走完之后你对T3的整个链路会有非常清晰的认知远远好过一个月里记住一百条零碎知识点。 
长河君 · 2026/10/28 22:41:35 · 阅读 1.2k T3 Stack全栈开发实战：用tRPC彻底解决前后端类型断层
1. 前后端类型断层传统REST方案的老问题在哪这两年我经手过不少全栈项目从早期的Express Vue、到后来的NestJS React再到现在的Next.js tRPC。要说哪种组合给我的印象最深反而是每换一次方案前面那套的痛点就变得更清晰一次。今天想聊的这套东西圈内习惯叫它T3 Stack——Next.js TypeScript Tailwind CSS tRPC再加上Prisma和NextAuth基本都是TypeScript生态里最热的那几件。标题写成t3code其实就代表用这套技术栈落地的一整套写码实践。先说最让我难受的老问题类型断层。以前做前后端分离接口文档写一份前端再照着文档自己定义一份类型后端又要保证返回结构跟文档一致。一个接口字段改个名字前端跑起来才发现列表页崩了。运气好一点编译期能查到运气不好运行到某个页面点击按钮才报错。这种两头各自维护一份类型的模式本质上是在给团队增加翻译成本。我见过最夸张的项目一个ListUser接口前端翻了三份文档、两个版本的历史变更记录才确认返回字段到底是avatarUrl还是avatar_url。tRPC的解题思路很直接后端用TypeScript写一个函数前端直接调用这个函数类型自然跟着走。你不需要生成SDK不需要维护OpenAPI定义也不需要写一堆axios封装。类型是同一份代码推导出来的字段改了编辑器立刻红波浪线告诉你哪里要改。很多人第一次听完觉得不可思议说白了就是把远程调用伪装成本地调用把跨进程的类型不一致压缩成函数签名天然一致。这篇文章打算从一个极简的Todo应用出发完整走一遍T3 Stack的初始化、数据建模、接口编写、前端调用、认证接入、部署上线全流程。适合两种人看一种是正在选型全栈方案的开发者想搞清楚这套组合跟传统REST方案的差异另一种是已经搭过脚手架但没跑通完整业务逻辑的新手想看看一个真实业务里tRPC怎么组织、Prisma怎么建模、认证怎么接。内容不会只扔代码每个关键选择我都会讲清楚为什么这么做、坑在哪里以及我踩过的几个不大不小的雷。2. 从create-t3-app开始脚手架到底替你干了什么2.1 初始化流程与选择项T3 Stack.json 这个脚手架是社区维护的官方推荐入口一条命令就能启动npm create t3-applatest执行之后它会交互式问你选哪些模块我的建议是初期全选。Next.js、Tailwind、tRPC、Prisma、NextAuth这五个是这套组合的完整形态后三个不选的话后面想补反而要手动改一堆配置文件。尤其是tRPC和Prisma它俩是搭档关系建议不要分开选。初始化完成之后的目录结构跟我以前用CRA或Vite建的React项目很不一样。最大的变化是多了src/server/这个目录里面专门放服务端代码。第一次看这个目录的人往往会懵前端项目里为什么会有服务端这正是T3的核心思路——用了Next.js的API路由能力把后端逻辑直接塞回同一个项目里。简单说你的数据库查询、业务逻辑、接口处理都在src/server/里页面组件在src/app/里两边通过tRPC这座桥互相调用。src/ ├── app/ │ ├── api/ │ ├── layout.tsx │ ├── page.tsx │ └── ... ├── server/ │ ├── api/ │ │ ├── root.ts # tRPC 根路由所有子路由装配到这里 │ │ └── routers/ │ │ ├── post.ts # 示例路由基于 Post 表 │ │ └── ... │ ├── auth.ts # NextAuth 配置 │ └── db.ts # Prisma Client 单例我建议拿到脚手架之后先不要急着删示例代码而是花十分钟读一遍post.ts那个路由文件的完整写法它几乎涵盖了一个最小tRPC路由的所有要素输入校验、数据库查询、返回结构。等理解了这些再把示例删掉换自己的业务模型会顺畅很多。2.2 目录结构背后的设计逻辑那为什么示例路由叫post.ts而不是todo.ts因为脚手架默认建了一张Post表。很多新手初始化后第一件事就是改表名结果把关联关系改乱了反而不如留着示例表先跑通一遍。我的做法是直接用它当测试表先验证写到数据库→tRPC查出来→前端渲染这条链路通了再删掉重写。src/server/db.ts里的内容也要留意。脚手架生成了一个Prisma Client单例而不是每次查询都new PrismaClient()。这个细节在开发环境感觉不出差异但在生产环境的热重载机制下如果不做单例处理每次代码变更都会创建新的数据库连接最终把连接池打爆。这种错误报错信息也很迷惑常常显示成数据库连接数超限新手排查半天甚至怀疑是数据库容量不够。2.3 Tailwind CSS与样式取舍T3默认带Tailwind。如果你之前只用过CSS Modules或者styled-components第一次接触Tailwind可能会不习惯——类名全堆在className里视觉上确实有点脏。但用过一段时间会发现它最大的优势不是写样式快而是不需要设计组件库也能保持风格统一。间距、颜色、字号都有设计令牌约束不容易出现一个人写24px、另一个人写26px这种漂移。我个人的风格是ToDo应用不用任何UI组件库完全靠Tailwind的原型能力搭界面两三百行代码就能做一个看起来还行的管理界面。等业务变重再考虑引入shadcn/ui这类无头组件库也不迟。对于刚入门的人我建议先别急着加组件库T3 Stack的默认组合已经很完整多一个库就多一个心智负担。3. 写第一个tRPC路由从一张Todo表开始3.1 Prisma数据模型设计与迁移示例跑通之后删掉Post相关代码开始建Todo表。先打开prisma/schema.prisma定义模型model Todo { id String id default(cuid()) title String completed Boolean default(false) createdAt DateTime default(now()) updatedAt DateTime updatedAt }字段看起来很简单但是有几个选择值得说明。cuid()是Prisma常用的默认主键生成方式相比自增数字主键cuid在分布式环境下不会冲突也能防止别人通过递增ID猜测你的数据量。Boolean default(false)这种写法也不只是建表时的默认值Prisma在后续每次插入时都会生效比在业务代码里手动赋初值可靠得多。模型改完之后执行迁移npx prisma migrate dev --name init_todo这条命令会做两件事生成SQL迁移文件并且重新生成Prisma Client。有两点要提醒一是开发环境中改表结构一定要用migrate dev它会自动同步数据库结构二是如果你改了schema但忘记重新生成Client代码里永远拿不到新字段的类型。我吃过这个亏改了model之后直接去写路由编辑器一直报类型错误折腾了十分钟才发现忘了跑命令。3.2 zodtRPC的输入校验基石T3 Stack默认引进了zod这是整个方案里不能省略的部分。tRPC定义了输入校验的三个层次不校验、手动校验、zod校验。不校验的代码最简洁但等于对调用方完全信任手动校验写起来很啰嗦而且容易漏边界。zod的写法最接近声明式const createTodoInput z.object({ title: z.string().min(1, 标题不能为空).max(100), }); export const todoRouter createTRPCRouter({ create: protectedProcedure .input(createTodoInput) .mutation(async ({ ctx, input }) { return ctx.db.todo.create({ data: { title: input.title, userId: ctx.session.user.id, }, }); }), });这个例子里的input经过两层验证先由zod解析并规范化再作为类型安全的参数传给mutation函数。输入格式不对时tRPC会在请求处理的最前端就抛错根本不会进到数据库操作那一层。这种入口即校验的模式比在业务代码里写if (!title) { throw new Error() }要干净很多也更难遗漏。3.3 Router、Procedure、Query与Mutation的选择tRPC里有两个基础概念我花了好一阵子才完全理解它们的分工Router和Procedure。Router好理解就是一组Procedure的集合类似传统后端里Controller的定位。但Procedure的抽象比Controller的method要细一些它其实就是一个可被远程调用的函数单元再通过.query()或.mutation()区分用途。官方建议的划分方式是所有写操作增删改用mutation所有读操作查列表、查详情用query。原因也很朴素tRPC的query天然带有缓存标记react-query会默认缓存query结果如果写操作也用query会出现刷新页面数据不更新的错觉。从路由组织上我习惯按业务模块拆Router再在root.ts里合并export const appRouter createTRPCRouter({ todo: todoRouter, auth: authRouter, });前端调用的时候就是api.todo.getAll、api.todo.toggle这种语义化路径。范式一旦固定下来项目中几百个接口的组织方式都是同一个套路新人进来很好上手。3.4 前端调用没有fetch也没有axios这是tRPC让我第一次觉得前后端分离这个词有了新的解释。在前端组件里调用接口不需要封装axios实例也不需要写/api/todo/getAll这种路径字符串const utils api.useUtils(); const { data: todos, isLoading } api.todo.getAll.useQuery(); const createTodo api.todo.create.useMutation({ onSuccess: () { utils.todo.getAll.invalidate(); }, });代码里没有URL、没有HTTP动词、没有序列化。api.todo.getAll.useQuery()本身就是一个类型安全的远程函数调用。返回的data字段是什么类型完全由后端路由函数的返回值推导出来。我后来查过tRPC的实现它内部还是走HTTP协议只是把序列化和反序列化都藏起来了。理解这一点很重要它不是一个魔法而是一层封装严实的RPC协议。4. 认证与多用户从示例项目变成真实产品4.1 为什么要接入认证而不是每个人用同一份数据一个只有一张Todo表的应用认证是可选项不是必选项。但如果打算把Todo应用做成真正可用的产品——让每个人登录后只能看到自己的Todo那认证就是刚需。T3 Stack默认引入NextAuth现在叫Auth.js跟tRPC的结合方式是整条链路上比较精妙的地方。更关键的一条经验最早的版本里我拖了很久没接认证所有数据都挂在同一个用户下测试的时候觉得还挺方便不用每次登录。结果等要接认证时发现数据模型里早就不存在userId字段迁移就得写数据转换脚本或者干脆重置数据库。这个决策越晚做代价越高。我现在做任何新项目第一版数据模型就会考虑用户维度哪怕暂时不做多租户也先把userId字段加进去。4.2 配置Provider与Session类型扩展脚手架自带NextAuth的基础配置但Provider还要自己填。下面是一个Google Provider的配置示例export const authOptions: NextAuthOptions { providers: [ GoogleProvider({ clientId: process.env.GOOGLE_CLIENT_ID, clientSecret: process.env.GOOGLE_CLIENT_SECRET, }), ], callbacks: { session({ session, user }) { if (session.user) { session.user.id user.id; } return session; }, }, };这里的坑藏在最后一行。默认的Session对象里其实没有id字段如果不手动扩展Session类型你在前端组件里访问session.user.id编译器会直接抛错。T3脚手架的src/types/next-auth.d.ts里预留了这个扩展点declare module next-auth { interface Session { user: { id: string; name?: string | null; email?: string | null; }; } }这个过程必须你自己补因为NextAuth官方只提供基础类型不会帮你假设业务里需要一个id。我第一次跑通全流程后回头整理代码时发现这个类型声明就是T3里的一个高效约定它让前端调用session.user.id时可以畅通无阻。4.3 保护路由页面层与服务端层的双重手段认证接上之后要面对的问题就是哪些页面是登录后才能看的。最简单的做法是页面层判断Session是否存在不存在就跳转登录页if (!session) { return LoginPage /; }但它只挡了UI层API层还是敞开的——懂技术的人可以直接用curl或Postman调用后端接口绕过前端的Session检查。所以关键在于服务端保护。tRPC的做法是使用中间件。T3脚手架里预置了protectedProcedure它先判断Session是否有效再决定是否放行export const protectedProcedure createTRPCProcedure() .use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: ctx.session } }); });有了这个中间件路由里涉及用户数据的操作基本都要用protectedProcedure而不是通用procedure。一个重要提醒中间件的判断最好放在代码最顶层不要只包一层if就算完。我有一次写了路由之后忘了在中间件里返回next()放进来的请求直接没有走后续流程排查问题时花了几个小时才发现是中间件的返回值结构有问题。4.4 最容易踩的坑登录成功但Session一直为空这个坑我印象很深。在本地跑得好好的部署到线上之后发现用户登录成功了但页面上一直显示未登录状态。排查到最后原因在于NEXTAUTH_URL环境变量没配置或者配错了——线上环境的回调URL指向了错误域名Session Cookie自然就写不到浏览器里。解决方式很简单在.env文件中确保NEXTAUTH_URL与当前域名完全一致如果用Vercel部署还要加一行NEXTAUTH_SECRET它是Session加密的密钥线上环境必须单独设置如果前端和后端代码部署在不同域名下还要处理Cookie跨域这个复杂度翻倍T3方案下尽量避免这种架构。提示一旦出现登录后刷新就掉登录态第一反应先去检查环境变量而不是反复调试认证代码。我见过的Session丢失问题百分之八十出在配置上而不是代码上。5. 数据返回的结构化缓存、失效与错误处理的进阶玩法5.1 react-query帮我们做了什么tRPC底层默认集成了react-query这应该是T3 Stack里被低估的部分。很多人只把它当成调用接口的工具却不了解它在背后自动加了多少东西。最直接的好处是缓存。同一个query在多个组件里调用react-query会合并请求并在一定时间内复用结果不会因为两个组件同时渲染而发出重复请求。另一个好处是状态管理。以前手写接口调用还得自己维护loading、error、data三个状态。react-query把这套封装成了标准的返回值const { data, isLoading, isError } api.todo.getAll.useQuery();组件里只需要判断这几个状态把对应的UI渲染出来就行。多个组件的状态同步、请求取消、错误重试react-query都给你处理好了。刚开始可能觉得这有什么特别的等你手写过一段时间REST调用再回来就能体会出差距了。5.2 乐观更新修改之后不刷新也能立即看到结果在线应用里最常见的需求是勾选一个Todo的完成状态期望界面马上反馈而不是等请求返回再重新拉取列表。react-query提供了乐观更新机制tRPC的封装也能无缝对接。我的实现思路是const toggleTodo api.todo.toggle.useMutation({ onMutate: async ({ id, completed }) { await utils.todo.getAll.cancel(); const previous utils.todo.getAll.getData(); // 提前在缓存里更新该 Todo 的状态 utils.todo.getAll.setData(undefined, (old) old?.map((todo) (todo.id id ? { ...todo, completed } : todo)) ); return { previous }; }, onError: (_, __, context) { // 请求失败时回滚缓存 if (context?.previous) { utils.todo.getAll.setData(undefined, context.previous); } }, onSettled: () { // 最终重新拉取服务器数据保证一致性 utils.todo.getAll.invalidate(); }, });这段代码值得反复琢磨。核心思想就是先把UI改成目标状态同时记住旧数据一旦请求失败就回滚。这样用户感知到的操作延迟几乎为零网络慢的时候体验特别好。不过要提醒一句乐观更新不是万能的涉及金额、库存之类强一致性的数据务必慎用。5.3 zod校验失败与TRPCError的错误分类错误处理是最容易被忽略的环节。传统REST方案中错误可能是401、403、404、500等各种状态码前端得写一堆判断。tRPC把它收敛成一层统一结构TRPCError自带code字段比如UNAUTHORIZED、NOT_FOUND、BAD_REQUEST。前端可以通过error.data?.code拿到结构化错误。另外一个细节zod校验失败的时候默认错误信息已经比较友好但你可以自定义。比如上面那个标题校验如果希望错误消息是中文可以写成title: z.string().min(1, 标题不能为空).max(100, 标题最多100个字)这些信息会原样透传到前端error.message里。省去了后端回复英文错误、前端再映射成中文提示的那套流程。提示生产环境下tRPC默认会隐藏内部错误详情避免泄露堆栈信息。如果你在调试线上问题记得在日志里记录error.stack而不是只依赖tRPC返回给客户端的内容。6. 部署视角开发时一切正常上生产为什么会挂6.1 Vercel环境下的环境变量差异与构建流程T3 Stack默认打包在Vercel上部署过程本身很简单项目推到GitHub、导入Vercel、点击部署但真正的坑恰恰藏在简单里。最大的差异是环境变量。本地开发时.env文件存放在项目根目录Next.js启动时会自动读取但部署到Vercel后.env文件不会上传所有变量必须在Vercel后台配置。如果漏配了DATABASE_URL或者NEXTAUTH_SECRET构建可能还能通过但运行时一定炸。我在生产环境踩过的两次雷一次是漏配GOOGLE_CLIENT_SECRET导致登录按钮直接报错另一次是NEXTAUTH_URL指向了localhostSession彻底失效。提示Vercel的Environment Variables面板里有个Preview和Production环境区分配置时注意选择正确的环境。有些人只在Production里配了变量结果Preview分支构建时依赖的变量缺失预览链接打不开。6.2 tRPC环境下的serverless调用环境Vercel的Serverless函数有一个特性每个请求可能分配到不同的Node.js实例实例之间不共享内存。这对tRPC是一个潜在的问题——如果你在模块顶层创建了一个需要状态的对象它可能只存活在当前实例里。解决方案是把每次请求的上下文显式传递进去。Vercel上的T3项目createContext函数会在每个请求到达时重新执行把Session和DB连接封装到Context里。这样即使实例切换到另一个进程数据取数也不会丢失状态。export const createTRPCContext async (opts: CreateNextContextOptions) { const session await getServerSession(authOptions); return { db, session, }; };这段代码保证了每个请求都从当前Session和数据库连接池获取自己的上下文而不是依赖某个全局可变对象。不写这个你在本地数据正常、生产环境偶发找不到Session大概率就是这个原因。6.3 数据库迁移prisma migrate deploy才是在生产该用的命令开发环境中用prisma migrate dev它同时帮你更新数据库结构和生成Client生产环境则完全不同要用npx prisma migrate deploy这个命令只会执行还没跑过的迁移文件而不会生成或修改任何本地内容保证生产环境的数据库结构跟迁移历史一致。很多新手把migrate dev直接用在CI或服务器的部署流程里这很危险——migrate dev在某些条件下会尝试重置数据库。另外生产环境的数据库连接串建议放在构建环境变量里而不是写死到代码。大多数数据库服务提供直接从控制台获取连接串的能力按需填到Vercel的环境变量面板就行。6.4 一套我实际使用的部署验证清单部署上线前我会按这个清单过一遍.env文件里的所有变量在Vercel后台都有对应配置NEXTAUTH_SECRET已设置且与本地不同也别直接用本地值DATABASE_URL指向正确的生产数据库没有包含本地开发库的信息所有OAuth Provider的回调URL更新为线上域名Google控制台、GitHub OAuth应用都要改执行过一次prisma migrate deploy确认数据库表结构与迁移文件一致登录流程完整走一遍登录→刷新页面→登录态保持→退出登录检查tRPC错误提示故意传一个非法输入确认前端能收到错误信息而不是白屏这七项都通过了我才会把项目状态改成可上线。中间任何一项触雷后面的用户反馈往往来得又快又不好受。7. 最后再分享一点关于选型的个人体会如果你正在纠结要不要从传统REST方案切换到T3 Stack我的看法是团队里所有人都在用TypeScript写业务那T3的收益是立竿见影的——接口文档省了、类型同步成本大幅降低、前后端联调用一个文件就能说清楚。但如果团队里有人不熟悉TypeScript或者项目的核心逻辑强依赖复杂的服务端架构那T3方案并不会有太多加成反而可能引入新的学习成本。从我个人实践来看T3 Stack最舒服的落点是在中小型全栈项目——几个月的创业产品、内部工具、个人项目的MVP阶段。这种项目迭代快、需求变动频繁类型安全和开发效率的直接收益最为明显。等到项目成长到需要独立的API网关、多团队并行开发、或者前后端分离部署的阶段再考虑引入更重的分层也不迟至少前期的业务已经验证了核心逻辑跑得通。最后如果你想上手试试我建议别沿用官方示例的Post表而是从创建Todo模型开始一步步把登录、增删改查、部署全部跑通过一遍。这套流程走完之后你对T3的整个链路会有非常清晰的认知远远好过一个月里记住一百条零碎知识点。