我第一次听说 t3code 的时候其实有点不以为然——市面上绝大多数的脚手架工具本质上是把一堆模板文件复制到你的硬盘里然后你就得自己去把那些“默认结构”改成你真正想要的东西。但真正把 T3 Stack 的 CL I 工具链create-t3-app社区里也普遍叫它 t3code完整跑了一遍之后我的想法改变了。它带给你的不只是一份能编译的模板代码而是一整套已经被验证过的全栈技术选型方案TypeScript 贯穿前后端、tRPC 做 API 层、Tailwind 处理样式、Prisma 操作数据库、NextAuth 搞定鉴权。这套组合的核心价值用一句话概括就是让类型安全从数据库一路延伸到浏览器里中间不打折。这篇文章是写给两类人看的一类是被 Next.js 项目里错综复杂的“逻辑该放哪”困扰的开发者另一类是已经在用 React 但想搭一个真正端到端类型安全的全栈应用的尝试者。我会从背景讲起然后完整走一遍建项目的交互过程拆解 tRPC 的核心机制用一个真实 CRUD 例子把数据库、鉴权、前端调用全串起来最后聊聊部署和实际踩坑的心得。1. T3技术栈到底在解决什么问题——会被全栈选型地狱劝退的开发者先看这里1.1 全栈开发的“组合成本”为何比你想的高单独看 Next.js、Prisma、Tailwind、tRPC每一个都是成熟得不能再成熟的技术。但“成熟”不等于“组合起来就好用”。我见过太多团队前端用了 Next.jsAPI 层又单独起了个 Express 服务前端再用 axios 自己定义每个接口的返回类型。三层语言各自有类型定义但没有一个统一的来源接口一变前端报错的方式永远是在运行时弹 undefined。这种割裂最直接的后果是**类型变成了文档而不是约束。**你说接口返回{ id: number, name: string }但是后端重构时把name改成了username前端不会在编译期发现只会在用户点开页面之后发现展示区域一片空白。改代码的人以为自己只动了自己那层实际上链条上的每一个人都要跟着手动排查。T3 Stack 的理念恰恰相反。它要求 TypeScript 不仅是语言层面的选择更要是通往前端 API 层和后端服务层的规则。tRPC 让你不用写 REST 路由不用手动造 URL不用维护两份类型定义服务端的procedure就像函数一样被前端直接调用并且类型自动推导。这才是它最迷人的地方。1.2 T3 Stack的核心哲学类型安全不是锦上添花T3 Stack 名字里的三个 T分别是 TypeScript、Tailwind、tRPC。第四个 T 是社区经常开玩笑说“缺的那个 T”代表开发者自己选——实际上最常被选的是 Prisma 和 NextAuth。它的创始人 Theo 在多次分享里都反复强调一个观点只用 TypeScript 但不打通类型链路等于白用。举个例子。没用 tRPC 之前你写一个“获取文章列表”的请求要经历这些步骤在 API 端点定义响应结构、在 .ts 文件里手写interface Article、在封装好的 fetch 函数里标注返回类型。三步之间任何一步忘记同步编译期都不会报错。用了 tRPC 之后后端的router.getArticles.query()就是前端可以导入并直接调用的函数返回值类型由后端推断出来你在前端拿到data的那一刻IDE 已经知道data[0].title是字符串了。这不是“少写几行代码”这种表面收益。它意味着**重构时IDE会告诉你哪里没改而不是靠测试靠用户发现问题。**对于中小型全栈项目而言这种约束带来的安全感比任何测试覆盖率都更要命。1.3 t3code在整套方案里扮演的角色T3 Stack 是方法论t3code 则是把这个方法论固化成工具的脚手架。它把 Next.js App Router、Tailwind、Prisma、NextAuth、tRPC 这些技术预先组合在一起并且处理好版本间的兼容关系。实际使用中这个角色相当重要。因为 Next.js 生态每隔几个月就有一次大版本迭代App Router 取代 Pages RouterNextAuth 变成 Auth.jstRPC 版本也从 v10 升到 v11。新手如果自己看官方文档逐步集成很可能卡在不同包对 React 版本、对 Next.js 版本的依赖冲突上最后装了一堆互不兼容的包。脚手架帮你把这些矩阵兼容问题都处理好了你打开项目就能开始写业务而不是坐在电脑前折腾依赖。2. 初始化项目从空目录到能跑起来的第一步2.1 环境准备与最简命令开始之前先确认本机的环境Node.js 版本建议 18.17 以上create-t3-app 会检查太低会直接报错包管理器看个人习惯npm、pnpm、yarn、bun 都支持推荐直接装一个 pnpm磁盘占用小安装速度快后面跑 Dev Server 的时候体验明显最基础的命令其实只有一行npm create t3-applatest如果你用的是 pnpmpnpm create t3-applatest执行之后命令行会先问项目名称比如输入my-t3-app然后生成一个同名目录让你选择具体要启用哪些功能。2.2 交互式配置的每个选项意味着什么create-t3-app 的交互界面做得很清晰它不会一口气要求你选十几个选项而是按顺序问你几个关键选择。默认会提供这些选项选项说明我的建议TypeScript是否可以禁用关闭后整体项目就不用 TS保留T3 的灵魂就是类型安全关掉就没意义了Tailwind CSS预装 Tailwind 并配置好样式体系保留虽然你后面可能用自己的 UI 库但 Tailwind 的原子类在国外模板里很常见tRPC是否启用 tRPC 作为 API 层保留这是整个 T3 的核心卖点Authentication预装 NextAuthAuth.js如果你确定不用鉴权可以关掉但大多数项目都用得上Prisma预装 ORM 和数据库连接配置保留否则 tRPC 缺一个数据来源示例代码就跑不起来ESLint、Prettier代码规范工具保留懒人养成好习惯的方式选完之后命令会让你选择包管理器。这一步别太纠结平时用什么就选什么。我自己一般选 pnpm因为后续安装快磁盘上也省空间。2.3 生成的目录结构哪些文件别乱动哪些随便改项目生成之后第一件让我觉得舒服的事是它有清晰的“recom 结构化”约定。核心目录大致长这样src/ app/ // Next.js App Router 页面目录 api/auth/ // NextAuth 路由处理 layout.tsx page.tsx server/ api/ root.ts // 汇总所有子路由 routers/ post.ts // 默认示例路由 trpc.ts // tRPC 实例的初始化 auth.ts // NextAuth 配置 db.ts // Prisma 客户端实例 trpc/ react.tsx // 前端 React 集成Provider hooks server.ts // 服务端调用 tRPC 的封装刚开始看到这个结构我犯过一个小错误把业务页面直接塞在app目录下逻辑顺手写到组件里结果组件越写越肿。后来习惯了这个项目的分层方式才意识到它想传达的思路是——页面持有数据获取逻辑业务逻辑收敛到 tRPC router 层数据库访问统一走 Prisma。文件管理上有个区分src/server/db.ts、src/server/auth.ts这种被多处引用的模块不要随便改导出方式而routers/下的文件是你可以自由发挥的业务领域新增一个模块就新建一个xxx.ts然后在root.ts里注册。3. 核心代码逻辑拆解tRPC是怎么把前后端焊死在一起的3.1 tRPC的底层思路一个让你不再写REST路由的方案tRPC 的全称是 TypeScript Remote Procedure Call。它做的事情其实很朴素把后端函数变成前端可以安全调用的远程过程。不用它的时候你写 REST API 是这个体验前端用fetch(/api/post/1)后端用app.get(/api/post/:id)中间靠人为约定参数格式和返回格式。一旦约定被破坏运行时爆炸。用了 tRPC你的后端子路由会变成一个个“函数式端点”。例如服务端定义了一个查询export const postRouter router({ getById: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) { return await ctx.db.post.findUnique({ where: { id: input.id } }); }) });前端调用的时候不需要拼 URL不需要写 fetch而是像调用本地函数一样const { data } api.post.getById.useQuery({ id: 1 });而且你拿到的data类型是服务端 Prisma 查询返回的类型直接贯穿过来的。前端和后端之间没有第二份interface需要维护。3.2 默认模板里rootRouter的三层结构打开src/server/api/root.ts你会看到类似这样的代码import { postRouter } from ~/server/api/routers/post; import { createCallerFactory, createTRPCRouter } from ~/server/api/trpc; export const appRouter createTRPCRouter({ post: postRouter, }); export type AppRouter typeof appRouter;这里的结构是最外层appRouter下面挂各个子模块例如post、user、note。每个子模块内部由多个procedure组成每个 procedure 可以调用一次数据库查询或写入操作。这个双层的命名空间设计和前端调用是一一对应的。如果你在根路由注册了note: noteRouter前端就是api.note.createNote.useMutation()如果你在 noteRouter 里写了getAll: publicProcedure.query(...)前端就是api.note.getAll.useQuery()。类型推导的关键在于底部的export type AppRouter typeof appRouter。前端 React hooks 的泛型类型都来自这个AppRouter类型。你新增任何一个 router、修改任何一个返回值前端 IDE 会在保存的瞬间给出反馈。3.3 从server端到client端的类型传递规则很多第一次用 tRPC 的人会困惑数据到底是怎么从前端请求到后端的其实默认情况下tRPC 走的是 HTTP POST 请求请求体里包含了 procedure 路径和参数。路径自动生成不需要你手动写/api/trpc/post.getById这种字符串。前端脚手架里已经帮你配好了httpBatchLink这个 link 还有个很有意思的特性**自动 batching。**如果你在一个渲染周期内连续调用了多个 querytRPC 会把它们合并成一个 HTTP 请求发出去减少网络往返。在高延迟场景下这个优化体感很明显。类型传递的规则其实不复杂服务端 procedure 的input类型通过 zod schema 定义前端调用时入参自动匹配服务端 query 或 mutation 的返回值通过 TypeScript 推断前端拿到后在编辑器里即可得到完整类型提示受保护的 procedureprotectedProcedure自带当前用户对象类型前端也可通过useSession得到用户信息正是这条链路让“前后端共享类型”不再是一个需要引入 monorepo 或 codegen 才能实现的重活儿。4. 数据库、鉴权与完整示例一条笔记应用的CRUD全链路4.1 Prisma连接SQLite的最简配置新建项目默认会生成 Prisma schema并且预置了一个 Post 模型。如果你只想快速验证全链路先用 SQLite 起步最省事。打开prisma/schema.prisma把默认内容改成generator client { provider prisma-client-js } datasource db { provider sqlite url env(DATABASE_URL) } model Note { id String id default(cuid()) title String content String createdAt DateTime default(now()) updatedAt DateTime updatedAt userId String user User relation(fields: [userId], references: [id]) } model User { id String id name String? notes Note[] }然后把.env文件里的连接串改成DATABASE_URLfile:./db.sqlite执行迁移npx prisma migrate dev --name init这条命令会创建数据库文件并在 Prisma Client 中同步新的模型类型。切回代码编辑器你会发现ctx.db.note已经有了完整的类型提示。4.2 NextAuth接入和受保护路由的写法脚手架默认的src/server/auth.ts已经配置好了 NextAuth你只要在prisma/schema.prisma里保持了 User 模型再填入一个适合你项目的 Provider 即可。开发阶段最简单的是用 GitHub OAuth需要到 GitHub Developer Settings 里申请一个 OAuth App得到 Client ID 和 Client Secret填到.env中。鉴权与 tRPC 的结合点在src/server/api/trpc.ts中有一段中间件逻辑export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }); });这段代码的意思是所有用protectedProcedure定义的接口都会先检查是否有用户会话。没登录直接抛错登录了就把用户信息注入到后面的 handler 里。这样你在数据库层操作时可以通过ctx.session.user.id知道“当前是谁”。注意一个细节NextAuth 的session回调里默认user.id只在数据库 session 模式下存在。脚手架里已经帮你加了id字段的映射不要为了省事把它删掉——后面所有查询当前用户笔记的逻辑都依赖这个 id。4.3 用zod校验输入一个完整的createNote例子现在我们在src/server/api/routers/目录下新建note.tsimport { z } from zod; import { createTRPCRouter, protectedProcedure } from ~/server/api/trpc; export const noteRouter createTRPCRouter({ create: protectedProcedure .input( z.object({ title: z.string().min(1, 标题不能为空), content: z.string().min(1) }) ) .mutation(async ({ ctx, input }) { return await ctx.db.note.create({ data: { title: input.title, content: input.content, userId: ctx.session.user.id } }); }), getAll: protectedProcedure.query(async ({ ctx }) { return await ctx.db.note.findMany({ where: { userId: ctx.session.user.id }, orderBy: { createdAt: desc } }); }), delete: protectedProcedure .input(z.object({ id: z.string() })) .mutation(async ({ ctx, input }) { await ctx.db.note.deleteMany({ where: { id: input.id, userId: ctx.session.user.id } }); return { success: true }; }) });这里有两个值得留意的细节。一是 zod 的.min(1)校验前端传空字符串时请求会在进入数据库之前就被拦截返回 400 级错误。二是deleteMany而非delete因为 Prisma 的delete必须按唯一主键删如果加上了userId条件就要用deleteMany否则用户可能通过篡改参数删掉别人的笔记。这个安全问题虽然不起眼但在真实项目里经常出现。4.4 前端调用与自动刷新在noteRouter注册到root.ts之后前端的使用简单得不像话。以创建笔记的组件为例import { api } from ~/trpc/react; function NoteForm() { const utils api.useUtils(); const createNote api.note.create.useMutation({ onSuccess: () { utils.note.getAll.invalidate(); } }); return ( form onSubmit{(e) { e.preventDefault(); const formData new FormData(e.currentTarget); createNote.mutate({ title: String(formData.get(title)), content: String(formData.get(content)) }); }} input nametitle placeholder标题 / textarea namecontent placeholder正文 / button typesubmit保存/button /form ); }读取列表function NoteList() { const { data, isLoading } api.note.getAll.useQuery(); if (isLoading) return div加载中/div; return ( ul {data?.map((note) ( li key{note.id} h3{note.title}/h3 p{note.content}/p /li ))} /ul ); }注意onSuccess里的utils.note.getAll.invalidate()。它的含义是当create成功后自动让getAll这个查询的数据失效并重新请求。你不需要手动调用refetch也不用把新创建的笔记手动塞进旧列表——声明式的失效机制帮你搞定。这种开发体验最大的好处是你完全不用关心“数据什么时候拉取”“状态怎么同步”这些琐事把注意力集中在业务逻辑本身。5. 部署、性能与踩坑心得给刚上手的你几条实在建议5.1 Vercel部署的隐藏坑t3code 生成的 Next.js 项目部署到 Vercel 通常是一路顺风。但有几个隐藏坑值得提前知道。第一个是数据库。本地开发用 SQLite 没问题但 Vercel 的 serverless 函数文件系统是只读的SQLite 文件无法在线上持续写入。你在本地 curl 一切正常部署上去一写入就报错。解决方案是换用 PostgresVercel Postgres 或 Neon 都行连接串以环境变量的方式注入Vercel 上不需要额外配置。Prisma schema 里把 datasource 的 provider 改成postgresql再执行一次 migrate联网环境下会直接提醒你改。第二个是 NextAuth 的AUTH_SECRET。本地开发时脚手架会自动帮你生成一个部署到线上之后最好去 Vercel 的环境变量面板里手动设置一个稳定值。否则每次重新部署或冷启动时session 可能刷新异常用户会莫名其妙掉线。可以用这个命令生成openssl rand -base64 32第三个是关于 edge runtime。很多示例代码会在middleware.ts里用withAuth做页面级别的路由保护但那会隐式要求中间件在 Edge 环境运行。如果你的 NextAuth 配置里用了 Prisma adapter直接跑在 middleware 中可能会报兼容性错误。我自己的做法是不用 middleware 做鉴权依赖 tRPC 的 protectedProcedure 在 API 层拦截页面级别只在服务端组件里顺便校验 session不做重定向逻辑。5.2 什么时候该跳出T3 Stack的默认选择聊了好处也该聊聊边界。t3code 不是万能的持续用了半年多之后我总结了几类不太适合硬套的场景。如果你的 API 需要被非 tRPC 客户端调用——比如第三方通过 OpenAPI 文档对接或者你有独立的移动端去调用同一套接口——tRPC 自带的 HTTP 协议对它们不够友好。虽然 tRPC 支持引入了 OpenAPI 插件如trpc-openapi但生态完善度仍然不及 REST。如果项目里已经存在一个非常庞大的 GraphQL schema 或 REST API 服务你的目标只是给 Next.js 前端加壳那也大可不必推倒重来。t3code 适合从零起步的新项目或者你有充分把握可以同步替换旧 API 层。它是“地基”不是“补丁”。如果你对 TypeScript 本身不熟悉那 t3code 提供的类型安全反而会成为障碍。因为你很多时间会花在解决类型报错上而不是写业务代码。建议先用基础 React Vite 把 TS 手感练熟再回来上手 T3。5.3 我对t3code的几处实操体会项目代码写得久了慢慢就有了一些不成文的经验分享几个我现在每开一个新 T3 项目都会遵守的小规矩。第一所有的业务外联 API 调用比如支付回调、第三方查询都放到 router 层不要在页面组件里直接 fetch。这样一方面是为了类型安全另一方面是后续加缓存、加审计日志都只需要动一个文件而不是去全项目搜索 fetch 语句。第二zod 的 schema 与数据库表结构保持同源思路。虽然我们没有 npx prisma zod generator 这种自动生成方案但每当表结构发生变化我都会顺带检查所有相关 procedure 的 input schema避免出现“库里字段已经改名前端还在传旧参”的低级错误。第三线上日志和错误追踪要尽早配置。tRPC 抛出的TRPCError在 tRPC Server 端会记录但是在前端只能看到一条Failed to fetch之类的消息。推荐在trpc.ts里加一个全局 errorFormatter把code、path、message写入日志平台排查线上问题会高效很多。第四不要把依赖裸奔在最新版上。T3 Stack 这种“全家桶”型框架最怕某天某个底层包突然大版本升级连带其他包都要跟着改。脚手架已经帮忙锁好了各包之间的兼容组合你需要做的是定期小步升级每次升完跑一遍next build检查而不是攒半年再一次性升。做全栈项目很多时候我们在纠结的其实是同一个问题类型、接口、数据流这些知识到底应该约束在哪里t3code 给出的答案是用工具链把这些约束固化成默认结构。它不会替你写好业务也不会让你的应用变得“高级”它只是让你从日复一日的interface同步和手工拼接 URL 中解脱出来把精力放到真正有差异性的地方。如果你手头正好有一个用 Next.js API 路由的老项目被类型不同步折磨过我建议你抽一个小时用 t3code 起一个最小的验证项目随便写两个 CRUD 接口感受一下改一个字段之后 IDE 自动把所有引用处标红的过程。那种“编译器帮我把活干了”的踏实感才是我愿意在这套技术栈上持续投入的真正理由。