第一次看到 t3code 这个名字我以为是某个代码生成器后来才反应过来它其实指向的是 T3 Stack 最佳实践下的那套全栈代码工程。T3 Stack 是 tRPC、Tailwind CSS、TypeScript 的合称搭上 Next.js 之后相当于把前端页面、服务端接口、数据库访问层、登录鉴权全部收编进同一个 TypeScript 项目里。如果你厌倦了在 REST 接口两边各写一份类型定义或者每次从零配 Prisma、NextAuth 都要折腾半天那 t3code 这套思路会非常对胃口。它解决的核心问题不是能不能做而是怎么做最省心——用一套代码、一种类型语言打通前后端减少大量无意义的重复劳动。适合已经有一定 Next.js 基础、想把手头项目推向全栈一致性的开发者也适合那些受够了前端一份类型、后端一份类型、联调用 Postman 对字段的团队开发场景。我最早接触 T3 Stack 是在做一个社区类的小产品当时前后端分成两个仓库接口文档维护得相当痛苦。后来尝试把架构收敛到 t3code 这套模式里整个开发体验提升了一个档次。这篇文章不是讲某个不可复现的黑科技而是把 t3code 项目从设计思路、工具选型到落地实操、踩坑记录完整拆开让你看完就能照着搭一套自己的全栈应用。1. 项目整体设计与思路拆解1.1 t3code 到底在解决什么问题先想一个问题全栈开发最耗时间的环节是什么不是写页面不是写 SQL而是沟通——前端说接口返回的字段改了后端跟着改联调时又要重新翻文档。两个端只要语言不同类型契约就永远存在摩擦。t3code 的核心主张非常干脆一套代码、一种类型语言、全链路类型安全。它不搞复杂的微服务拆分也不引入额外的中间件而是把所有逻辑放进 Next.js 这个应用里用 tRPC 把服务端函数直接暴露给前端调用。这样做带来的直接收益是类型定义只写一次。后端定义好的 Router 结构前端引入类型后自动获得完整的入参和出参提示字段名拼错了、类型对不上开发阶段编译就直接报错而不是等到运行时才发现。对我这种经常一个人包办前后端的开发者来说省下的时间非常可观。对团队来说价值更明显——前后端之间的契约从文档转移到了代码本身代码就是唯一事实来源接口文档从需要维护的资产变成了可选的补充材料。t3code 这个方向的关键词其实就两个类型安全和开发效率。它针对的是中小型应用、内部工具、快速验证的 MVP以及依赖单一团队维护的全栈产品。如果你是做纯展示型网站不涉及复杂的数据交互和鉴权T3 Stack 的优势体现不出来但只要是用户登录 操作数据 页面展示这类标准 Web 应用这套架构就会非常顺手。1.2 为什么是 T3 而不是其他组合在选型之前我也认真比较过其他方案。第一种是传统的 Next.js API Routes React Query Axios前端手动定义接口函数后端在pages/api里逐条写 handler。这种方式能跑但项目一大就乱每个接口都要手动维护路径字符串、请求方法、请求体类型、响应体类型一旦后端改了返回值前端不会收到任何提示全靠联调时用眼睛找。第二种是 NestJS React 的前后端分离。功能强大但对我来说太重了。NestJS 有依赖注入、模块系统、守卫、管道一堆概念如果项目本身不大这些抽象带来的复杂度远大于收益。T3 Stack 的好处是轻它不是重量级框架只是一组工具的组合但组合出来的体验非常顺滑。我把三种方案的差别整理成一张表方便对照方案类型安全开发效率适合场景复杂度传统 REST 前端手写类型低靠人工维护中等接口多了很繁琐前后端团队分离的大项目中等NestJS React 前后端分离中等可用 OpenAPI 生成较低工程化配置多中大型企业级应用高t3codeT3 Stack高端到端自动推导高无需手动维护接口层全栈一体化的小中产品低T3 Stack 里T3这个词最开始是 tRPC、Tailwind、TypeScript 三个首字母都是 T 的技术缩写后来社区把 Next.js 也纳入进来形成了现在这套 Standard。选 tRPC 而不是 REST核心原因是它把远程调用包装成了本地函数调用前端写post.create({ title: hello })所有参数检查、路由匹配、错误返回都交给框架处理。选 Prisma 而不是 TypeORM是因为 Prisma 的 schema 文件天然是一份数据模型文档迁移工具也更省心。选 Tailwind 而不是 CSS Modules是因为它省掉了大量的样式文件组织成本。这套组合没有一个是必须的但它确实非常适合独立开发者和敏捷团队。2. 工具选型解析与核心原理2.1 TypeScript这套体系的基石t3code 能成立最底层的基础是 TypeScript。没有 TypeScript 的泛型推导能力tRPC 的端到端类型安全就是一句空话。前端调用useQuery时返回的数据类型不是手写的 interface而是从后端 Router 定义里自动推导出来的。这种推导依赖 TS 的infer和Generic机制所以项目从一开始就必须开启严格模式strict: true是最低要求。我在实际项目中还发现TS 的路径别名Path Alias对体验影响很大。t3code 的工程默认把/映射到项目根目录这样你可以像写内部模块一样引入东西import { db } from ~/server/db看起来非常清爽。核心原则是尽早让类型系统介入把能查的错误在编译期查完。很多开发者嫌 TS 麻烦但在 t3code 这种模式下TS 不是负担反而成了帮你兜底的工具。写前端的时候编辑器能自动提示后端接口有哪些参数这种安全性带来的心智负担减轻是实实在在的。2.2 tRPC把写接口变成调函数tRPC 是这个架构里最特别的一环。传统 REST 的思维是资源 方法你需要设计 URL、设计状态码、设计错误结构tRPC 的思维是函数调用你在服务端定义一个router createTRPCRouter({ getPosts: publicProcedure.query(...) })前端就能直接调用。整个过程没有 URL 字符串拼接没有手动传 Content-Type也不需要在两个端各写一遍类型。它天然基于 JSON 序列化底层走 HTTP但对开发者完全透明。用生活化的类比来说REST 像是你去餐厅点菜得按菜单上的流程走——服务员要确认你的桌号、菜品编号上菜顺序也可能出错tRPC 像是你直接进后厨跟熟悉的厨师说再来一份上次那个厨师知道你要什么也不需要重新解释一遍。放到代码里前端const { data } api.post.getAll.useQuery()就是一句给我数据后端 router 里的getAll就是那个厨师。tRPC 里有两个高频概念需要花时间搞懂。第一个是procedure过程它是 API 的基本单元分query查和mutation写中间件middleware可以统一附加鉴权逻辑。第二个是input校验通常配合 zod 来实现。你在服务端定义了z.object({ title: z.string().min(1) })前端传空字符串直接在校验层被拦截错误信息还能通过 tRPC 的标准格式返回给前端展示。这种一处定义两端生效的体验用传统 REST 方式几乎做不到同等程度。2.3 Prisma 与 NextAuth数据与鉴权的两翼Prisma 在这套体系里扮演的是数据库访问层的角色。它跟 tRPC 配合得非常自然tRPC 的 query 函数里可以直接await db.post.findMany()返回的Post类型会被 tRPC 自动携带到前端。所以你在前端拿到的一整组帖子数据从数据库行变成了 TS 类型全程不需要手写 DTO。这里有一个细节需要注意Prisma 默认会自动生成 client 文件到node_modules/.prisma你在 schema 里定义好模型后必须跑一次npx prisma generate新字段才会出现在前端类型提示里。这个过程我在后面实操部分会详细讲。NextAuth 是登录鉴权的默认选择因为 t3code 的官方脚手架内置了对它的支持。它跟 tRPC 的关系很微妙NextAuth 接管登录态存 sessiontRPC 的 context 里读取 session决定某个 procedure 是否允许当前用户执行。写法上就是 createTRPCContext 里调用getServerSession(authOptions)然后把 session 挂到 ctx 上再由protectedProcedure做中间件判断。这套链路你把顺序理清之后实现起来并不复杂但新手最容易卡在环境变量没配好上——NextAuth 需要AUTH_SECRETPrisma 需要DATABASE_URL缺一个都会在启动或调用时报错。2.4 Tailwind CSS样式的取舍Tailwind 不是 t3code 里的必需品但它是官方脚手架的三根支柱之一。选它有几个实际考量一是原子化 CSS 不需要额外的样式文件管理改样式直接在 className 里操作对组件化开发非常友好二是配合状态切换如disabled:、dark:前缀能快速实现交互反馈三是 Tailwind v4 已经发布构建引擎切换到 Lightning CSS性能比老版本提升明显。如果你对传统 CSS 更熟悉也没关系完全可以保留自己的样式表方案但既然用了 t3code 的脚手架默认这套能省不少事。我自己的习惯是全局布局、页面骨架用 Tailwind 工具类快速搭复杂的图表组件再用 CSS Modules 或 styled-components 隔离两者互不冲突。项目的边界感只要清晰样式方案反而是最不需要纠结的部分。3. 实操过程与核心环节实现3.1 从脚手架到可运行工程t3code 项目最推荐的启动方式是官方脚手架create-t3-app。终端执行npx create-t3-applatest my-app交互式选项里会让你勾选需要的模块。我的建议是新项目先选上 Next.js、tRPC、Prisma、NextAuth、TailwindTypeScript 本身是默认基础不用额外选。如果你是纯前端展示项目可以关掉 Prisma 和 NextAuth但那样就享受不到完整链路的好处了。初始化完成后目录结构大概是这样的my-app/ src/ app/ # Next.js App Router 页面 pages/api/ # 兼容性 API 路由一般不用动 server/ api/ routers/ # tRPC router 定义 root.ts # 根 router 汇总 db.ts # Prisma client auth.ts # NextAuth 配置 trpc/ server.ts # 服务端 tRPC 封装 client.ts # 客户端 tRPC 封装 prisma/ schema.prisma # 数据库模型 .env # 环境变量创建完成后第一件要做的事是配置环境变量。打开.env至少要有DATABASE_URLmysql://user:passwordlocalhost:3306/t3code AUTH_SECRET用 openssl rand -base64 32 生成一串这里的DATABASE_URL取决于你本地用的数据库MySQL、PostgreSQL、SQLite 都支持。开发初期我强烈建议用 SQLiteDATABASE_URLfile:./dev.db就行零配置跑通逻辑再说。别一上来就研究 Docker 跑 MySQL那会把注意力从主线上岔开。3.2 定义第一个业务模块帖子系统用一个最简单的帖子和用户关联的例子带你完整走一遍 t3code 的链路。第一步在prisma/schema.prisma里定义模型model User { id String id default(cuid()) name String? email String unique posts Post[] } model Post { id String id default(cuid()) title String content String? createdAt DateTime default(now()) authorId String author User relation(fields: [authorId], references: [id]) }跑数据库迁移和客户端生成npx prisma migrate dev --name init npx prisma generate注意migrate dev会自动执行 generate但如果改了 schema 只想重新生成 client单独跑 generate 就够了。迁移完成之后数据库里就有了User和Post两张表接下来在 tRPC 里写路由。在src/server/api/routers/post.ts里创建一个 post routerimport { z } from zod; import { createTRPCRouter, publicProcedure, protectedProcedure } from ~/trpc/server; export const postRouter createTRPCRouter({ // 公开查询任何人都能看全部帖子 getAll: publicProcedure.query(({ ctx }) { return ctx.db.post.findMany({ include: { author: { select: { name: true } } }, orderBy: { createdAt: desc }, }); }), // 登录后才能发帖入参用 zod 校验 create: protectedProcedure .input( z.object({ title: z.string().min(1, 标题不能为空).max(100), content: z.string().max(10000).optional(), }) ) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });这两段基本把 tRPC 的开发范式说明白了。publicProcedure和protectedProcedure的区别在于后者在中间件层校验 session没登录直接抛 UNAUTHORIZED 错误。前端调用时页面代码长这样不需要写任何 HTTP 请求函数use client; import { api } from ~/trpc/client; export function PostList() { const { data: posts, isLoading } api.post.getAll.useQuery(); if (isLoading) return div加载中.../div; return ( ul {posts?.map((p) ( li key{p.id} h2{p.title}/h2 span{p.author.name}/span /li ))} /ul ); }你要做的只是调用api.post.getAll.useQuery()返回的posts类型会从 tRPC 的 router 里自动推导出来p.author.name写错了编辑器立刻标红。这就是 t3code 模式最直观的体验。新增帖子的 mutation 同样简单配合 React 的表单状态就能跑通const utils api.useUtils(); const createPost api.post.create.useMutation({ onSuccess: () utils.post.getAll.invalidate(), }); async function handleSubmit(e: React.FormEvent) { e.preventDefault(); await createPost.mutateAsync({ title, content }); }invalidate()是关键它会在 mutation 成功后自动刷新getAll的数据省掉了手动重新拉取。3.3 环境变量、网络层与部署细节实操里最容易被坑的是网络层配置。t3code 的 tRPC 默认走 Next.js 的 API 路由App Router 下它在src/app/api/trpc/[trpc]/route.ts里定义了一个 catch-all 路由所有 tRPC 请求都打到这里。你不需要去理解每个请求的 URL 长什么样但需要知道前端用的httpBatchLink会把这些请求批量打包减少网络往返次数。这在传统 REST 设计里是不容易做到的优化点。部署到 Vercel 时有几个环境变量必须重新配一遍DATABASE_URL、AUTH_SECRET如果用了第三方登录还要配 OAuth 相关的AUTH_GITHUB_ID、AUTH_GITHUB_SECRET之类。构建时 Next.js 会执行 TypeScript 检查如果 tRPC 的类型有错误构建直接失败所以类型安全在 CI/CD 里也等于是免费送质量检查。如果要用 Docker 部署需要注意prisma migrate deploy要在启动前执行不能用migrate dev那是开发用的。我的做法是在 Dockerfile 里把这一步放到构建后、启动前RUN npx prisma generate CMD [sh, -c, npx prisma migrate deploy node server.js]这样既保证了 schema 跟数据库一致又不会在容器里产生开发模式的意外行为。4. 常见问题与排查技巧实录4.1 前端拿不到后端新增的类型这是使用 t3code 过程中最频繁遇到的问题。原因几乎都一样改完schema.prisma后忘了npx prisma generate。只要 Prisma client 的类型没更新tRPC 后端返回的类型就还停留在旧状态。排查思路是三步走先看prisma/schema.prisma是否已更新再执行 generate最后重启next dev让类型重新加载。如果还不行打开 VSCode 的 TypeScript 服务重启命令面板里搜 TypeScript: Restart TS Server很多时候只是编辑器缓存。4.2 tRPC 路由写好了但页面不识别有人会在src/server/api/root.ts里注册 router 时忘记把新 router 加进去。比如写了postRouter但没有在appRouter里写post: postRouter前端自然调用不到。这个低级错误非常隐蔽因为没有报错信息只是api.post显示为 undefined。我的经验是每次定义新 router 后第一时间去root.ts看一眼注册表。这是 t3code 里少见的不依赖任何工具、纯靠细心避免的坑。4.3 NextAuth session 始终拿不到用户protectedProcedure里如果一直报未登录先查getServerSession是否成功。最容易出错的是 tRPC context 的创建时机——如果在 App Router 的 server 端去拿 session一定要把authOptions传对并且确认AUTH_SECRET在生产环境没有缺失。另外很多开发者会把 NextAuth 的配置写在src/server/auth.ts但 tRPC context 文件里引入的是另一个旧的 auth 配置两个文件不互通就会诡异失败。统一入口文件很重要。4.4 Prisma 客户端报table does not exist开发时数据库结构变了没同步最典型的是把migrate dev和migrate reset搞混。migrate dev是开发环境常用的它会创建迁移文件并同步数据库migrate reset会清空数据重来只适合本地需要重建的场景。如果你发现表缺失先跑npx prisma migrate dev如果还不存在检查DATABASE_URL指向的数据库对不对极有可能连的是别的库。4.5 部署后调用接口全挂这个问题九成是环境变量。本地能跑、Vercel 挂了首先去 Vercel 控制台的 Environment Variables 页面核对DATABASE_URL、AUTH_SECRET确认有没有填错。另一个容易忽视的点是数据库白名单——如果你用的是云数据库比如 Neon、PlanetScale本地 IP 和 Vercel 的函数 IP 不一样务必在数据库控制台把允许访问的 IP 范围加上否则连接直接被拒。我将这些常见问题整理成一个速查表现象可能原因解决方式前端没有新增类型提示未跑 prisma generate执行 npx prisma generate 并重启 TS Serverapi.post 显示 undefinedrouter 未注册检查 root.ts 的 router 注册表protectedProcedure 一直未授权session 拿不到检查 getServerSession 配置与 AUTH_SECRET报 table does not exist数据库未同步执行 npx prisma migrate dev部署后接口全挂环境变量缺失或白名单核对 Vercel env 和数据库 IP 白名单4.6 性能心得批量链路和 staleTimet3code 默认的网络层是批量请求但在实际使用中我发现高频查询还是要配合 staleTime 才能发挥最佳体验。React Query 的useQuery自带缓存你可以给不常变的数据设置staleTime: 60_000一分钟内不重新请求减少后端压力。比如帖子列表这类数据不要太频繁地发请求用户看起来也感觉秒开。这种调优手段跟架构关系不大但配合 t3code 的统一数据层做起来特别顺手因为所有查询都集中在 router 里加缓存配置只需改动调用的那一行。另外如果你发现某个查询被驳回或卡住记得留意 tRPC 的错误类型——UNAUTHORIZED、NOT_FOUND、BAD_REQUEST错误结构统一前端可以针对特定 code 做文案区分。我自己踩过坑之后对 t3code 最大的体会是它把全栈的类型安全从理想变成了日常。只要迈过前面几次编译报错和环境变量配置的门槛后续开发几乎都在享受正反馈。最后再分享一个小技巧如果你经常做多个小项目就把 t3code 脚手架里的prisma/schema.prisma和src/server/api/routers目录当成自己的模板库存着新需求来了直接复制改字段能省掉一大堆重复劳动。这套模式我自己维护了好几个项目稳定性和开发速度都让我满意至少短期内不会换回传统前后端分离的模式。
第一次看到 t3code 这个名字我以为是某个代码生成器后来才反应过来它其实指向的是 T3 Stack 最佳实践下的那套全栈代码工程。T3 Stack 是 tRPC、Tailwind CSS、TypeScript 的合称搭上 Next.js 之后相当于把前端页面、服务端接口、数据库访问层、登录鉴权全部收编进同一个 TypeScript 项目里。如果你厌倦了在 REST 接口两边各写一份类型定义或者每次从零配 Prisma、NextAuth 都要折腾半天那 t3code 这套思路会非常对胃口。它解决的核心问题不是能不能做而是怎么做最省心——用一套代码、一种类型语言打通前后端减少大量无意义的重复劳动。适合已经有一定 Next.js 基础、想把手头项目推向全栈一致性的开发者也适合那些受够了前端一份类型、后端一份类型、联调用 Postman 对字段的团队开发场景。我最早接触 T3 Stack 是在做一个社区类的小产品当时前后端分成两个仓库接口文档维护得相当痛苦。后来尝试把架构收敛到 t3code 这套模式里整个开发体验提升了一个档次。这篇文章不是讲某个不可复现的黑科技而是把 t3code 项目从设计思路、工具选型到落地实操、踩坑记录完整拆开让你看完就能照着搭一套自己的全栈应用。1. 项目整体设计与思路拆解1.1 t3code 到底在解决什么问题先想一个问题全栈开发最耗时间的环节是什么不是写页面不是写 SQL而是沟通——前端说接口返回的字段改了后端跟着改联调时又要重新翻文档。两个端只要语言不同类型契约就永远存在摩擦。t3code 的核心主张非常干脆一套代码、一种类型语言、全链路类型安全。它不搞复杂的微服务拆分也不引入额外的中间件而是把所有逻辑放进 Next.js 这个应用里用 tRPC 把服务端函数直接暴露给前端调用。这样做带来的直接收益是类型定义只写一次。后端定义好的 Router 结构前端引入类型后自动获得完整的入参和出参提示字段名拼错了、类型对不上开发阶段编译就直接报错而不是等到运行时才发现。对我这种经常一个人包办前后端的开发者来说省下的时间非常可观。对团队来说价值更明显——前后端之间的契约从文档转移到了代码本身代码就是唯一事实来源接口文档从需要维护的资产变成了可选的补充材料。t3code 这个方向的关键词其实就两个类型安全和开发效率。它针对的是中小型应用、内部工具、快速验证的 MVP以及依赖单一团队维护的全栈产品。如果你是做纯展示型网站不涉及复杂的数据交互和鉴权T3 Stack 的优势体现不出来但只要是用户登录 操作数据 页面展示这类标准 Web 应用这套架构就会非常顺手。1.2 为什么是 T3 而不是其他组合在选型之前我也认真比较过其他方案。第一种是传统的 Next.js API Routes React Query Axios前端手动定义接口函数后端在pages/api里逐条写 handler。这种方式能跑但项目一大就乱每个接口都要手动维护路径字符串、请求方法、请求体类型、响应体类型一旦后端改了返回值前端不会收到任何提示全靠联调时用眼睛找。第二种是 NestJS React 的前后端分离。功能强大但对我来说太重了。NestJS 有依赖注入、模块系统、守卫、管道一堆概念如果项目本身不大这些抽象带来的复杂度远大于收益。T3 Stack 的好处是轻它不是重量级框架只是一组工具的组合但组合出来的体验非常顺滑。我把三种方案的差别整理成一张表方便对照方案类型安全开发效率适合场景复杂度传统 REST 前端手写类型低靠人工维护中等接口多了很繁琐前后端团队分离的大项目中等NestJS React 前后端分离中等可用 OpenAPI 生成较低工程化配置多中大型企业级应用高t3codeT3 Stack高端到端自动推导高无需手动维护接口层全栈一体化的小中产品低T3 Stack 里T3这个词最开始是 tRPC、Tailwind、TypeScript 三个首字母都是 T 的技术缩写后来社区把 Next.js 也纳入进来形成了现在这套 Standard。选 tRPC 而不是 REST核心原因是它把远程调用包装成了本地函数调用前端写post.create({ title: hello })所有参数检查、路由匹配、错误返回都交给框架处理。选 Prisma 而不是 TypeORM是因为 Prisma 的 schema 文件天然是一份数据模型文档迁移工具也更省心。选 Tailwind 而不是 CSS Modules是因为它省掉了大量的样式文件组织成本。这套组合没有一个是必须的但它确实非常适合独立开发者和敏捷团队。2. 工具选型解析与核心原理2.1 TypeScript这套体系的基石t3code 能成立最底层的基础是 TypeScript。没有 TypeScript 的泛型推导能力tRPC 的端到端类型安全就是一句空话。前端调用useQuery时返回的数据类型不是手写的 interface而是从后端 Router 定义里自动推导出来的。这种推导依赖 TS 的infer和Generic机制所以项目从一开始就必须开启严格模式strict: true是最低要求。我在实际项目中还发现TS 的路径别名Path Alias对体验影响很大。t3code 的工程默认把/映射到项目根目录这样你可以像写内部模块一样引入东西import { db } from ~/server/db看起来非常清爽。核心原则是尽早让类型系统介入把能查的错误在编译期查完。很多开发者嫌 TS 麻烦但在 t3code 这种模式下TS 不是负担反而成了帮你兜底的工具。写前端的时候编辑器能自动提示后端接口有哪些参数这种安全性带来的心智负担减轻是实实在在的。2.2 tRPC把写接口变成调函数tRPC 是这个架构里最特别的一环。传统 REST 的思维是资源 方法你需要设计 URL、设计状态码、设计错误结构tRPC 的思维是函数调用你在服务端定义一个router createTRPCRouter({ getPosts: publicProcedure.query(...) })前端就能直接调用。整个过程没有 URL 字符串拼接没有手动传 Content-Type也不需要在两个端各写一遍类型。它天然基于 JSON 序列化底层走 HTTP但对开发者完全透明。用生活化的类比来说REST 像是你去餐厅点菜得按菜单上的流程走——服务员要确认你的桌号、菜品编号上菜顺序也可能出错tRPC 像是你直接进后厨跟熟悉的厨师说再来一份上次那个厨师知道你要什么也不需要重新解释一遍。放到代码里前端const { data } api.post.getAll.useQuery()就是一句给我数据后端 router 里的getAll就是那个厨师。tRPC 里有两个高频概念需要花时间搞懂。第一个是procedure过程它是 API 的基本单元分query查和mutation写中间件middleware可以统一附加鉴权逻辑。第二个是input校验通常配合 zod 来实现。你在服务端定义了z.object({ title: z.string().min(1) })前端传空字符串直接在校验层被拦截错误信息还能通过 tRPC 的标准格式返回给前端展示。这种一处定义两端生效的体验用传统 REST 方式几乎做不到同等程度。2.3 Prisma 与 NextAuth数据与鉴权的两翼Prisma 在这套体系里扮演的是数据库访问层的角色。它跟 tRPC 配合得非常自然tRPC 的 query 函数里可以直接await db.post.findMany()返回的Post类型会被 tRPC 自动携带到前端。所以你在前端拿到的一整组帖子数据从数据库行变成了 TS 类型全程不需要手写 DTO。这里有一个细节需要注意Prisma 默认会自动生成 client 文件到node_modules/.prisma你在 schema 里定义好模型后必须跑一次npx prisma generate新字段才会出现在前端类型提示里。这个过程我在后面实操部分会详细讲。NextAuth 是登录鉴权的默认选择因为 t3code 的官方脚手架内置了对它的支持。它跟 tRPC 的关系很微妙NextAuth 接管登录态存 sessiontRPC 的 context 里读取 session决定某个 procedure 是否允许当前用户执行。写法上就是 createTRPCContext 里调用getServerSession(authOptions)然后把 session 挂到 ctx 上再由protectedProcedure做中间件判断。这套链路你把顺序理清之后实现起来并不复杂但新手最容易卡在环境变量没配好上——NextAuth 需要AUTH_SECRETPrisma 需要DATABASE_URL缺一个都会在启动或调用时报错。2.4 Tailwind CSS样式的取舍Tailwind 不是 t3code 里的必需品但它是官方脚手架的三根支柱之一。选它有几个实际考量一是原子化 CSS 不需要额外的样式文件管理改样式直接在 className 里操作对组件化开发非常友好二是配合状态切换如disabled:、dark:前缀能快速实现交互反馈三是 Tailwind v4 已经发布构建引擎切换到 Lightning CSS性能比老版本提升明显。如果你对传统 CSS 更熟悉也没关系完全可以保留自己的样式表方案但既然用了 t3code 的脚手架默认这套能省不少事。我自己的习惯是全局布局、页面骨架用 Tailwind 工具类快速搭复杂的图表组件再用 CSS Modules 或 styled-components 隔离两者互不冲突。项目的边界感只要清晰样式方案反而是最不需要纠结的部分。3. 实操过程与核心环节实现3.1 从脚手架到可运行工程t3code 项目最推荐的启动方式是官方脚手架create-t3-app。终端执行npx create-t3-applatest my-app交互式选项里会让你勾选需要的模块。我的建议是新项目先选上 Next.js、tRPC、Prisma、NextAuth、TailwindTypeScript 本身是默认基础不用额外选。如果你是纯前端展示项目可以关掉 Prisma 和 NextAuth但那样就享受不到完整链路的好处了。初始化完成后目录结构大概是这样的my-app/ src/ app/ # Next.js App Router 页面 pages/api/ # 兼容性 API 路由一般不用动 server/ api/ routers/ # tRPC router 定义 root.ts # 根 router 汇总 db.ts # Prisma client auth.ts # NextAuth 配置 trpc/ server.ts # 服务端 tRPC 封装 client.ts # 客户端 tRPC 封装 prisma/ schema.prisma # 数据库模型 .env # 环境变量创建完成后第一件要做的事是配置环境变量。打开.env至少要有DATABASE_URLmysql://user:passwordlocalhost:3306/t3code AUTH_SECRET用 openssl rand -base64 32 生成一串这里的DATABASE_URL取决于你本地用的数据库MySQL、PostgreSQL、SQLite 都支持。开发初期我强烈建议用 SQLiteDATABASE_URLfile:./dev.db就行零配置跑通逻辑再说。别一上来就研究 Docker 跑 MySQL那会把注意力从主线上岔开。3.2 定义第一个业务模块帖子系统用一个最简单的帖子和用户关联的例子带你完整走一遍 t3code 的链路。第一步在prisma/schema.prisma里定义模型model User { id String id default(cuid()) name String? email String unique posts Post[] } model Post { id String id default(cuid()) title String content String? createdAt DateTime default(now()) authorId String author User relation(fields: [authorId], references: [id]) }跑数据库迁移和客户端生成npx prisma migrate dev --name init npx prisma generate注意migrate dev会自动执行 generate但如果改了 schema 只想重新生成 client单独跑 generate 就够了。迁移完成之后数据库里就有了User和Post两张表接下来在 tRPC 里写路由。在src/server/api/routers/post.ts里创建一个 post routerimport { z } from zod; import { createTRPCRouter, publicProcedure, protectedProcedure } from ~/trpc/server; export const postRouter createTRPCRouter({ // 公开查询任何人都能看全部帖子 getAll: publicProcedure.query(({ ctx }) { return ctx.db.post.findMany({ include: { author: { select: { name: true } } }, orderBy: { createdAt: desc }, }); }), // 登录后才能发帖入参用 zod 校验 create: protectedProcedure .input( z.object({ title: z.string().min(1, 标题不能为空).max(100), content: z.string().max(10000).optional(), }) ) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });这两段基本把 tRPC 的开发范式说明白了。publicProcedure和protectedProcedure的区别在于后者在中间件层校验 session没登录直接抛 UNAUTHORIZED 错误。前端调用时页面代码长这样不需要写任何 HTTP 请求函数use client; import { api } from ~/trpc/client; export function PostList() { const { data: posts, isLoading } api.post.getAll.useQuery(); if (isLoading) return div加载中.../div; return ( ul {posts?.map((p) ( li key{p.id} h2{p.title}/h2 span{p.author.name}/span /li ))} /ul ); }你要做的只是调用api.post.getAll.useQuery()返回的posts类型会从 tRPC 的 router 里自动推导出来p.author.name写错了编辑器立刻标红。这就是 t3code 模式最直观的体验。新增帖子的 mutation 同样简单配合 React 的表单状态就能跑通const utils api.useUtils(); const createPost api.post.create.useMutation({ onSuccess: () utils.post.getAll.invalidate(), }); async function handleSubmit(e: React.FormEvent) { e.preventDefault(); await createPost.mutateAsync({ title, content }); }invalidate()是关键它会在 mutation 成功后自动刷新getAll的数据省掉了手动重新拉取。3.3 环境变量、网络层与部署细节实操里最容易被坑的是网络层配置。t3code 的 tRPC 默认走 Next.js 的 API 路由App Router 下它在src/app/api/trpc/[trpc]/route.ts里定义了一个 catch-all 路由所有 tRPC 请求都打到这里。你不需要去理解每个请求的 URL 长什么样但需要知道前端用的httpBatchLink会把这些请求批量打包减少网络往返次数。这在传统 REST 设计里是不容易做到的优化点。部署到 Vercel 时有几个环境变量必须重新配一遍DATABASE_URL、AUTH_SECRET如果用了第三方登录还要配 OAuth 相关的AUTH_GITHUB_ID、AUTH_GITHUB_SECRET之类。构建时 Next.js 会执行 TypeScript 检查如果 tRPC 的类型有错误构建直接失败所以类型安全在 CI/CD 里也等于是免费送质量检查。如果要用 Docker 部署需要注意prisma migrate deploy要在启动前执行不能用migrate dev那是开发用的。我的做法是在 Dockerfile 里把这一步放到构建后、启动前RUN npx prisma generate CMD [sh, -c, npx prisma migrate deploy node server.js]这样既保证了 schema 跟数据库一致又不会在容器里产生开发模式的意外行为。4. 常见问题与排查技巧实录4.1 前端拿不到后端新增的类型这是使用 t3code 过程中最频繁遇到的问题。原因几乎都一样改完schema.prisma后忘了npx prisma generate。只要 Prisma client 的类型没更新tRPC 后端返回的类型就还停留在旧状态。排查思路是三步走先看prisma/schema.prisma是否已更新再执行 generate最后重启next dev让类型重新加载。如果还不行打开 VSCode 的 TypeScript 服务重启命令面板里搜 TypeScript: Restart TS Server很多时候只是编辑器缓存。4.2 tRPC 路由写好了但页面不识别有人会在src/server/api/root.ts里注册 router 时忘记把新 router 加进去。比如写了postRouter但没有在appRouter里写post: postRouter前端自然调用不到。这个低级错误非常隐蔽因为没有报错信息只是api.post显示为 undefined。我的经验是每次定义新 router 后第一时间去root.ts看一眼注册表。这是 t3code 里少见的不依赖任何工具、纯靠细心避免的坑。4.3 NextAuth session 始终拿不到用户protectedProcedure里如果一直报未登录先查getServerSession是否成功。最容易出错的是 tRPC context 的创建时机——如果在 App Router 的 server 端去拿 session一定要把authOptions传对并且确认AUTH_SECRET在生产环境没有缺失。另外很多开发者会把 NextAuth 的配置写在src/server/auth.ts但 tRPC context 文件里引入的是另一个旧的 auth 配置两个文件不互通就会诡异失败。统一入口文件很重要。4.4 Prisma 客户端报table does not exist开发时数据库结构变了没同步最典型的是把migrate dev和migrate reset搞混。migrate dev是开发环境常用的它会创建迁移文件并同步数据库migrate reset会清空数据重来只适合本地需要重建的场景。如果你发现表缺失先跑npx prisma migrate dev如果还不存在检查DATABASE_URL指向的数据库对不对极有可能连的是别的库。4.5 部署后调用接口全挂这个问题九成是环境变量。本地能跑、Vercel 挂了首先去 Vercel 控制台的 Environment Variables 页面核对DATABASE_URL、AUTH_SECRET确认有没有填错。另一个容易忽视的点是数据库白名单——如果你用的是云数据库比如 Neon、PlanetScale本地 IP 和 Vercel 的函数 IP 不一样务必在数据库控制台把允许访问的 IP 范围加上否则连接直接被拒。我将这些常见问题整理成一个速查表现象可能原因解决方式前端没有新增类型提示未跑 prisma generate执行 npx prisma generate 并重启 TS Serverapi.post 显示 undefinedrouter 未注册检查 root.ts 的 router 注册表protectedProcedure 一直未授权session 拿不到检查 getServerSession 配置与 AUTH_SECRET报 table does not exist数据库未同步执行 npx prisma migrate dev部署后接口全挂环境变量缺失或白名单核对 Vercel env 和数据库 IP 白名单4.6 性能心得批量链路和 staleTimet3code 默认的网络层是批量请求但在实际使用中我发现高频查询还是要配合 staleTime 才能发挥最佳体验。React Query 的useQuery自带缓存你可以给不常变的数据设置staleTime: 60_000一分钟内不重新请求减少后端压力。比如帖子列表这类数据不要太频繁地发请求用户看起来也感觉秒开。这种调优手段跟架构关系不大但配合 t3code 的统一数据层做起来特别顺手因为所有查询都集中在 router 里加缓存配置只需改动调用的那一行。另外如果你发现某个查询被驳回或卡住记得留意 tRPC 的错误类型——UNAUTHORIZED、NOT_FOUND、BAD_REQUEST错误结构统一前端可以针对特定 code 做文案区分。我自己踩过坑之后对 t3code 最大的体会是它把全栈的类型安全从理想变成了日常。只要迈过前面几次编译报错和环境变量配置的门槛后续开发几乎都在享受正反馈。最后再分享一个小技巧如果你经常做多个小项目就把 t3code 脚手架里的prisma/schema.prisma和src/server/api/routers目录当成自己的模板库存着新需求来了直接复制改字段能省掉一大堆重复劳动。这套模式我自己维护了好几个项目稳定性和开发速度都让我满意至少短期内不会换回传统前后端分离的模式。
