★ FEATURED ARTICLE 1. “t3code”到底是个什么先把这个热词背后的一整套东西拎清楚最近在技术社区里“t3code”这个搜索词被频繁捞起来。如果你跟我一样第一眼看到这个词就去翻资料大概率会落到一个组合上——T3 Stack也就是由TypeScript、Tailwind CSS、tRPC三大件外加 Next.js 作为主框架组成的一套全栈开发方案通常配合 Prisma 和 NextAuth 一起用。社区里管它叫“T3 Code”指的不是某个神殿级别的算法而是一套能立刻上手、端到端类型安全、样板代码极少的现代 React 全栈脚手架。我先说结论这玩意儿不是某个大厂推出来的商业框架而是一个开源社区自发沉淀下来的最佳实践组合。核心项目叫create-t3-app作者是 TheoGitHub 上星标常年稳定在几万量级。它解决的是当下前端开发里一个很直接的痛点——选型疲惫症。你想做一个带数据库、带鉴权、带 API 的完整应用光是把 Next.js、Prisma、tRPC、NextAuth、Tailwind 这五样拼在一起处理版本兼容、类型对接、目录规范、环境变量校验就能耗掉一整天。而 t3code 的价值就是你拿过来它已经把这一整套全给你拧成了同一根绳你只需要写好业务代码。这篇文章写给谁简单说三类人最值得读想学一套完整全栈玩法、但不想把时间浪费在胶水代码上的前端/全栈开发者已经听过 tRPC 和 Prisma 的名头、但一直没搞明白它们怎么串起来的初级用户以及已经在用 T3 Stack 做项目正卡在某些类型的推不掉、部署翻车、鉴权绕弯这些坑里的人。我自己是把 create-t3-app 用来做过一个带用户内容管理的完整官网项目对它的性格算是摸得比较透。下面不吹不黑按真实的使用路径把每一层拆开讲包括选型逻辑、初始化细节、代码链路、部署避坑以及文档里不会写但你会踩到的坑。2. 为什么是 T3 Stack 这套组合选型逻辑不是赶时髦学习一个技术方案之前先搞懂它“为什么这样设计”比直接抄代码重要得多。t3code 这套组合选得看起来随意实际上每一个选择背后都有一层“为什么”。2.1 TypeScript 打底拒绝半吊子类型安全T3 里的第一个 T是 TypeScript。“类型安全”这四个字放在 2024 年已经不算新鲜但 T3 Stack 把它做到了今天的极限——从数据库到页面组件全程不断层。这依赖的不是复杂的代码生成工具而是 TypeScript 的类型推断机制Prisma 根据你的数据库 schema 生成 Client 类型tRPC 从服务端路由推断出客户端可用的类型Next.js 又把服务端拿到的东西直接交给组件。这就形成了一个链路数据库表结构 → 类型定义 → API 返回 → 前端组件使用 → 实时提示。全程没有任何一个环节需要你手动去写接口的 DTO 或重复的类型声明。你改一个数据库字段前端组件的类型错误立刻爆出来你在服务端加一个查参数调用端自动就能自动补全。这个体验用一句话概括你写的代码少但编译器盯得紧。2.2 很多人没想明白为什么中间层偏偏是 tRPC大多数没有正经用过 tRPC 的人第一反应是“这东西是什么跟 REST 和 GraphQL 比成熟吗”我最初也是这么想的直到我意识到——在一个 Next.js 全栈应用里前后端代码共享同一个 Git 仓库跑在同一个部署单元里你为什么还需要对外提供一份完整的 REST APIREST 假设的是“服务端和客户端彼此不认识要通过协议沟通”。但在 T3 Stack 的场景里前端页面、服务端函数、数据模型全在同一个 codebase 里服务端可以直接把路由类型注入给客户端。于是你写 API 再也不用定义路由路径字符串/api/post/getAll在 controller 里反复处理参数校验、错误码在客户端手写一套 fetch 封装维护一份永远容易过期的 API 文档你只需要在routers/下面定义一个 procedure然后前端直接导入它的调用方法。tRPC 做的不多不少刚好把“前后端之间那段胶水”干掉。这跟“不用 REST 不专业”的观点不冲突。如果你做的是开放平台、需要被第三方调用的公共服务请老老实实用 REST 或 GraphQL。但如果你做的是自己的产品后台、内部工具、需要快速交付的全栈应用tRPC 在这个场景里是最优解而不是妥协。2.3 Tailwind 不是装饰是快速建站的引擎T3 里的 Tailwind CSS 经常被只看表面的开发者当成“原子化框架又炒冷饭”。但实际项目里它真正解决了“写样式到底该往哪个文件里放”的问题。传统 CSS-in-JS 方案在服务端渲染时会面临样式注入时机的问题纯 CSS 文件多了以后命名和清理成本极高而 Tailwind 的做法是把样式原子化直接在 JSX 里完成视觉搭建。t3code 默认带上它之后新项目的首屏样式可以直接在组件代码里写不用新建样式文件不用纠结 class 名改完刷新就行。当然原子类是会上瘾的写习惯了之后再看那种一个按钮写三十行.btn-primary的代码会有一种“这玩意儿怎么维护”的窒息感。这一点我不多做评判反正 T3 Stack 的默认选择就是 Tailwind喜欢的人觉得如鱼得水不喜欢的话也可以保留它的类名逻辑只做你自己的设计系统。提示T3 Stack 的选型核心逻辑是“让类型定义成为前后端沟通的唯一权威来源”。理解这一点后面看任何代码都不会发怵。3. 从命令行到跑通首屏create-t3-app 的初始化细节与目录解剖组装整套技术栈虽然能收获“自己配环境”的快感但真正做项目的人没这个时间。t3code 的价值集中体现在初始化这一步——它给出了一整套交互式 CLI 配置让你在几十秒内跑起一个五脏俱全的工程。3.1 初始化的完整操作假设你环境里已经装好了 Node.js建议 18最好 20直接执行npm create t3-applatest my-project然后你会进入一个交互式选项界面可以勾选需要包含的模块Tailwind CSS —— 推荐勾选NextAuth.js —— 做登录或后台鉴权就勾纯展示站可以先不勾Prisma —— 要连数据库就勾这是后面类型安全的根基tRPC —— 全栈类型打通的核心建议勾选择完毕后CLI 会让你选要不要初始化 Git 仓库通常建议选 yes然后问你用哪个包管理器安装依赖。npm 和 pnpm 都行我个人习惯 pnpm安装速度确实快不少。装完之后你就能看到项目的基本结构和普通 create-next-app 出来的目录相比多了几个关键文件├── prisma │ └── schema.prisma ├── src │ ├── env.mjs │ ├── pages │ │ └── api │ │ └── trpc │ │ └── [trpc].ts │ ├── server │ │ ├── api │ │ │ ├── routers │ │ │ ├── root.ts │ │ │ └── trpc.ts │ │ ├── auth.ts │ │ └── db.ts │ └── utils │ └── api.ts3.2 这几个文件是想让你一眼看懂整个请求链路很多初学者在这一步会懵tRPC 的 endpoint 在哪数据库连接在哪我应该从哪里开始写业务实际上这套目录结构已经把“职责边界”画得很清晰src/server/db.ts—— 创建 Prisma Client 的唯一入口全局只创建一次实例src/server/api/trpc.ts—— 初始化 tRPC 上下文和事务边界src/server/api/root.ts—— 汇总所有子路由src/pages/api/trpc/[trpc].ts—— 唯一的服务端入口点Next.js 请求打到这里后分发到对应 routersrc/env.mjs—— 用 zod 校验所有环境变量缺一个启动就报错从源头防止“明明配了却没生效”这套分层和传统三层架构有点像但不那么死板。你只需要往routers里加文件然后在root.ts里挂一个appRouter即可。3.3 数据库连接的初始化prisma migrate 必须早点做在跑npm run dev之前我建议先做一件事把数据库模型定义好并完成首次迁移。因为这个项目的核心链路高度依赖 Prisma 生成的类型——如果schema.prisma是空的tRPC 估计也写不出什么东西。cd my-project npm run db:push这条命令会读取prisma/schema.prisma的内容并同步到数据库。默认情况下create-t3-app 生成的 schema 里有一个简单的示例模型。如果你用的是 SQLite直接改DATABASE_URL指向一个本地文件路径跑迁移后数据库文件就会建立起来。如果用的是 PostgreSQL 或 MySQL连接串正确后同样可以同步。我第一次用的时候偷了个懒没做 migrate直接写了一个查询数据库的 procedure结果前端调用时 TypeScript 一直报类型不存在。后来才意识到Prisma Client 需要根据 schema 生成之后才会在代码里暴露对应的类型定义。先generate或db:push再写业务代码这个顺序很重要。4. 核心链路实战数据库模型、tRPC 路由与页面组件的完整打通跑通空项目不算本事把一条真实业务链路走通才是关键。我用一个最简单也最有代表性的场景——文章列表 单篇文章详情完整演示一遍从数据库到页面渲染的所有环节。这个链路覆盖了 t3code 绝大多数开发场景的基本模式。4.1 定义数据模型在prisma/schema.prisma里先定义两个模型model Post { id String id default(cuid()) title String content String published Boolean default(false) createdAt DateTime default(now()) updatedAt DateTime updatedAt } model User { id String id default(cuid()) name String? email String? unique emailVerified DateTime? image String? posts Post[] }运行npx prisma db:push npx prisma generate这时候node_modules/.prisma/client里已经有了Post和User的完整类型定义。4.2 写第一个 tRPC 路由来到src/server/api/routers/post.tsimport { z } from zod; import { createTRPCRouter, publicProcedure } from /server/api/trpc; export const postRouter createTRPCRouter({ getAll: publicProcedure.query(async ({ ctx }) { return ctx.db.post.findMany({ orderBy: { createdAt: desc }, where: { published: true }, }); }), getById: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) { return ctx.db.post.findUnique({ where: { id: input.id }, }); }), create: publicProcedure .input( z.object({ title: z.string().min(2), content: z.string().min(10), }) ) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, }, }); }), });然后挂到src/server/api/root.tsimport { postRouter } from /server/api/routers/post; export const appRouter createTRPCRouter({ post: postRouter, });这一段代码有几个点值得留意publicProcedure表示无需登录就能调用的接口如果加上了protectedProceduretRPC 会在中间件层面调用 NextAuth 的 session 判断是否放行。ctx.db就是你在db.ts里创建的 Prisma Client它会被注入到每个 procedure 的上下文中。zod负责运行时参数校验同时推导出参数类型给前端。输入校验写在这里比自己手动if (!id) throw干净一个量级。4.3 前端调用的几种姿势在页面组件中通过src/utils/api.ts导出的api对象发起请求import { api } from /utils/api; export default function PostListPage() { const { data: posts, isLoading, refetch } api.post.getAll.useQuery(); const createPost api.post.create.useMutation({ onSuccess: () { refetch(); }, }); if (isLoading) return div加载中.../div; return ( div {posts?.map((post) ( div key{post.id} h2{post.title}/h2 p{post.content}/p /div ))} button onClick{() createPost.mutate({ title: 测试标题, content: 这是一段内容 }) } 新增 /button /div ); }在这里posts的类型是 Prisma 根据数据库推断出来的根本不需要你手动 import 任何 API 类型。这就是前面说的——类型定义顺着链路直接流到组件。.useQuery()默认会在组件挂载时执行请求返回值是由 TanStack Query 包装好的数据自带isLoading、isError、refetch等状态管理。.useMutation()处理写操作mutate触发请求onSuccess回调里刷新查询列表。注意如果你是纯服务端组件Server Component可以用createTRPCContext直接调用服务端函数不需要经过 HTTP 层。tRPC 在这里表现得很灵活但新手上路还是先掌握客户端调用模式再研究跨组件混合请求。我在做项目的时候发现tRPC 在开发模式下一个特别打动人的细节是——调用 API 时完全不需要关心 URL 或 method。写惯了 fetch 的人一开始会觉得“这太魔幻了”但这就是它的设计目标让服务端函数变成客户端可引用的“直接调用入口”。4.4 加上鉴权NextAuth 与 tRPC 如何握手如果你的项目需要登录才能发文章只需要把 procedure 从publicProcedure换成protectedProcedureimport { protectedProcedure } from /server/api/trpc; create: protectedProcedure .input(...) .mutation(async ({ ctx, input }) { if (!ctx.session?.user) { throw new Error(未登录); } return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); })这个语法有趣的地方在于鉴权并不是“在路由里写 if 判断”而是在 tRPC 中间件层面统一处理。如果会话无效case 会在进入 procedure 之前就抛出异常客户端会收到统一的错误码。这对开放接口和后台接口并存的项目来说开发体验提升极其明显。4.5 跑起来时的实际感受做完上面这些步骤之后运行npm run dev你看到的应该是一套天然自带类型提示的全栈应用。自己手动搭过 Next.js REST API 的人会立刻体会到差距以前改接口返回结构至少要去三个地方同步类型现在改完 Prisma schema推送后 TypeScript 直接告诉你哪里漏改。这种“改完模型全项目跟着变绿”的感觉确实只有用过才知道。5. 部署前的三件小事与线上运行时的坑位记录写代码是一回事儿部署是另一回事儿。t3code 官方推荐 Vercel因为 Next.js 和 Vercel 的配合确实是无缝级的。但如果你像我一样经历过几次线上翻车就会发现“默认能跑”和“稳定运行”之间还隔着几个习惯问题。5.1 环境变量校验env.mjs 的妙处create-t3-app 默认生成src/env.mjs这个文件用 zod 对process.env做校验。你在本地.env里如果漏填了某个变量启动时直接红屏报错而不是等到运行某个接口时才弹出“undefined”。这个特性对部署尤其友好当你在 Vercel 上配置了环境变量再 deploy 时构建阶段就能发现配置问题不会让你的站点带病上线。5.2 无服务器环境的数据库连接池问题Vercel 的 Lambda 环境是无状态的每个请求都可能拉起一个新的执行环境。如果每个环境都去新建一个 Prisma Client 连接到数据库会出现两个问题冷启动时间被拖长数据库连接数迅速被打满T3 Stack 其实已经替你考虑到这一点了src/server/db.ts默认使用全局变量缓存 Prisma Client 实例不会每次都创建新的连接。但在线上如果你的数据库处于比较严格的连接限制下例如很多云数据库免费版只允许少量并发连接建议在DATABASE_URL里开启连接池参数PostgreSQL 可以加?pgbouncertrue配合 PgBouncer 使用或者干脆选用普适的连接池中间件。我第一次上线时就是忽略了这一点。数据库跑在开发机上还感觉不出来一上 Vercel、稍微有点访问量数据库端的连接数报警就开始满天飞。后来加上池配置再配合 Vercel 的冷启动逻辑才把问题压下去。5.3 别忘了跑数据库迁移这一点必须单独拎出来强调因为我在不同社区见过太多次求助帖子代码部署了线上数据库表却不一致。Vercel 部署时默认执行的是build脚本如果你没有在postinstall或build里加入prisma migrate deploy或prisma db:push那么线上数据库跟本地开发库的 schema 脱节是迟早的事。create-t3-app 默认模板里通常只会在本地做迁移所以我的习惯是build: prisma generate next build然后在 CI 或本地命令行里规划一个手动执行迁移的步骤生产环境用prisma migrate deploy而不是prisma db:push因为 migrate 会检查和记录迁移历史更安全。5.4 经典报错tRPC 返回 Date 类型时的序列化问题T3 Stack 默认使用superjson作为序列化器它能把Date、Map、URL等复杂类型直接传递到前端。这比 JSON.stringify 强很多但也带来一个小坑如果你用的是自定义序列化器或者某个中间件覆盖了 transformer客户端就可能收到字符串而不是 Date 对象。我在另一个项目里因为引入了自定义 errorFormatter一不小心把 transformer 配置写偏了结果前端拿到的createdAt变成一串 ISO 字符串调试了大半天才定位到问题。这个经验告诉你T3 Stack 自带的最佳实践能别动就别动改之前先想清楚收益到底大不大。6. 组合技再用 TanStack Query 与 NextAuth 扩展一下实战能力基本链路跑通之后一个中型项目的完整形态还差一些补强。t3code 默认已经内置了 TanStack Queryreact-query但很多新手不知道它能干什么。在这里我把实际用到过的几个典型场景列一下。6.1 用 TapQuery 管理缓存与请求生命周期api.post.getAll.useQuery()返回的并不是 tRPC 自己的状态管理而是 TanStack Query 的查询实例。这意味着你可以使用全部 TanStack Query 能力staleTime控制缓存新鲜度避免每次进页面都重新请求enabled条件请求比如需要在用户 id 存在时才拉取数据onError统一错误处理示例const { data } api.post.getAll.useQuery(undefined, { staleTime: 60_000, refetchOnWindowFocus: false, });这个组合在开发体验上是很舒服的。真正生产级应用都天然需要这套机制只是你以前可能没把“REST API useState”的痛苦熬过去没意识到有更舒服的方案。6.2 中间件鉴权让部分页面只能在登录后看到Next.js 的 middleware 可以在请求到达页面之前做拦截。配合 NextAuth可以在src/middleware.ts里写一个很薄的路由守卫export { default } from next-auth/middleware; export const config { matcher: [/admin/:path*, /profile/:path*], };这样写比在每个页面里判断 session 要优雅得多而且在服务端层面完成不会被前端直接绕过。6.3 服务端渲染与 tRPC 并行查询的性能优化当多个 useQuery 并发进行时开发模式没问题但在 SSR 场景下会串行执行浪费不少时间。可以用Promise.all把多个查询合并或者利用页面级createTRPCProxyClient在渲染的同时做好数据适配。这一点可能偏进阶一些但如果你做的是数据密集型的仪表盘页面提升非常明显。官方文档上一段关于 SSR 与 tRPC 的拼接示例值得花时间吃透。7. 我现在的日常选择什么时候继续用 t3code什么时候换方案最后聊点真实的个人体会。跑完这个项目之后我对 T3 Stack 的评价是它不是银弹但在“产品开发效率”这个维度上难找对手。如果你的项目是以下形态可以放心用 t3code内部管理系统 / 后台工具要求快速开发出可用版本全栈一体化的官网/内容站带会员、数据展示、简单多角色权限个人作品集或小团队产品追求可维护性和迭代速度如果你的项目是以下形态建议换个思路开放平台 API需要对外提供官方 REST/GraphQL 接口前后端完全分离的团队结构比如前端组和后端组不共享代码仓库大型单体应用需要独立部署的微服务边界需要多语言、多数据库主从、复杂事务流的大型系统我在实际使用中发现t3code 让人着迷的地方不是“它功能多”而是“它让你少写了一半代码还保住了类型安全”。这一点对一个疲于奔命的开发者来说就是实打实的快乐。不过有几个习惯我还是建议你在项目启动前就养好把业务逻辑放进 tRPC router 里不要散落在组件 effect 里数据库模型优先设计别边写功能边加字段减少后期的迁移连锁反应环境变量一律过env.mjs校验别偷偷在代码里硬编码。整体看下来T3 Stack 本身就是一份很好的全栈开发答卷。你不需要从零造轮子也不需要盲目追逐最新热词。t3code 这个热词能火说明大家确实受够了胶水代码希望用一套省心的组合拳赶紧把产品做出来。你不用全盘照抄它的每一件事但把它的思路吸收进去——尤其是“类型安全全链路”“上下文注入”“接口即函数”这几个设计点放到任何一个技术栈里都能提升一大截开发体验。
阅读完成 · 觉得有帮助？
:比较器电路设计指南)
