在很长一段时间里，我都是"后端写一套接口文档、前端照着字段对接"的传统开发流，直到接手一个对类型安全要求极高的中台项目，才第一次认真了解 t3code 背后这套 T3 Stack 的完整打法。当时最惊讶的不是它堆了多少新框架，而是从数据库到页面组件，类型居然一路畅通无阻，改了个字段名想让前后端一起报错，它真的就全都给我标红了。这个体验直接改变了我搭全栈应用的思路。这篇文章我把 t3code 相关的技术选型逻辑、完整搭项目的过程、以及中间踩过的几个坑从头讲一遍，适合打算做全栈项目的开发者参考，也适合那些已经听说过 T3 但一直没搞明白它到底解决什么问题的人。
1. t3code 的核心逻辑：把类型安全铺满整个开发链路
1.1 先搞清楚 t3code 到底凑了什么
第一次看到 t3code 这个概念，很多人的反应是"又一个全家桶"。实际上它并不是一个具体的框架，而是一套组合方案，官方叫 T3 Stack。这里的"3"不是三代的意思，而是三门技术刚好都以 T 开头：TypeScript、Tailwind CSS、tRPC。配合最常用的宿主框架 Next.js，再加 Prisma 做 ORM、NextAuth.js 做认证，这就是一套完整的类型安全全栈样板。
- Next.js：承担路由、渲染模式、API 入口，是整套项目的骨架；
- TypeScript：给所有代码加类型约束，但它的价值要在 tRPC 和 Prisma 配合下才真正放大；
- Tailwind CSS：负责样式，不参与业务逻辑，却是 T3 应用很顺手的一部分；
- tRPC：让前后端共享类型，调用 API 像调用本地函数一样，不需要手写接口文档；
- Prisma：数据库模型和查询代码的类型也参与推导。
这里最容易被误解的是 tRPC。它并不是像 REST 或者 GraphQL 那样的网络协议，本质上它是一个 RPC 调用层，客户端通过 tRPC 暴露出来的 hooks 去调用服务端函数，类型定义从前端到后端是天然共享的。你改一个入参类型，前端调用的地方立刻有类型提示，也能直接报错。
1.2 为什么需要"端到端"类型安全，而不是只给后端上 TypeScript
很多项目后端已经是 TypeScript 了，接口层也做了一层类型校验，但前端拿到的仍然是一堆普通 JSON。前端调用时靠的是手动声明的 interface，一旦后端改了字段，前端没同步更新，运行时就会出诡异的 undefined。端到端类型安全解决的恰恰是这个沟通问题：类型是唯一的，没人需要手动维护第二份。
t3code 的实现方式是把服务端的 procedures（tRPC 对接口函数的称呼）作为类型导出，前端通过import type { AppRouter }拿到整个路由的类型结构。React Query 会根据这个类型自动给出每个查询的 data、isLoading、error。
这种设计在多人协作时的价值很大。原来前后端各留一份接口定义，经常出现对不上版本的情况，现在改类型只需要改一处，全项目都会跟着反应。我实际体验下来，TypeScript 报错变多了，但往往不是坏事，错的在编译期就拦下来，而不是等到用户点按钮才报错。
2. 初始化 t3code 项目的完整实操：从脚手架到跑通 Hello World
2.1 create-t3-app 的交互式初始化
T3 官方提供了create-t3-app脚手架，不需要手工集成各种依赖，它会一步一步问你需要的功能模块。我建议第一次用的时候，把 TypeScript、Tailwind CSS、tRPC、Prisma、NextAuth 全部选上，因为后面加模块比一开始多用一点要麻烦得多。
npm create t3-app@latest my-t3-app进入交互式选项后，项目名建议用小写加中划线，避免后续包名解析出问题。选择模块这一步我踩过一个坑：如果你暂时不想要 NextAuth，可以先不选，但数据库建议直接选上 Prisma，因为 tRPC 如果没有任何实际数据读写，很难理解它的价值和数据流动方式。
初始化完成后，目录结构大致如下：
my-t3-app/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ └── root.ts │ │ └── db.ts │ ├── pages/ │ │ ├── api/ │ │ │ └── trpc/[trpc].ts │ │ └── index.tsx │ ├── styles/ │ └── utils/ │ └── api.ts2.2 运行前必须处理的依赖与配置
很多人在npm run dev之后就卡住，因为 Prisma 还没有生成客户端代码。正确的顺序是：
- 先创建
.env文件，把DATABASE_URL配好。T3 默认用 SQLite 最省事，文件路径file:./db.sqlite； - 执行
npx prisma db push同步数据库结构； - 执行
npx prisma generate生成 Prisma Client； - 最后再
npm run dev。
启动之后访问http://localhost:3000，会看到一个默认页面，到这里最基本的链路已经跑通了。
这里有一个非常影响体验的配置：tRPC 的 API 路由文件必须放在src/pages/api/trpc/[trpc].ts，不要自定义路径。如果移了位置，客户端和服务端之间的链接就断开了，控制台会报一个请求返回 404。我一同事当时自定义成src/pages/api/trpc.ts，排查了半天才发现路径不对。
3. 数据库模型与 tRPC Router 联动：核心代码这样写才顺
3.1 Prisma Schema 怎么设计才有扩展性
tRPC 的类型推导能力以数据库模型为基础，所以 schema 设计直接影响前端类型体验。以最经典的 todo 应用为例：
// prisma/schema.prisma generator client { provider = "prisma-client-js" } datasource db { provider = "sqlite" url = env("DATABASE_URL") } model Task { id String @id @default(cuid()) title String completed Boolean @default(false) createdAt DateTime @default(now()) userId String }定义完成后npx prisma db push，数据库的表就创建好了。这里我建议 id 不要用自增整数，用cuid()更方便多实例部署，也能避免前端遍历时把 id 当数字处理的不一致问题。
有了模型，src/server/db.ts里会默认导出一个db实例：
import { PrismaClient } from "@prisma/client"; import { env } from "~/env.mjs"; const globalForPrisma = globalThis as unknown as { prisma: PrismaClient }; export const db = globalForPrisma.prisma ?? new PrismaClient(); if (env.NODE_ENV !== "production") globalForPrisma.prisma = db;这段代码可以在开发热更新时复用同一个 Prisma 实例，避免连接数暴涨。改成生产环境后不会开启全局复用，是符合预期的。
3.2 tRPC Router 的创建与暴露
tRPC Router 是服务端逻辑的入口。T3 默认在src/server/api/root.ts里聚合所有子路由，建议沿用这个习惯，不要把文件拆得太散，先按业务模块分 router，再在 root 里合并：
// src/server/api/root.ts import { createTRPCRouter } from "~/server/api/trpc"; import { taskRouter } from "./routers/task"; export const appRouter = createTRPCRouter({ task: taskRouter, }); export type AppRouter = typeof appRouter;在 task router 里定义查询与变更：
// src/server/api/routers/task.ts import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; export const taskRouter = createTRPCRouter({ getAll: publicProcedure.query(async ({ ctx }) => { return ctx.db.task.findMany({ orderBy: { createdAt: "desc" }, }); }), toggle: publicProcedure .input(z.object({ id: z.string() })) .mutation(async ({ ctx, input }) => { const task = await ctx.db.task.findUnique({ where: { id: input.id } }); if (!task) throw new Error("任务不存在"); return ctx.db.task.update({ where: { id: input.id }, data: { completed: !task.completed }, }); }), });这里的zod是 tRPC 的类型校验库。publicProcedure表示无需登录即可调用，后面接入 NextAuth 后会换成protectedProcedure。这样写的最大好处是：入参校验放在服务端同一处，前端不需要重复写校验逻辑，而前端调用toggle时，IDE 能直接提示需要一个{ id: string }入参。
3.3 为什么 query 和 mutation 要分开，而不是一个函数搞定
新手经常问：增删改查不都是发请求吗，为什么 tRPC 非要分开query和mutation？这背后和 React Query 的设计有关。query是用来获取数据的，结果会被缓存，重复调用时可以直接复用；mutation是改变数据的操作，执行完后通常需要让相关查询失效并重新拉取。
const utils = api.useUtils(); const toggleMutation = api.task.toggle.useMutation({ onSuccess: () => { utils.task.getAll.invalidate(); }, });invalidate会让 React Query 重新拉取getAll，页面数据自动更新，不需要手动 setState。如果把一个写操作定义成 query，数据就永远不会自动刷新，非常容易产生 UI 和数据不一致的问题。
我在项目中最常用到的三段式写法是：
useQuery读数据；useMutation写数据；- 在 mutation 的
onSuccess里 invalidate 相关 query 的缓存。
这套循环写顺手之后，状态管理的负担会小很多，全局 store 也不再是必要选项了。
4. 前端数据消费与页面渲染：tRPC hooks 的实际体验
4.1 写一个完整的双向联动页面
假设要做这样一个页面：展示任务列表，点击按钮切换完成状态，并显示当前未完成数量。前端代码可以直接这样写：
// src/pages/index.tsx import { api } from "~/utils/api"; export default function Home() { const { data: tasks, isLoading } = api.task.getAll.useQuery(); const toggleTask = api.task.toggle.useMutation({ onSuccess: () => { utils.task.getAll.invalidate(); }, }); if (isLoading) return <div>加载中...</div>; const doneCount = tasks?.filter((t) => t.completed).length ?? 0; return ( <main className="mx-auto max-w-xl p-6"> <h1 className="text-2xl font-bold">任务清单</h1> <p className="mt-2 text-gray-600">已完成 {doneCount} 项</p> <ul className="mt-4 space-y-2"> {tasks?.map((task) => ( <li key={task.id} className="flex items-center gap-3 border p-3"> <input type="checkbox" checked={task.completed} onChange={() => toggleTask.mutate({ id: task.id })} /> <span className={task.completed ? "line-through" : ""}> {task.title} </span> </li> ))} </ul> </main> ); }令人舒服的是，tasks里的每一项都带有id、title、completed、createdAt的完整类型提示。即使 Prisma 模型加了一个新字段，前端这里也会立刻出现这个字段的补全。
4.2 处理加载态、错误态和乐观更新的最佳实践
T3 项目里初始代码只显示了数据加载，但真实项目中，加载态和错误态绝对不能少。tRPC 的 hooks 直接返回isLoading、isError、error这几个状态，处理起来非常直观：
if (isError) return <p className="text-red-500">加载失败：{error.message}</p>; const utils = api.useUtils(); const toggleTask = api.task.toggle.useMutation({ onMutate: async (variables) => { // 取消正在进行的查询，避免覆盖乐观更新 await utils.task.getAll.cancel(); const previousData = utils.task.getAll.getData(); utils.task.getAll.setData(undefined, (oldTasks) => oldTasks?.map((task) => task.id === variables.id ? { ...task, completed: !task.completed } : task, ), ); return { previousData }; }, onError: (err, variables, context) => { if (context?.previousData) { utils.task.getAll.setData(undefined, context.previousData); } alert(`操作失败：${err.message}`); }, onSettled: () => { utils.task.getAll.invalidate(); }, });乐观更新的思路是：先立刻更新本地缓存让界面变得很快，请求失败时再把缓存回滚到之前的状态。这种模式在 todo 应用里看起来有点小题大做，但在用户高频率操作的业务场景下体感差异非常明显。我个人强烈建议把这套写法当成基础款来掌握。
4.3 绕开一个让人困惑的坑：ctx 里为什么直接有 db
第一次看 tRPC 代码时，我对ctx.db特别困惑：为什么这个 context 里自动就有数据库实例？这其实是在src/server/api/trpc.ts里显式注入的：
export const createTRPCContext = (opts: CreateNextContextOptions) => { return { db, session: opts.req.session, }; };createTRPCContext返回什么，后续所有 procedure 的ctx里就有什么。想加日志、加请求 ID、加用户上下文，都是往这里加。这是 tRPC 扩展性最强的一个口子。官方默认把session也注入进去，就是故意让你在写业务逻辑时可以方便地读取当前登录用户，而不用每一处都手动处理请求头。
5. 认证状态接入与部署落地：最容易翻车的地方
5.1 把 NextAuth 接进 tRPC 的正确姿势
只做到任务列表这样的 demo 肯定不够，真实项目逃不开登录态。T3 将 NextAuth 预置了进来，默认配置在src/server/auth.ts。
如果是新项目，初始化时建议选择 Discord、GitHub 或者邮箱 Provider 中的一种做测试。核心是把session传给 tRPC 的 context，同时提供一个protectedProcedure：
import { createTRPCRouter, publicProcedure, protectedProcedure } from "~/server/api/trpc"; export const taskRouter = createTRPCRouter({ myTasks: protectedProcedure.query(async ({ ctx }) => { return ctx.db.task.findMany({ where: { userId: ctx.session.user.id }, }); }), });protectedProcedure的实现其实很简单，本质就是在进 handler 之前做一次 session 判断，没登录就直接抛异常。这样前端调用myTasks时，如果未登录会收到一个明确的报错，而不是拿到空洞的数据。
实际配置过程中最常见的坑是NEXTAUTH_SECRET 没配。开发环境可以不配也能跑，但生产环境启动时 NextAuth 会直接报错。部署前记得生成一个随机字符串：
openssl rand -base64 32然后填到环境变量的NEXTAUTH_SECRET里。
5.2 部署时的数据库迁移与连接池问题
本地开发用 SQLite 很省心，但一旦部署到线上，我建议尽快切到 PostgreSQL。T3 官方文档对部署有具体说明，切换的关键步骤是：
- 把
datasource db的 provider 改成postgresql； - 在
.env中把DATABASE_URL换成 PostgreSQL 的连接串； - 执行
npx prisma migrate deploy而不是db push，分别对应生产环境的迁移流程和开发环境的快速同步； - Prisma 到数据库的连接记得开启连接池，连接串添上
?connection_limit=5之类参数，避免 serverless 环境反复创建连接。
这里我踩过一个大坑：在 Vercel 上部署的 Next.js 函数是无状态的，如果DATABASE_URL不带连接池配置，数据库连接数会很快被打满。后来在 Prisma 官方文档里找到方案，用 PgBouncer 或者连接串参数把连接池开起来才解决。这个配置在生产环境是必须的，不然并发一高就崩。
5.3 前后端协同的线上排查经验
tRPC 的报错默认是TRPCClientError，服务端抛出的消息会被安全地遮蔽掉一层，这是为了防止把内部细节泄露给用户。线上排查时，我建议把日志采集做在 tRPC 中间件里，每次请求把 path、耗时、状态码写一条结构化日志。可以用 console 或接入你的日志平台，能大大节省排错时间。
一个常见困惑是：为什么线上 tRPC 报错信息不像本地那么具体？这不是 bug，是默认安全策略。真要看到完整错误，可以在createTRPCClient里配置customFetch，由自己决定哪些 header 与错误需要透传，或者在服务端中间件里把shape的 error 信息替换为内部 logger 记录。不要为了图方便关掉这个遮蔽，线上排错靠日志就好。
6. 关于 t3code 项目结构的整体使用体会
很多人问我，T3 Stack 是不是只适合小项目，或者只适合"什么都用 TypeScript"的团队。我的实际回答是：它更适合那些已经厌倦了重复维护类型定义和接口文档的团队。项目大小不是关键，关键在于你们是不是愿意接受"以类型为准"的开发方式。只要是前后端都愿意用 TypeScript 的项目，这套模式带来的协作收益就会很明显。
如果团队里前端只会 JavaScript，不熟悉 TypeScript，那 T3 的上手曲线会陡一些。相反，如果团队对类型比较敏感，你会发现大部分时间都在写业务逻辑，而不是纠结类型对不对、字段有没有同步。这是一个非常本质的体验差异。
另外再说说测试这件事。tRPC 和 React Query 的可测试性都很好，因为 context 可以被 mock，不需要真的启动一个 HTTP 服务。T3 项目的核心逻辑都集中在 router 层，可以写针对 router 的单元测试，直接通过调用 procedure 的方式验证，不用经过 HTTP。我个人测试下来的效果是：这种测试覆盖的是业务规则，不容易受前端状态影响，比端到端测试稳定得多。
最后分享一个小技巧：很多人刚开始写 tRPC 时，会把所有查询都放在一个大 router 里。我建议按业务域拆 router，再按页面维度拆 selection。不要一上来就做全局缓存策略，先把 React Query 的默认缓存文档读一遍，搞清楚staleTime和gcTime的含义，再结合你的数据刷新频率调整，否则很容易出现"刷新了页面还是旧数据"的困惑。
这篇文章写到的代码和方法，全部都在 T3 的默认约定内，跑通它们不需要额外装太多东西。如果你正在做全栈应用的选型，或者已经在用这套方案但总觉得哪里不顺手，照着上面第七节的思路检查一遍你的数据流，大概率会有收获。
