做久了全栈开发的人应该都经历过这种痛苦前端框架选好了后端接口也开始写了但前后端对接那一刻类型对不上、字段名写错、接口文档过时……光排查这些破事就能耗掉半天。我第一次听到“t3code”这个概念时第一反应也是“又一个新框架”后来才搞明白它并不是一个新框架而是一个把几个主流工具按最佳实践组合起来的“全家桶方案”官方叫法是T3 Stack。核心成员是TypeScript、Tailwind CSS、tRPC、Next.js搭配Prisma做数据库ORM。理解t3code的含义其实就是理解这套组合拳怎么打再加上怎么用它快速搭出一个类型安全、开发体验极爽的全栈项目。这篇文章我不打算只罗列概念我想把从零搭一个t3code项目的完整过程、踩坑记录、以及每个环节的“为什么”都写清楚适合正在选型全栈方案的人也适合想把手头项目改造成类型安全架构的团队。1. 内容整体设计与思路拆解1.1 从一次失败的全栈项目说起先讲一个我自己的真实经历。去年有一个内部工具项目后端用Express写REST API前端用Vue3数据库用MySQL。分工很明确但问题出在“接口对接”上。后端同事返回的字段叫create_time前端同事写成created_at页面一跑数据全空查了半天才发现是命名不一致。后来又遇到类型问题前端声明了number类型的id后端返回的是字符串明明数据存在判断条件却全部失效。改来改去两个人都改出了脾气。这个痛点我相信很多人经历过它本质上是前后端之间缺少一套“契约机制”。你不能指望靠文档来约束文档永远会滞后。后来我了解到t3code这套方案它的核心思路就是用TypeScript的静态类型把“契约”直接写进代码里让编译器在开发阶段就帮你拦截这类问题。前后端跑同一个类型定义后端改了类型前端立刻编译报错根本轮不到联调阶段才发现。t3code的本质不是某个单一技术的胜利而是“全链路类型安全”的组合效应。单独用TypeScript只能保证单端安全单独用tRPC也只能保证接口调用方便但把它们组合在Next.js的项目结构里类型从数据库模型一路流到前端组件整条链路都是通的。这种体验一旦用上就很难回去了。1.2 t3code全家桶的四个核心成员与隐藏队友很多人第一次听到T3这个名字都会以为是什么新框架的代号其实T3来自The TypeScript Toolkit的缩写。官方定义的四个核心成员分别是Next.js承担前端页面渲染和API路由既支持服务端渲染也支持静态生成。TypeScript全项目统一使用提供静态类型检查。Tailwind CSS原子化CSS框架快速写样式省去大量样式文件。tRPC解决前后端API通信用TypeScript为整个调用链提供类型安全。在实际项目里还有一个几乎必装的隐藏队友就是Prisma。它作为数据库ORM负责把数据库表结构映射成TypeScript类型。用t3code搭起来的项目数据模型层、接口层、页面层这三层用的是同一套类型系统。数据库表加了字段代码提示立刻更新前后端调用也立刻感知这是它最爽的地方。有人可能会问用REST或GraphQL不也行吗当然行但与之相比tRPC省去了定义接口文档、生成类型定义、处理序列化等一系列额外步骤。REST需要人为维护URL设计和响应结构GraphQL需要写schema和执行层逻辑。tRPC直接调用后端函数就像调用本地函数一样类型自动继承少了一整类心智负担。1.3 这套组合能火的原因以及它的边界T3 Stack之所以在开发者社区里传播快热度持续不减我认为有几个原因。第一它契合了“少即是多”的极简哲学——官方口号就是“构建类型安全的全栈应用最稳妥的方式”没有引入复杂的Babel配置、自定义构建流程所有工具都开箱即用。第二它把“类型安全”从一种工程规范升华成了开发体验的一部分让开发者不知不觉就写出高质量代码。第三社区资源丰富create-t3-app这个脚手架已经非常成熟开箱分层清晰适合小团队快速启动内外部工具。但也要说清楚它的边界。t3code面向的场景是“前后端紧密耦合的应用”尤其适合内部工具、中小型Web应用、MVP原型。如果你的场景是开放API平台、需要大量外部消费者或者涉及复杂权限网关那tRPC的表现就不如REST或GraphQL灵活。对于这类需求还是要对架构做更充分的评估不要盲目套用t3code全家桶。2. 核心细节解析与实操要点2.1 环境准备先把底子打好在真正初始化项目之前我有几个环境层面的建议。Node.js版本最好在18.17以上因为新版Next.js和Prisma对Node版本有最低要求。包管理器建议用pnpm实测下来它对依赖安装速度和磁盘空间更友好而且t3app官方文档里的命令默认也支持pnpm。如果电脑还没装可以用corepack enable来开启pnpm支持这是Node自带的功能不用单独全局安装。还有一点容易被忽略尽量在干净的目录下操作。之前我在一个已经装了旧版本依赖包的目录里直接初始化t3项目结果Next.js版本冲突报了一堆peer dependency错误。虽然最终靠删除node_modules解决了但白白浪费了半小时。建议新建一个独立文件夹在空目录里执行初始化命令能避开很多诡异问题。2.2 初始化项目create-t3-app全流程拆解初始化t3项目很简单执行一行命令pnpm create t3-applatest命令行会进入交互模式先让你输入项目名然后让你选择需要的模块。我建议第一次尝试时全部勾选Next.js、TypeScript、Tailwind CSS、tRPC、Prisma还有NextAuth.js。别觉得多新版脚手架生成的目录结构已经非常清晰不会带来额外负担。万一不需要某个模块后面手动删起来也没那么麻烦。选择完成后它会自动安装依赖并生成基础配置。有个细节需要注意整个过程中会让你选择App Router还是Pages Router。这三个二选一时我更推荐App Router因为Next.js 14以后官方推荐方向就是App RoutertRPC新版也深度兼容它的Server Components未来的生态资源会越来越多。初始化完成后进去看一眼目录结构project-name/ src/ app/ api/trpc/[trpc]/route.ts layout.tsx page.tsx server/ api/routers/ db/ trpc/ router.ts server.ts prisma/ schema.prisma这个结构不需要强行背只要理解它的设计逻辑就行src/app负责页面和API路由src/server负责后端逻辑src/trpc负责前后端共享的路由定义。Prisma的schema文件独立在prisma目录。分工清晰各回各家。2.3 配置Tailwind与基础页面初始化后你会立刻获得一个可用页面但样式组件还需要自己搭。Tailwind CSS在t3项目里默认已经配置好可以直接在className里使用原子类。比如要做一个居中的卡片布局可以快速写出来div classNameflex min-h-screen items-center justify-center div classNamew-full max-w-md rounded-xl border border-gray-200 bg-white p-8 shadow-md h1 classNametext-2xl font-bold text-gray-900欢迎使用 t3code/h1 p classNamemt-2 text-gray-600类型安全的全栈应用从这里开始。/p /div /divTailwind的实际价值在真实项目里会被放大。以前写CSS要维护一个全局样式文件类名容易冲突现在所有样式都内联在组件里改样式不会影响其他页面。配合VS Code的Tailwind插件写类名时有自动补全效率确实高很多。有个小窍门如果发现某个样式在多个组件中反复出现不要急着抽成自定义CSS类可以先用Tailwind的apply在组件层做一层封装或者直接抽成一个小组件。原子化CSS一旦养成了“组合”的思维项目会越来越轻盈。2.4 接入tRPC第一个类型安全接口的诞生tRPC可以说是t3code的灵魂。理解它的关键在于它让前端像调用本地函数一样调用后端函数而类型信息全程不断。用一句话对比更容易理解REST是点到点的URL请求tRPC是函数到函数的直接调用。在t3项目里定义后端接口只需要在src/server/api/routers下新建路由文件。比如创建一个post.tsimport { z } from zod; import { createTRPCRouter, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ getAll: publicProcedure.query(async ({ ctx }) { return ctx.db.post.findMany(); }), getById: publicProcedure .input(z.object({ id: z.number() })) .query(async ({ ctx, input }) { return ctx.db.post.findUnique({ where: { id: input.id } }); }), });然后记得在根路由文件src/server/api/root.ts里把它挂载进去export const appRouter createTRPCRouter({ post: postRouter, // 其他路由 });看到zod出现的地方就是参数校验的入口。在tRPC里zod不仅负责运行时校验还能通过类型推导给前后端提供静态类型。这是一个非常优雅的设计你在后端定了一个id是number前端如果传了字符串编写代码时就会直接看到红色波浪线而不是运行时才发现。前端调用它的方式也很直接在组件里写import { api } from ~/trpc/react; export function Posts() { const { data: posts, isLoading } api.post.getAll.useQuery(); if (isLoading) return div加载中.../div; return ul{posts?.map((p) li key{p.id}{p.title}/li)}/ul; }看起来只是调了一个函数但数据请求、缓存、状态管理都给你安排好了不需要额外引入react-query因为tRPC底层已经内置了query client。2.5 引入Prisma数据库层的关键一环刚才的例子中出现了ctx.db.post.findMany()这个ctx.db就来自Prisma客户端。t3项目初始化时已经把Prisma接入好了你只需要把prisma/schema.prisma里的demo模型改成自己的业务模型。比如定义一个简单的用户模型model User { id String id default(cuid()) email String unique name String? createdAt DateTime default(now()) }改完模型之后执行两条命令pnpm prisma generate pnpm prisma db pushgenerate用于生成Client类型db push用于把模型同步到开发数据库。这两个命令几乎每次改模型都要用建议记住。这里提醒一个坑如果你之前只跑过generate没有跑db push页面里调用api.post时会报数据库表不存在的错误看起来像是代码写错了其实是模型没同步。Prisma的另一个优势是自带Seed能力。在prisma目录里新建seed.ts运行时执行pnpm prisma db seed就可以插入测试数据。我习惯在项目初始化后立刻写一个简单的seed文件填充十几条假数据后续前端开发时不用反复造数据。3. 实操过程与核心环节实现3.1 完整案例做一个待办事项清单理论说再多不如做一个真实的小项目。我拿“待办事项清单”这个经典场景来演示t3code的完整能力。这个需求麻雀虽小五脏俱全能覆盖数据库模型、服务端API、前端调用、状态更新四个核心环节正好检验一家全家桶方案的成色。先定义数据模型。在prisma/schema.prisma中加入model Todo { id String id default(cuid()) title String completed Boolean default(false) createdAt DateTime default(now()) }模型尽量简洁一个标题一个完成状态一个创建时间。做小项目时不要急着加太多字段等需求明确后再扩展即可。这里用cuid而不是自增id是因为cuid在分布式环境下不容易冲突不需要额外查最大值。3.2 服务端定义tRPC路由在src/server/api/routers/todo.ts中写入完整的增删改查逻辑import { z } from zod; import { createTRPCRouter, publicProcedure } from ../trpc; export const todoRouter createTRPCRouter({ getAll: publicProcedure.query(({ ctx }) { return ctx.db.todo.findMany({ orderBy: { createdAt: desc }, }); }), create: publicProcedure .input(z.object({ title: z.string().min(1) })) .mutation(({ ctx, input }) { return ctx.db.todo.create({ data: { title: input.title }, }); }), 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: { completed: !todo.completed }, }); }), delete: publicProcedure .input(z.object({ id: z.string() })) .mutation(({ ctx, input }) { return ctx.db.todo.delete({ where: { id: input.id } }); }), });这里面mutation和query的语义区别要弄清楚。query负责读取mutation负责写操作。tRPC自己不会限制你必须在query里做只读事情但按这个约定写代码意图会更清晰后续也容易加缓存策略。3.3 前端调用接口并处理UI状态服务端就绪后页面侧的代码非常简单。用useState维护一个输入框的内容然后用api.todo.create的mutation把新待办写入数据库use client; import { useState } from react; import { api } from ~/trpc/react; export default function TodoList() { const utils api.useUtils(); const [title, setTitle] useState(); const { data: todos, isLoading } api.todo.getAll.useQuery(); const createTodo api.todo.create.useMutation({ onSuccess: () utils.todo.getAll.invalidate(), }); const toggleTodo api.todo.toggle.useMutation({ onSuccess: () utils.todo.getAll.invalidate(), }); const deleteTodo api.todo.delete.useMutation({ onSuccess: () utils.todo.getAll.invalidate(), }); if (isLoading) return div加载中.../div; return ( div classNamemx-auto max-w-lg p-6 h1 classNametext-xl font-bold我的待办/h1 form onSubmit{(e) { e.preventDefault(); createTodo.mutate({ title }); setTitle(); }} classNamemt-4 flex gap-2 input value{title} onChange{(e) setTitle(e.target.value)} classNameflex-1 rounded border p-2 placeholder输入待办内容 / button typesubmit classNamerounded bg-blue-600 px-4 py-2 text-white 添加 /button /form ul classNamemt-6 space-y-2 {todos?.map((todo) ( li key{todo.id} classNameflex items-center justify-between border-b py-2 label classNameflex items-center gap-2 input typecheckbox checked{todo.completed} onChange{() toggleTodo.mutate({ id: todo.id })} / span className{todo.completed ? line-through text-gray-400 : } {todo.title} /span /label button onClick{() deleteTodo.mutate({ id: todo.id })} classNametext-sm text-red-500 删除 /button /li ))} /ul /div ); }这段代码里有一个关键模式每个mutation都调用了utils.todo.getAll.invalidate()。它的作用是让tRPC缓存失效触发重新请求最新数据。刚开始用t3code的人最常犯的错误是添加完数据后页面不更新然后手动写一次useRouter().refresh()其实只要invalidate即可。跑起来后整个待办清单就完整可用添加、勾选、删除、刷新全部类型安全修改数据库模型后编译阶段就能发现前后端类型不匹配的问题。这个项目麻雀虽小但已经展示了t3code整个工作流的爽感。4. 常见问题与排查技巧实录4.1 类型不匹配开发时最常见的报错用t3code类型系统的好处是“错误出现得早”但这也意味着刚开始你会经常面对一些看起来莫名其妙的类型报错。比如你在服务端返回的字段叫userName前端拿到后却用了nameTS立刻标红。这时候不要急着用any跳过去耐心跟一下类型定义。一般来说Prisma模型就是源头tRPC的返回类型会从Prisma自动推导前端拿到的一定和模型层一致。如果对不上先看服务端return的对象再看前端接收的变量类型问题大多出现在手写的映射逻辑里。另一个常见情况是input参数没写zod校验或者校验类型对不上。比如前端传了字符串id后端期望numbertRPC会在运行时做zod校验并直接返回报错信息。调试时可以先在浏览器Network面板看请求和响应体大多数情况下错误信息已经写得很明确了。这类报错其实都是t3code在帮你不要反感。4.2 tRPC路由不显示或返回404有一次我在root.ts中只添加了路由名但忘记在routers目录中创建对应的文件结果页面调用时一直报404。排查过程中我仔细检查了路由注册。tRPC的Router定义是树结构的root.ts是根节点里面引用的每个子路由模块都必须真实存在且导出命名正确。建议新增路由时先把空文件建好再挂载可以避免这种问题。另一个容易出问题的点是文件名大小写。Linux环境下routers文件夹里Post.ts和post.ts是两个文件Windows却会自动忽略大小写导致本地跑得好好的推到服务器上就404。这是跨平台开发的经典坑建议目录和文件名统一用小写。4.3 Prisma首次执行与数据库连接的问题新版脚手架默认使用SQLite零配置就能跑起来适合单机开发。但如果你准备和团队协作或准备部署到服务器建议切到PostgreSQL或MySQL。切换时不只是改DATABASE_URL还要重新生成Client。有一次我把连接串改成PostgreSQL后忘了跑generate结果一直报某个模型字段不存在因为Client还是按SQLite生成的。另外要特别记住一个顺序改schema文件后先执行pnpm prisma generate再执行pnpm prisma db push。generate负责更新代码里的类型db push负责更新真实的数据库表。顺序反了可能不会报错但有可能出现代码能跑但类型提示还是旧的情况非常迷惑人。在开发阶段数据库连接串建议直接放在.env文件。如果有多个环境变量文件base配置变化后需要重启开发服务器才会加载别改完环境变量就怀疑代码写错了。4.4 部署上线的一些建议t3code项目部署到生产环境时有几个标配动作要做。第一项目用Next.js构建所以可以遵循Next.js的标准部署流程。Vercel是最顺滑的选项因为Next.js本身就是它的作品。第二部署前一定要执行数据库迁移我用的是prisma migrate deploy它会在生产库上应用所有迁移记录。如果跳过这步服务端调用任何数据库操作都会报错。第三环境变量要仔细核对尤其是DATABASE_URL和AUTH_SECRET这类敏感项。还有一次部署踩坑是构建阶段内存不足。因为Prisma generate和Next.js构建同时进行服务器内存不够导致构建进程被系统杀掉。后来在构建命令里限制Node内存才解决。类似这种问题在本地可能一辈子遇不到但上了服务器就讲究运气了。建议部署前先在本地用pnpm build跑一遍完整构建能提前暴露大部分问题。4.5 调试与性能的一些心得关于调试我还是推荐最朴素的console.log加浏览器Network面板。tRPC的请求其实就是一个标准HTTP请求完全可以用既有工具观察。想看更多上下文信息再加一个console.log在trpc server.ts的onError回调里服务端报错会输出完整的堆栈信息排查问题效率提高不少。性能方面有两个点值得关注。一个是tRPC的query默认有缓存如果数据更新了但页面不刷新这很可能是缓存策略在起作用。另一个是不要在一个页面里调用过多tRPC query宁可把接口设计成聚合型减少请求数量。我见过有人在同一个页面里写了十几个useQuery每个都去查数据库虽然t3code没有限制这样用但数据库连接池迟早会报警。好的设计是面向页面需求定义路由一次请求拿回足够页面渲染的数据这比贪图接口语义化更重要。从我个人体会来说t3code最打动我的地方不是某个单独技术有多惊艳而是它把“类型安全”从一个口号变成了日常开发过程中能真实感知到的体验。最初我担心学这一套东西有门槛但实际用下来发现脚手架已经把大部分集成工作做完了真正需要思考的只是业务代码。如果你正在做内部工具、MVP、中小型Web应用而且受够了前后端联调时反复传参、反复翻文档的痛苦那这套方案值得认真一试。刚开始不要贪多先照着上面的流程跑通一个待办清单你就能感受到从数据库到前端的全链路类型安全到底是种什么样的体验。后续再把自己手头的业务往这个结构里迁移会比推倒重来轻松很多。
原理与应用实践)
