在技术圈子混久了你会发现一个很有意思的现象每当有人晒出全栈项目截图评论区问得最多的往往不是功能怎么实现而是用的什么技术栈。这几年我给出的答案基本都是同一个核心组合——TypeScript 打底、Next.js 做前端框架、tRPC 打通前后端类型、Prisma 管数据库、Tailwind 快速出样式。这个组合圈内叫 T3 Stack而我在实际落地时把它整合成了一个偏工程化的样板内部代号就叫 t3code。这名字没太多讲究纯粹因为它把 T3 的核心思想和代码脚手架绑定在一起。这套东西我用了将近两年从个人项目到小团队协作都跑过今天这篇就把它的核心构成、设计逻辑、实战时最容易栽的跟头一次说清楚。t3code 不是某个现成的开源框架它是一套基于 T3 Stack 技术选型的工程实践产物。它解决的问题很具体全栈 TypeScript 项目里前后端类型不一致、API 接口文档同步麻烦、数据库字段和类型定义来回迁就——这些胶水代码消耗的时间和精力往往比业务逻辑还多。T3 Stack 的核心主张就是少写胶水用一套语言贯穿浏览器、服务器和数据库让类型安全从代码文件一直延伸到 SQL 查询。这套方案最适合的人群有两类。一类是独立开发者或三五人小团队想要快速做出一个类型安全、可维护、后续能扩展的全栈应用原型另一类是从纯前端转全栈、想在真实项目里体会端到端类型安全到底是什么感觉的开发者。如果你还在纠结Next.js API Routes 够不够用要不要引入 GraphQLORM 该选哪个这篇文章里的取舍过程应该能帮你想清楚不少事情。1. 为什么是这套组合t3code 的选型逻辑很多人在看 T3 Stack 的技术清单时第一个反应是这些工具我都听过但为什么偏偏是它们组在一起。这背后不是随机拼凑而是一连串针对性极强的取舍。1.1 TypeScript 作为贯穿全栈的主轴语言TypeScript 在这套方案里不是可选项而是地基。tRPC 这套核心库之所以能实现端到端类型安全前提就是前后端都跑在 TypeScript 上。你用编辑器打开前端的调用代码看到一个user.listPosts()函数它的参数类型、返回值类型都源自从后端 Prisma 模型推导出来的类型。这个过程里没有手写接口文档、没有重复定义类型、没有运行时校验库全靠 TypeScript 编译器。这种做法的实际体验是改一个 Prisma schema 中的字段名保存文件前端编辑器里所有用到这个字段的地方立刻标红重构的成本被压到极低。我在没有使用这套方案之前改后端一个接口的返回值导致前端页面编译器报错十几个地方的情况几乎每周都有一次现在这类连错误类型都不用猜编译器直接告诉你哪个文件哪一行缺了什么修完基本一次过。1.2 tRPC 替代 REST 和 GraphQL 的理由有人会问为什么不直接用 REST API 或者 GraphQLREST 的问题不是不好而是你的团队得额外维护一套接口定义。你得写路由、写请求参数校验、写文档、写客户端代码这些工作量和业务无关纯属开销。GraphQL 的 schema 定义和 resolver 一样有学习成本对团队成员的要求也高。tRPC 的思路是既然前后端都是 TypeScript为什么不让函数直接成为 API你在服务端写一个叫getUserById的函数前端直接 import 一个同名代理函数调用参数类型、返回类型自动跟着走。不需要 URL 设计不需要手写fetch封装不需要联调文档。这带来的效率提升在小团队项目里尤其明显——一个人同时写前后端时上下文切换的成本被砍掉大半。当然tRPC 不是万能药。CPU 密集型的公共接口、需要被第三方大量调用的业务 API、跨语言的服务端架构这些场景它并不合适。但 t3code 面向的是同构 TypeScript 全栈应用这个前提下它几乎是最优解。1.3 Next.js 的定位全栈应用的最小容器Next.js 在这里承担两层角色。第一层是前端 React 应用的渲染层利用它的文件路由、server component 和 client component 机制组织页面。第二层是 API 承接层tRPC server 就是挂载在 Next.js 的 route handler 或者 API routes 里根据 Next.js 版本不同实现方式有差异前端和后端在同一服务器环境下运行部署时不用单独开一台 Node 服务一个 Next.js 应用就全包了。有一个设计细节值得展开Next.js 的 server component 可以直接调 tRPC server 端函数不需要走 HTTP 请求。这个模式在 t3code 里是推荐的因为它同时拿到了前后端类型安全和服务器直接执行的高性能跳过了网络序列化那层成本。只有在客户端组件中tRPC 才会走 HTTP 请求链路。2. t3code 的目录结构与核心数据流搭建 t3code 第一步是理解它的目录组织。这套结构直接决定了团队协作时什么代码该放哪的边界感也因此减少了大量无谓的沟通成本。t3code/ ├── prisma/ │ └── schema.prisma # 数据模型定义唯一的数据类型源头 ├── src/ │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ # 每个业务域一个 router 文件 │ │ │ └── root.ts # 应用所有 router 的根聚合 │ │ ├── db.ts # Prisma Client 实例 │ │ └── auth.ts # NextAuth 配置 │ ├── trpc/ │ │ ├── server.ts # tRPC 服务端初始化、中间件 │ │ └── client.ts # 客户端调用器 │ ├── app/ # Next.js App Router 目录 │ └── styles/ └── package.json2.1 schema.prisma承载一切类型的唯一真源在 t3code 里prisma/schema.prisma文件是整条数据链的源头。定义一个Post模型包括字段类型、关联关系、索引约束之后 Prisma 会基于它生成 TypeScript 类型和客户端查询 API。tRPC 的 router 函数直接 return Prisma 查询结果返回值类型自动推导到前端 TComponent 的 props这一层链路不用任何一行手写的接口类型代码。我常打的比方是schema.prisma 是数据库的表结构同时它也是 TypeScript 世界里所有数据对象的立法机构其余层只负责执行和呈现。修改字段、增加关系整个栈的类型推导会像波浪一样更新。这种单一真源带来的安全感用过以后真的回不去。2.2 tRPC router 的拆法与聚合业务代码按 domain 拆 router 是 t3code 的约定。每个 router 本质是一个可以组合的对象里面有几个核心成员procedure定义调用方式可以是publicProcedure或带鉴权的protectedProcedure。input用 zod 声明参数校验 schema这是最接近接口文档的东西。query表示读操作mutation表示写操作语义清晰。一个典型例子是帖子系统的 routerimport { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from /trpc/server; export const postRouter createTRPCRouter({ listPublished: publicProcedure.query(async ({ ctx }) { return ctx.db.post.findMany({ where: { published: true }, orderBy: { createdAt: desc }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1) })) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id }, }); }), });注意ctx这个变量。它是 tRPC 在每个请求里创建的上下文对象在服务端初始化时串联了数据库实例和当前登录用户会话。业务代码里拿ctx.db和ctx.session都很自然不用每个函数重新连接数据库或重新解析 token这就是上下文模式的收益。2.3 一次请求在 t3code 里的完整路径为了让大家对 t3code 有更直观的感觉我画一个典型数据流这里用文字描述流程不涉及图表工具用户在浏览器点了一个按钮触发trpc.post.create.useMutation()前端 tRPC 客户端把{ title, content }作为参数发 POST 请求到 Next.js 部署的 tRPC 端点服务端首先执行 zod 校验不合法直接返回 400 级别的校验错误接着protectedProcedure中间件检查会话未登录返回未授权最后进入业务 handler使用ctx.db写入数据库并返回新创建的帖子对象。整个链路除了 zod 校验是显式写得出的其余的类型推导和鉴权都属于框架层约定你在业务代码里甚至感觉不到它们的存在。从这个流程能看到 t3code 的核心哲学业务开发几乎不会碰网络层和序列化层所有精力都可以放在具体业务逻辑上。3. 认证与数据库两件地基事情的正确打开方式任何真实项目都绕不开登录和数据存储。t3code 在这两块的绑定也很深选的是 NextAuth.js 和 Prisma各有各的讲究。3.1 NextAuth.js 与 tRPC 的会话打通NextAuth.js 要做的事情是处理 OAuth 登录、维护 session、提供 JWT 或数据库 session 存储。t3code 里的关键一步是把 NextAuth 的 session 塞进 tRPC 的 context。这样protectedProcedure才能检查ctx.session?.user是否为空业务代码里也才能知道当前操作人是谁。// src/trpc/server.ts export const createTRPCContext async (opts: { headers: Headers }) { const session await getServerAuthToken(opts.headers); return { db, session, }; };这段代码里有个常被忽略的细节getServerAuthToken不是在所有场景都走 cookie 会话。如果你用 App Router 且服务端组件直接调用 tRPC 函数headers 会从组件请求上下文中透传如果是客户端组件发起的 HTTP 调用tRPC 会在请求的 headers 里带上 cookieserver 端再解析。这两种场景都要求你的 NextAuth 配置里 session 策略正确——推荐用 database session 方案这样可以顺手把 session 和用户表关联起来后面要做我发布过的帖子这类查询也更顺。3.2 Prisma 的工程化手感Prisma 在 t3code 里的定位不只是 ORM它的 schema 文件同时承担了数据库迁移定义和TypeScript 类型输出两个职责。日常开发流程是改 schema然后跑prisma migrate和prisma generate数据库迁移文件被纳入版本控制生成的客户端类型自动更新。这里有个实操习惯我很推荐写完 schema 不要把prisma generate的结果提交到 git而是放在构建脚本和postinstall里自动跑。这样换机器拉代码时类型自动跟上不会出现本地类型和远程分支的 schema 不一致导致编辑器报错的情况。我踩过的坑就是某个同事的node_modules/.prisma缓存过期编辑器一直报类型错误最后排查下来发现是 generate 产物没刷新。至于查询性能Prisma 的findMany等 API 日常属于够用且安全的层级它天然限制了 N1 查询问题——当然你可以用include做关联预取但要小心预取过深。t3code 里约定预取深度最多两层超过就走单独 router 分次取避免一次请求带回半个数据库。3.3 权限校验的统一书写位置权限校验是 t3code 里相对有掌控感的环节。你可能在一个 project 场景里有管理员成员访客三类角色如果用 REST 思维你会在每个接口里写 if 判断。在 tRPC 里这个逻辑可以在protectedProcedure之外再包装一层requireRoleconst adminOnly protectedProcedure.use(({ ctx, next }) { if (ctx.session?.user.role ! ADMIN) { throw new TRPCError({ code: FORBIDDEN }); } return next({ ctx }); });之后定义adminProcedure adminOnly新增一个管理员接口就一行声明。权限规则的高度复用很快就锻炼出对系统边界感的直觉——什么操作该属于哪个角色不再是埋在代码里的散装 if而是业务目录可以横向对照的规则清单。4. 从初始化到部署实操里最容易踩的五个坑t3code 在本地跑通不难真去落地部署、扩展到多环境时坑就密集了。这些坑我在不同项目里都踩过记下来省得大家重复交学费。4.1 环境变量管理不设默认值启动即报错tRPC、Prisma、NextAuth 三块都会读取环境变量尤其是DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL。不少人本地用.env工作得好好的一部署到服务器就发现数据库连接失败、登录跳转古怪最后发现是环境变量没配全。t3code 的处理策略是在 server 端启动时做显式校验缺任何关键变量直接抛错而不是让应用在半瘫痪状态下运行。import { env } from /env; // src/env.js 基于 zod 校验 process.env这个看似霸道的做法极大降低了排障成本。错误信息会直接告诉你缺的是哪一个变量一分钟就能修好而不是在接口 500 但日志很干净的状态里翻半小时。4.2 构建时的 tRPC 路径问题Next.js 有两种渲染环境服务端组件和客户端组件。tRPC 在客户端组件里调用时需要把请求地址指向服务端 tRPC endpoint而在服务端组件里直接调用 tRPC handler 时不经过 HTTP不用配 base URL。最容易出的问题出现在你把一段 tRPC 调用从客户端组件挪到服务端组件或者反过来时tRPC client的创建方式必须跟着切换。如果共用同一个 client 实例浏览器端会尝试 fetch 一个服务器端绝对路径导致请求失败。t3code 的约定是客户端组件统一用独立的createTRPCClient实例服务端组件统一用createCaller直接调用。4.3 部署平台的内存限制t3code 的产物是一个 Next.js 应用对服务器内存有一定要求。我在小型云主机和 Serverless 平台上都跑过结论是如果你用 Node 服务器部署内存最低给 1GBPrisma 的查询引擎和 Next.js 构建产物跑起来才会顺畅如果你用无服务器部署注意 Prisma 的 binary target 要配置成linux-arm64-openssl-3.0.x或对应运行时目标否则部署环境的二进制和本机打包的二进制不一致运行时会直接崩。这块的详细配置可以查 Prisma 官方文档的 binaryTargets 章节但我更想强调的思路是本地能跑不代表部署没问题部署配置的验证一定要在真实环境中做一次完整流程。4.4 登录回调地址和 cookie 的 SameSite 设置NextAuth 的登录跳转依赖 cookie本地开发是localhost同源没问题一旦部署到线上域名变了NEXTAUTH_URL必须和生产域名一致而且要注意多个子域共用同一个认证服务时的 cookie 作用域。如果只配置了主域名用户从app.yourdomain.com发起的登录可能被引导到一个奇怪的拼接地址。调 cookie 的 SameSite 属性也要看场景。同站单服务部署用lax如果 tRPC API 和 Next.js 前端被拆到不同子域就需要nonesecure的配置。不要照抄网上的配置先理解自己的部署拓扑再设置。4.5 zod 输入校验与前端类型的同步节奏zod schema 写在 tRPC router 里前端通过 tRPC 的类型推导拿到 input 类型。但要注意一个节奏问题如果你修改了 zod 的输入校验规则但前端已经通过参数校验的缓存继续发旧格式的请求413、400 的报错会层出不穷。这时候最稳妥的做法是zod schema 向上兼容新增字段给默认值删除字段要谨慎团队约定破坏性变更必须前后端一起发布。5. 性能与体验优化以及 tRPC 的常见使用误区T3 Stack 这类方案给人最深的印象是开发快但开发快不代表运行慢。合理使用下t3code 的性能可以跟手写 REST API 的方案持平甚至在特定场景下更优。我来讲讲几个既提升体验又避免误区的优化做法。5.1 React Query 缓存的作用域与失效策略tRPC 客户端底层依赖 React Query 做数据缓存。useQuery 返回的数据默认会缓存相同 key 的 query 在组件多次挂载时不会重复请求。这个机制在你实现列表页返回后数据不刷新的问题上有奇效但也容易造成更新后数据不新鲜。最好的实践是依赖 tRPC 的useMutation().onSuccess回调在写操作成功后精确触发相关 query 的重新拉取。比如新增一个帖子成功后只让listPublished刷新其他无关的 query 保持缓存。5.2 服务端调用不走 HTTP省掉网络开销前面提过服务端组件可以直接调 tRPC handler这是 t3code 里一个容易被低估的性能优势。假设你的页面需要一个推荐帖子侧边栏传统 REST 流程是服务端页面再向后端发一个 HTTP 请求而 t3code 的做法是直接调用postRouter.listRecommended函数数据库查询结果直接用于渲染。这一跳省下了网络往返的几十毫秒。如果你的页面同时请求多个数据块性能提升会更明显。5.3 不要在 t3code 里做的事用 tRPC 传输大文件tRPC 默认走 JSON 序列化不适合传multipart/form-data的大文件。很多新手想把文件上传也写在 mutation 里结果请求体过大或序列化失败。我的建议是文件上传走独立的 API 路由或云存储预签名 URLtRPC 只负责传元数据和文件标识。这个边界一清晰问题就少一半。5.4 实时功能的补充方案tRPC 本身是请求-响应模型虽然它也有 subscription 机制但网关、断线重连等实时场景下不如专门的 WebSocket 服务成熟。t3code 的推荐是结构性实时通知用数据库内置的 pub/sub 或独立的 WebSocket 服务业务查询仍走 tRPC。两者职责分离后实时模块的故障不会影响核心 CRUD 链路。6. 实战补充从 t3code 出发快速搭建一个带登录的日志应用理论讲了这么多用一个真实案例收尾最有说服力。前几天我刚用 t3code 起了一个轻量团队日志应用功能包括登录、发布日志、列表展示、按成员筛选、个人日志统计。整个开发从跑通到上线用了大约一天半核心流程可以完整走一遍。6.1 第一块数据模型和迁移建了两张表User和LogEntry。model User { id String id default(cuid()) name String? email String unique role String default(MEMBER) logEntries LogEntry[] } model LogEntry { id String id default(cuid()) content String createdAt DateTime default(now()) authorId String author User relation(fields: [authorId], references: [id]) index([authorId, createdAt]) }index是按成员和日期范围查询的加速器这个索引在日志应用场景基本必加。6.2 第二块日志相关的 tRPC router写日志的 mutation 和列表查询都放在同一个logRouter里其中列表查询支持按成员过滤export const logRouter createTRPCRouter({ listRecent: protectedProcedure .input(z.object({ userId: z.string().optional() })) .query(async ({ ctx, input }) { return ctx.db.logEntry.findMany({ where: { authorId: input.userId }, include: { author: true }, orderBy: { createdAt: desc }, take: 50, }); }), create: protectedProcedure .input(z.object({ content: z.string().min(1).max(2000) })) .mutation(async ({ ctx, input }) { return ctx.db.logEntry.create({ data: { content: input.content, authorId: ctx.session.user.id }, }); }), });take: 50是分页的粗粒度版本防止列表无限膨胀后续如果数据量变大可以演进成 cursor 分页。6.3 第三块前端页面和实时体验首页用服务端组件直接调用 tRPC 拉最近的日志列表登录后展示全量历史。写日志的表单放在客户端组件里提交成功后useUtils().logRouter.listRecent.invalidate()触发列表刷新。整个过程没有写一行手动的 HTTP 请求代码也没有重复定义类型新增字段时的编译期检查极大减少了错过更新的概率。上线后观察到的效果是团队成员在提测环境里用得很顺没有出现登录后看不到自己数据的权限 bug也没有接口文档和实际返回不一致的问题。这种类型安全带来的心安不是一两个接口省下的时间能衡量的它是在整个项目生命周期里持续释放的复利。7. 所以 t3code 到底适合什么场景该夸的夸完了也得把边界说清楚。如果你遇到下面这些情况t3code 这套方案不一定是最优选择你的团队需要在多语言间共享 API前后端分别是 TypeScript 和 Go/JavatRPC 的类型安全优势直接消失不如用 OpenAPI 代码生成器。你有一个必须被大量第三方调用的公开 APIREST 或 GraphQL 的生态和兼容性仍是最稳的tRPC 的调用模式和工具链对外部使用者不友好。你对数据库团队协作隔离敏感Prisma 的 migrate 工作流在多人同时修改 schema 时会有点疼需要约定好分工或引入 review 流程。而如果你的处境是一个 3~8 人的全栈 TypeScript 团队、要快速交付一个内部工具或 mid-sized 产品、希望把时间花在业务逻辑而不是接口胶水上t3code 几乎是为这个场景量身定做的。它不要求团队成员是全栈框架专家只要会 TypeScript 基本语法照着 t3code 的目录约定往里填业务代码生产效率立刻就能感受到差别。我自己的习惯是先用 t3code 跑通核心业务闭环再跟团队复盘哪些地方该引入更灵活的替代方案。技术选型从来不是一锤定音能解决当前真实问题、同时给后续留出演进空间就是好方案。t3code 这套实践作为起点确实是目前这个前提下我找不到更好替代品的组合。如果你已经在用 T3 Stack 或正准备尝试希望这篇里的选型逻辑、目录约定、部署坑位和经验判断能帮你少走几段弯路。