这个标题和热词组合有点意思。我在技术社区逛了一圈发现“t3code”近期和全栈 TypeScript 的关系最紧密尤其是指以create-t3-app为核心的 T3 Stack 实践。这套组合在中小型全栈项目里热度一直没降过因为它在“类型安全”这件事上做到了真正的端到端而不是停留在 PPT 层面。我基于自己的实操经验把 T3 Stack 从选型逻辑、项目初始化、核心链路拆解到鉴权、数据库、部署的完整跑通过程整理成文都是可以直接落地的内容看完至少能帮你少踩几天的坑。1. t3code是什么为什么我选择全栈TypeScript这套组合1.1 从“t3”这个代号说起“t3code”对我来说不是某个具体项目名称而是指代围绕 T3 StackTheo 提出的 The T3 Stack展开的一整套编码实践。T3 得名于 Typed类型化、Tailored定制化、Tested可测试三个单词的首字母核心理念是用 TypeScript 贯穿应用的全链路从数据库表结构到浏览器里的 UI 组件类型信息一路传递中间不丢、不靠猜。这对于做全栈应用的团队来说价值非常大后端改了字段类型前端编译期就能看到哪些位置报错不用等到接口联调才发现问题。这套技术栈通常由 Next.js、TypeScript、Tailwind CSS 和 tRPC 四件套组成配合 Prisma 或 Drizzle 这类 ORM 以及 Zod 做数据校验。和我以前习惯的“Vue Express MongoDB”传统分离式架构相比T3 的核心差异是前后端共享类型定义、共享一套代码仓库、共享一套部署链路。用一句话总结它把“前后端联调”这个环节的工作量压缩到了几乎为零。1.2 适合什么样的人和项目如果你的项目属于以下场景T3 Stack 非常合适独立开发者需要快速上线 SaaS 工具或个人作品集不想维护两个独立应用小团队3-10 人做内部管理系统、数据后台、内容工具希望在低成本下保持代码质量现有项目的前后端类型系统完全脱节每次接口变更都要人工对齐文档想学习现代 React 全栈开发但不想被过多的工程化配置淹没如果你做的是需要开放 API 给第三方、多端分离的大型产品或者有独立的前端团队和后端团队、需要各自独立部署那 T3 这种紧耦合模式就不太合适这点后面我会专门展开讲。1.3 我踩过的传统模式之痛在转向 T3 之前我写过不少“React Node 原生接口”的项目。每次加一个字段流程都是改数据库表 - 改后端 DTO - 写接口文档 - 前端复制类型 - 联调时发现字段名拼错 - 再改。这套链路最浪费时间的就是“复制类型”和“对文档”两个环节。而 T3 解决的就是这个核心痛点一切类型由 TypeScript 编译器来保证而不是靠人的记忆力。当然T3 也有学习曲线尤其是 tRPC 的用法和 Next.js App Router 的缓存模型。但一旦过了初期的适应期开发体验确实是一种“回不去”的感觉这也是我非常愿意把完整实践过程写出来分享的原因。2. 四件套的选型逻辑为什么是 Next.js TypeScript Tailwind tRPC2.1 Next.js为什么它成了全栈应用的默认引擎在服务端渲染和全栈框架里Next.js 现在的生态地位基本等同于当年的 PHP——简单、直接、部署方便。T3 选择 Next.js 而不是 ViteExpress 这样的组合核心原因有三个一是 App Router 原生的 Server Components 让数据库查询可以在服务端直接执行不需要单独暴露 HTTP 接口二是部署生态成熟Vercel 一键发布对独立开发者非常友好三是它有一套内在约定文件即路由、服务端优先、流式渲染把很多常见的工程问题都标准化了。和 Remix 相比Next.js 在小到中型项目里会更顺手一些因为 Remix 更强调 Web 标准和渐进增强适合对浏览器原生能力有高要求的场景但开发体验上不如 Next.js“开箱即用”。单从 T3 的搭配逻辑来说Next.js 的作用是提供一个既能跑服务端又能跑客户端的统一运行时让 tRPC 和 TypeScript 可以在这个运行时里无缝工作。2.2 TypeScript不是语言偏好是工程约束如果只选一个 T3 里最不能替换的组件我会选 TypeScript。因为 tRPC 的整个类型安全机制都是建立在 TypeScript 类型系统上的没有 TS 就没有 tRPC 一切好处的根基。T3 里 TypeScript 不只是拿来做类型标注更重要的用法是用它在“数据库 schema 定义层”就建立信任Prisma 的 schema 是源生成的客户端类型自动流向 API 层和 UI 层中间没有手工桥接。实践中我会开启strict模式并且尽量不使用any。为了进一步提升安全性我会配合 Zod 提供运行时校验。TypeScript 是编译期类型Zod 是运行期类型两者双保险。很多初学者会问“有了 TS 为什么还要 Zod”答案是TS 类型在编译后就不存在了而用户提交的数据是真实的运行时事件你总需要一个东西确保“脏数据”进不了数据库。2.3 Tailwind CSS实用主义的高效选择Tailwind 在 T3 里被选为默认样式方案本质上是因为它的“原子类 组合”模式和 T3 的“少写样板代码”哲学一拍即合。以前我写样式是先写 CSS 文件再想 class 命名BEM 命名法经常让我纠结到底叫header__title--active还是title_active。Tailwind 直接让我跳过“命名”这个耗神环节在 JSX 里堆 utility class所见即所得。更关键的是Tailwind 和 React 组件化的思维方式高度契合你可以在组件文件里直接完成结构和样式设计不用来回切换文件。配合apply或者组件封装也能保持样式复用。如果你担心项目后期不好维护可以用 Tailwind 的layer自定义设计系统但大部分中小项目根本到不了那个复杂度。2.4 tRPC替代 REST 和 GraphQL 的第三选择tRPC 是 T3 Stack 最“反直觉”也最核心的一块。它完全绕开 REST 的 URL 设计和 GraphQL 的 schema 定义直接把服务端的函数变成“可被前端调用的过程”。我从 REST 转到 tRPC 时最大的感受是不再需要设计 API 了只需要设计函数。举个例子// server/routers/user.ts import { z } from zod; import { protectedProcedure, router } from ../trpc; export const userRouter router({ getById: protectedProcedure .input(z.object({ id: z.string() })) .query(({ ctx, input }) { return ctx.prisma.user.findUnique({ where: { id: input.id }, }); }), });然后在前端调用import { api } from ~/utils/api; function UserProfile({ id }: { id: string }) { const { data } api.user.getById.useQuery({ id }); return div{data?.name}/div; }用户不存在、参数错误这类问题编译期直接暴露。和 GraphQL 相比tRPC 少了一套 schema DSL不需要 codegen类型直接从 TS 里推断。这在中小型内部项目里效率相差巨大——GraphQL 的类型体操和工具链复杂度对一个小团队来说负担很重。2.5 一次选型对比梳理维度T3 Stack (tRPC Next.js)传统 REST 前端分离GraphQL Apollo类型穿透全链路自动推断手工维护 DTO 与客户端类型依赖 codegen可部分自动联调成本极低高需接口文档中需维护 GraphQL 文档学习曲线中需理解概念低中高schema 设计和缓存策略复杂开放 API 能力弱需额外封装强天然适合强适合复杂查询适合规模1-10 人中小型大型多团队大型复杂聚合场景把这张表刻在脑子里你在做架构选择时就不会再去盲从大厂方案了。3. 从零跑通一个 T3 项目初始化、目录结构与核心代码3.1 环境准备与脚手架初始化我先说环境准备。Node.js 版本建议 20包管理器我用 pnpm因为它的依赖解析速度和磁盘占用比 npm 好很多。如果你本地还没安装 Next.js 相关的全局工具其实都不需要装——create-t3-app会自动处理你只要保证 node 和包管理器可用就行。初始化项目的命令很简单pnpm create t3-applatest my-t3-project执行后 CLI 会问你选哪些技术。我的常规选择是Next.js必选Tailwind CSS必选tRPC必选Prisma比较适合需要关系型数据的业务如果只是简单 KV 场景可以选 DrizzleNextAuth.js等需要鉴权时再选如果项目不需要登录可以先不勾恢复原状保持默认我没勾的是一些比如--no-git之类的选项建议默认初始化。整个脚手架生成时间大约一分钟之后依赖安装可能需要几分钟网速好很快不用急着摸鱼——装完之后你会看到一套带完整类型安全的初始代码。3.2 目录结构拆解每一块都有明确职责初始化完成后进入项目看一眼目录结构理解它的设计逻辑比直接开写重要得多。T3 模板的核心目录如下src/ ├── app/ │ ├── layout.tsx │ ├── page.tsx │ └── api/ │ └── trpc/ │ └── [trpc]/ │ └── route.ts ├── env.js ├── server/ │ ├── api/ │ │ ├── root.ts # 聚合所有 router │ │ ├── routers/ │ │ │ ├── post.ts │ │ │ └── user.ts │ │ └── trpc.ts # tRPC 实例创建 │ ├── auth.ts │ └── db.ts └── utils/ └── api.ts # 前端 hooks 封装app/是 Next.js App Router 的页面层server/是服务端逻辑utils/api.ts是前端调用 tRPC 的桥接。这种“页面写 UI、server 写业务、utils 做桥接”的划分方式帮我省去了很多思考架构的时间模板已经把最佳实践摆在那里是按它的思路走还是另起炉灶我建议前期按模板思路走等熟悉了再按需调整。3.3 从数据库 Schema 到页面渲染一条完整的类型安全链路我以最经典的“博客文章列表”为例完整拆一遍这条链路。第一个文件是 Prisma Schema它定义数据库结构model Post { id String id default(cuid()) title String content String createdAt DateTime default(now()) updatedAt DateTime updatedAt authorId String author User relation(fields: [authorId], references: [id]) }然后运行npx prisma db push同步到数据库再跑一次npx prisma generate生成客户端类型。这里的PrismaClient在src/server/db.ts里实例化全应用共用一个实例。接下来定义 tRPC 路由。注意protectedProcedure和publicProcedure的区别前者会校验 session后者不校验。拿公开查询文章举例// src/server/api/routers/post.ts import { z } from zod; import { createTRPCRouter, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure .query(async ({ ctx }) { const posts await ctx.db.post.findMany({ orderBy: { createdAt: desc }, include: { author: true }, }); return posts; }), byId: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) { return ctx.db.post.findUnique({ where: { id: input.id }, include: { author: true }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1).max(100), 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, }, }); }), });在root.ts里把它挂载到 appRouter// src/server/api/root.ts import { postRouter } from ./routers/post; import { createTRPCRouter } from ./trpc; export const appRouter createTRPCRouter({ post: postRouter, });然后页面组件字段直接通过 tRPC 的 hook 拿数据// src/app/page.tsx import { api } from ~/utils/api; export default function HomePage() { const { data: posts, isLoading } api.post.list.useQuery(); if (isLoading) return div加载中.../div; return ( div {posts?.map((post) ( div key{post.id} h2{post.title}/h2 p{post.content}/p span作者{post.author.name}/span /div ))} /div ); }整个链路里没有任何手工编写的 API 类型文件但posts的数据类型已经精确到 Prisma 模型的每一项了。我当时第一次跑通这个流程时最大的震动就是原来前后端类型共享可以做到这么纯粹。3.4 服务端调用 tRPC 的另一种方式不是所有场景都需要从浏览器发请求。在 Server Component 或 Route Handler 里你不需要走 HTTP 链路直接使用 tRPC 的服务端 caller 方式import { appRouter } from ~/server/api/root; import { createCaller } from ~/server/api/trpc; const caller createCaller(await createTRPCContext()); const posts await caller.post.list();这比从客户端useQuery再等待网络往返要快得多尤其适合服务端渲染 SEO 类页面。记住一个原则能服务端拿数据就服务端拿别让用户白等一次网络请求。4. 实操中最容易踩的坑鉴权、数据库选型与文件上传4.1 鉴权方案Auth.js 在 App Router 下的配置细节T3 模板集成的鉴权默认是 Auth.jsv5Navigation 在任何页面都能拿到 session。但这里有两个容易踩的坑。第一个是环境变量配置登录信息的加密密钥若不符合长度要求应用会启动失败。解决方法是生成一个足够长的随机字符串openssl rand -base64 32然后配置到.env里的相关密钥字段。第二个坑是部署到 Vercel 后如果用了数据库会话别忘记给数据库创建对应的表和字段。看起来简单但我见过很多人在生产环境白屏最后发现是数据库表缺失。如果想用它来实现“用户未登录跳转登录页”你在 Server Component 里这样写import { getServerAuthSession } from ~/server/auth; import { redirect } from next/navigation; export default async function ProtectedPage() { const session await getServerAuthSession(); if (!session) redirect(/login); return div受保护内容/div; }这里有个细节getServerAuthSession依赖auth()函数从 cookies 里解析 session所以它会动态渲染。如果你把它放在了静态渲染页面里Next.js 会提示需要加export const dynamic force-dynamic。不理解 App Router 缓存模型的初学者很容易在这里绕晕。4.2 数据库选型Prisma 与 Drizzle 的取舍很多人在 T3 项目里会纠结 Prisma 还是 Drizzle。我写下我的实际感受。Prisma 的优势是生态成熟、错误提示友好、schema 定义直观适合大多数团队缺点是性能有一定开销复杂查询里会有 SQL 抽象不够灵活的问题。Drizzle 则更贴近原生 SQL更轻量支持服务端组件流式查询但学习成本高一点尤其对于不熟 SQL 的人。我的选型建议是团队熟悉 SQL、追求性能和可定制性选 Drizzle团队希望快速上手、减少心智负担选 Prisma。两者都能在 create-t3-app 里直接勾选模板已经配好了二者的 tRPC 上下文不用额外折腾。4.3 文件上传为什么我建议直接选托管服务T3 Stack 本地跑起来后最容易忽视的文件上传问题。自建内存存储或本地磁盘存储部署到 Vercel 这类 Serverless 环境大概率会失败因为文件系统是非持久的。T3 生态里常搭配的 UploadThing 就是为此设计的它的核心是在上传前先通过路由请求令牌返回带有效期的上传地址前端直接往上传地址写文件拿到回显 URL再交给服务端存数据库。前端接入的代码非常简单核心就两步一是创建上传路由二是在页面组件里使用上传组件。我没法在这里贴出完整第三方 SDK 代码它的配置和版本迭代比较快但思路是稳定的任何上传方案都必须保证“文件存储位置”和“数据库字段”是分离的不要让应用本身依赖本地磁盘。退一步说如果你不想用托管服务也可以把文件转成 base64 存入数据库但那只适用于小型文件且存取开销很大不推荐在生产环境使用。5. 性能优化与部署从本地到生产的一次完整记录5.1 React Server Components 带来的结构性优化T3 默认搭载的 Next.js App Router 让 RSC 成为默认方案。RSC 让我们可以把查询逻辑放在服务端只把渲染结果发给客户端。比如上面的文章列表页如果用客户端渲染要发请求、等 loading但用服务端组件直查数据库页面首次加载几乎没有空白期。RSC 对 bundle 体积的改善也很明显服务端组件不会打进浏览器 JS因此大型页面里可以避免牵扯很多依赖。虽然这点对开发体验没有直接变化但 Lighthouse 分数会让人放心很多。5.2 缓存模型Router Cache 与数据更新的博弈App Router 引入了一个新问题数据更新后页面什么时候才重新渲染Next.js 会在用户导航时缓存路由组件如果只是数据变了但路由没变页面可能不会拉取新数据。解决这个问题的标准做法是在 mutation 成功后调用revalidatePath()或router.refresh()。在 tRPC mutation 里这样处理import { revalidatePath } from next/cache; createPost: protectedProcedure .input(...) .mutation(async ({ ctx, input }) { const post await ctx.db.post.create({ data: input }); revalidatePath(/); return post; })还有个细节如果在 Client Component 里调用useMutationmutation 完成后调一次utils.post.list.invalidate()是最佳的刷新方案。T3 模板里会自动生成基于 tRPC 的工具 API封装了 queryClient 的失效重新取数逻辑比router.refresh()更精确、更快。5.3 部署到 Vercel环境变量与迁移脚本部署流程比较简单推 GitHub 仓库连接 Vercel 导入项目填环境变量点部署。但我见过的部署失败大部分都出在环境变量和数据库连接上本地.env里的密钥没有拷贝到 Vercel数据库连接串没加sslmoderequire或者 Prisma 迁移没有执行。实际操作时我在 Vercel 的 Build Command 里会加prisma db push next buildP 到外部托管数据库时使用确保每次部署前先同步数据库结构。但团队协作的场景更建议用prisma migrate deploy避免误操作导致结构漂移。这个差异建议按照“独立项目 vs 团队项目”来选择。5.4 避免 Serverless 下的常见连接池问题Serverless 环境每个请求可能都是独立实例PrismaClient 如果每次请求都新建会出现连接数打满的问题。T3 模板在src/server/db.ts里已经做了全局单例处理用globalThis.prisma缓存实例。这种代码不值得自己去想“怎么连接数据库”照着模板用就行。如果你用的是 Drizzle也一样有推荐的连接管理方案跟着官方文档配置即可。6. 只有实际用过才知道的心得T3 的边界与使用建议6.1 T3 不适合所有项目这并不可耻我见过很多团队被 T3 的“全栈少配置”吸引把它用在大型开放平台上结果发现 tRPC 对第三方 API 集成支持很弱、需要频繁写额外的 HTTP 封装层。T3 的适用场景是“你既是前端又是后端”的内部应用、工具类产品而不是公共服务 API。判断标准很简单如果前端的每一个数据调用都来自你自己写的页面T3 很合适如果外部系统要按 REST 或 GraphQL 来访问你的接口就换个方案。6.2 团队协作里最有价值的是类型公约T3 带来的类型安全在个人项目里只是“很爽”在多人协作里则是“省大量时间和口水”。以往联调时最常见的“字段名大小写不一致”“时间字段格式不统一”“分页参数叫 page 还是 offset”这类纠纷在 T3 里会直接消失。后端定义了 input schema前端调用直接能看到参数结构数据库返回字段类型不匹配前端编译期就红波浪线。这种约束比代码规范文档有效得多因为它是编译器强制执行的。6.3 学习路线建议如果你想快速上手 T3我建议按这个顺序来先跑一遍create-t3-app默认模板的 README搞懂目录结构然后自己写一个小 CRUD比如待办清单或博客熟悉 Prisma schema、tRPC router、useQuery/useMutation 三件套接着加一个鉴权流程理解 session 和 protectedProcedure最后部署上 Vercel把环境变量和数据库迁移跑通。整个过程大概两三个晚上能完成之后你再回头看它带来的价值会比在这里读十遍文章都更直观。6.4 一个小技巧善用模板里的类型工具T3 还提供了一些很好用的类型辅助比如从appRouter中直接反推某个 Procedure 的输入输出类型import type { RouterOutputs } from ~/utils/api; type PostListOutput RouterOutputs[post][list];这在封装可复用的展示组件时特别方便。不用手动 import 每个数据模型直接从路由输出类型拿能少写很多没必要的 interface。从我个人的长期使用体验来看T3 Stack 最大的价值不是它长得有多“酷”而是它把全栈开发中最耗时、最不出彩、最容错率高的“类型对接”环节用工程化手段降到了极低的成本。对于独立开发者和小团队这套组合的投入产出比非常高。如果你正在犹豫要不要入坑我的建议是拿一个小项目先试水跑完一轮 CRUD、鉴权和部署之后你自然能判断它是不是你的菜。