T3 Stack 全栈实战：从类型安全到部署性能优化的完整攻略

看到t3code这个名字，很多人第一反应是问我：它到底是个啥？不瞒你说，这是我们团队内部折腾了一个多月的全栈实验项目代号。T3 取的是 T3 Stack 的 T3，code 就是代码工程本身，合起来意思很直白：用 T3 Stack 写一个能真正上线跑业务的中型应用。起因也很简单——团队里有人吹 T3 全家桶"类型安全能省一半联调时间"，有人嗤之以鼻，与其开会吵，不如直接拉一个项目出来实测。一个月后，我们用t3code做出了一个带用户体系、项目管理和部署流水线记录的半生产级应用，也从 65 分的 Lighthouse 优化到了 95 分。这篇文章把整个过程中的选型逻辑、目录改造、tRPC 落地细节、部署阶段踩过的坑、性能优化清单全部摊开写出来。如果你正在犹豫要不要上 T3 Stack，或者用 create-t3-app 搭完项目却不知道怎么往深处改，这篇应该能给你省下不少时间。

1.t3code的选型复盘：T3 Stack 到底解决了什么问题

1.1 为什么非要搞一个实验项目验证

我们团队此前的技术栈处于一个很尴尬的状态：前端是 Next.js，后端是独立的 NestJS 服务，中间靠 REST API 通信。理论上没什么问题，但实际开发中，类型断层带来的成本非常隐蔽。前端调一个接口，得先打开后端 Swagger 文档看字段，再手动在 TypeScript 里定义一遍类型。后端改了字段名，前端那边往往要等联调时才爆出红错，然后两个人开始"翻旧账"：是后端没同步文档，还是前端没更新类型？

一个中型项目六十多个接口，这种对齐成本累积起来非常吓人。t3code这个实验项目的核心目标只有一个：验证"类型从数据库一路通到前端组件"到底能把摩擦降到什么程度。说得直白点，我想知道如果 API 的类型定义不再是手写的，而是自动生成、并且前后端共用一套，那日常开发会变成什么样。

1.2 T3 不是框架，是一套有主见的组合拳

很多人把 T3 Stack 当成一个框架，其实不是。它是一套组件选型的约定，核心由五块拼成：

• Next.js：负责页面渲染、路由、SSR/SSG，以及服务端入口。
• TypeScript：从后到前全链路类型覆盖，这是整套组合的灵魂。
• Tailwind CSS：样式方案，主打原子类和快速迭代。
• tRPC：替代 REST，让前端像调用本地函数一样调用后端逻辑，同时类型自动推导。
• Prisma：ORM，负责数据库访问，并且能从 schema 生成完整的 TypeScript 类型。

这套组合的取舍非常明确：放弃 REST，放弃 GraphQL，放弃手写 API 层，把类型当作唯一的事实来源。它不追求每个环节都用最流行的方案，而是追求"类型在整个链路里不丢失"。比如 Prisma 定义完数据库表结构后，生成的类型可以直接被 tRPC 的 router 使用，tRPC 的返回类型又能被前端自动推导出来，前端组件里写代码时拿到的是编译级提示。这个体验，用过一次基本就回不去。

1.3 和其他方案的对比

在确定技术栈之前，我们其实做了简单对比：

我还测过一个细节：tRPC 的router定义完以后，后端加一个字段，前端代码里立刻就有提示。不需要刷新文档，不需要重新生成 SDK。这种感觉用四个字形容就是"真的通"。当然 tRPC 也有代价，后面部署章节我会详细说——它要求前后端一起部署，适合全栈应用而不是独立微服务。

1.4 我们最终锁定的版本组合

t3code用的是当时最新且验证过稳定性的组合，这组版本在实际开发中没遇到严重兼容问题：

{ "next": "^14.2.10", "react": "^18.3.0", "@prisma/client": "^5.19.0", "@trpc/server": "^10.45.0", "@trpc/client": "^10.45.0", "superjson": "^2.2.1", "zod": "^3.23.0", "tailwindcss": "^3.4.10" }

这里有个经验：不要第一时间冲最新大版本。比如 tRPC v11 出来的时候，对应的 Next.js adapter 方案还在调整，团队如果从零开始，直接上 v11 没问题；但从 v10 迁移要小心。t3code的目标是验证业务价值，不折腾框架，所以选了最稳的组合。如果你是自己个人项目，可以考虑追新；如果是生产项目，稳字当头。

2. 从 create-t3-app 脚手架到t3code：目录改造实录

2.1 脚手架给了什么，我又改了什么

初始化命令很简单：

npm create t3-app@latest

交互式选择完，会拿到一个基础工程。默认带了 Next.js、Tailwind、Prisma、tRPC、NextAuth 的全家桶。但实际写业务之前，我对默认结构做了一番"减法"和"加法"：

• 减掉的：默认的 NextAuth 被我换成了自研 Session 方案。原因是 t3code 需要对接企业微信登录，NextAuth 里写自定义 Provider 也可以，但多一层封装反而麻烦，不如自己写。这里不是否定 NextAuth，如果你做的是常规邮箱密码登录，用它很合适。
• 加上的：引入了src/modules业务域目录。默认脚手架把所有逻辑放在src/server和src/trpc里，项目小还好，一旦业务多就会变成"堆垃圾"。
• 保留的：Prisma 的schema.prisma位置、tRPC 的api/trpc/[trpc]路由入口、superjson 的序列化配置。这三块默认方案已经足够干净，动它们纯属给自己找事。

2.2 trpc 目录结构：三层感知

改造后的关键目录长这样：

src/ ├── app/ │ ├── api/ │ │ └── trpc/ │ │ └── [trpc]/route.ts │ ├── (dashboard)/ │ │ ├── projects/ │ │ └── settings/ ├── modules/ │ ├── auth/ │ │ ├── auth.service.ts │ │ ├── auth.router.ts │ │ └── auth.schema.ts │ ├── project/ │ │ ├── project.service.ts │ │ ├── project.router.ts │ │ └── project.schema.ts ├── server/ │ ├── api/ │ │ └── root.ts │ ├── db.ts │ └── auth.ts ├── trpc/ │ ├── server.ts │ └── client.ts

核心思路是：路由层只做参数校验和组装，业务逻辑下沉到 service。很多初学者把一堆查询写在 router 里，短时间很爽，但 router 文件会迅速膨胀到几百行。t3code 的规则是 router 里只做三件事：从 ctx 拿用户信息、解析输入参数、调用 service 方法。剩下的数据清洗、权限判断、事务控制全部放 service。

2.3 Prisma schema 建模的取舍

t3code核心业务是"用户创建项目，并查看该项目下所有部署记录"。schema 设计上我刻意避开了两个常见坑：

• 不用复合主键。比如projectId + environment这种组合，Prisma 虽然支持，但会导致外键关联和类型生成变复杂，后续写查询时心智负担大。单独加一个id字段成本很低。
• 数据库层面做唯一约束。比如 project 表的slug字段，不仅业务上要唯一，数据库里也必须有@unique。类型系统能帮你拦截一部分错误，但并发场景下唯一约束才是最后防线。

model User { id String @id @default(cuid()) email String @unique name String? projects Project[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Project { id String @id @default(cuid()) slug String @unique name String description String? ownerId String owner User @relation(fields: [ownerId], references: [id], onDelete: Cascade) deployments Deployment[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Deployment { id String @id @default(cuid()) projectId String project Project @relation(fields: [projectId], references: [id], onDelete: Cascade) status DeploymentStatus @default(PENDING) commitSha String? message String? createdAt DateTime @default(now()) } enum DeploymentStatus { PENDING RUNNING SUCCESS FAILED }

每次改 schema 后执行的命令是：

npx prisma migrate dev --name init npx prisma generate

这里有个重要细节：prisma generate必须在代码运行或构建之前执行。很多人部署到服务器上才发现@prisma/client没有生成最新的 client 类型，就是这个原因。CI 流程里记得加这一步。

3. tRPC 类型安全在t3code里的完整闭环

3.1 一次前后端联调的体感对比

tRPC 给人的第一印象是"前端直接调用后端函数"，但它真正值钱的部分，是前后端共享一套类型。拿t3code里最典型的"获取项目列表"接口举例。

服务端 router 定义：

// src/server/api/root.ts import { createTRPCRouter, publicProcedure } from "../trpc"; import { projectRouter } from "../../modules/project/project.router"; export const appRouter = createTRPCRouter({ project: projectRouter, }); export type AppRouter = typeof appRouter;

业务域 router：

// src/modules/project/project.router.ts import { createTRPCRouter, protectedProcedure } from "../../trpc/server"; import { z } from "zod"; import * as projectService from "./project.service"; export const projectRouter = createTRPCRouter({ listMyProjects: protectedProcedure .query(async ({ ctx }) => { return projectService.listProjectsByOwner(ctx.session.userId); }), createProject: protectedProcedure .input(z.object({ name: z.string().min(2), slug: z.string().regex(/^[a-z0-9-]+$/), description: z.string().optional(), })) .mutation(async ({ ctx, input }) => { return projectService.createProject(ctx.session.userId, input); }), });

前端调用：

// src/modules/project/hooks.ts import { api } from "../../trpc/client"; export function useMyProjects() { return api.project.listMyProjects.useQuery(); }

在listMyProjects返回后，前端拿到projects数组，每项都带着id、slug、name、deployments等完整类型。你甚至不需要瞄一眼接口文档，因为编辑器已经告诉你"这里可以传什么、返回什么"。我把这个体验类比成： 以前是快递员把包裹送到小区门口，你得自己下楼拿；现在快递员直接把包裹放到你桌上，而且包装上就写着里面是什么。

3.2 鉴权中间件怎么落地

tRPC 的鉴权是靠procedure.use中间件实现的。t3code里我封装了一个protectedProcedure，所有需要登录的接口都走它：

// src/trpc/server.ts import { initTRPC, TRPCError } from "@trpc/server"; import superjson from "superjson"; import { ZodError } from "zod"; import type { Context } from "./context"; const t = initTRPC.context<Context>().create({ transformer: superjson, errorFormatter({ shape, error }) { if (error.cause instanceof ZodError) { return { ...shape, message: error.cause.issues.map(issue => `${issue.path.join(".")}: ${issue.message}`).join("; "), }; } return shape; }, }); export const createTRPCRouter = t.router; export const publicProcedure = t.procedure; const isAuthed = t.middleware(({ ctx, next }) => { if (!ctx.session?.userId) { throw new TRPCError({ code: "UNAUTHORIZED" }); } return next({ ctx: { ...ctx, session: { userId: ctx.session.userId }, }, }); }); export const protectedProcedure = t.procedure.use(isAuthed);

这个设计的好处是：业务代码里几乎看不到鉴权逻辑。写createProject时，我直接假定ctx.session.userId一定存在，不存在就没法走到这个 procedure。隐患在编译期就被切掉了，而不是运行时才返回 401。真正踩过的坑是 context 类型没写对，ctx.session可能是 null，导致所有 procedure 一进中间件就报错。所以 context 的类型定义要单独抽出来，别在中间文件里随手写。

3.3 错误处理：从 zod 到 TRPCError 的规范化

t3code的错误处理逻辑是这样的：参数层面交给 zod，业务层面交给TRPCError，形成了一套标准化的"用户可读错误"。

比如创建项目时 slug 被占用，service 层直接抛：

throw new TRPCError({ code: "CONFLICT", message: "slug 已被占用，换一个试试", });

前端useMutation里拿到error.message，直接渲染到 UI 上。而 zod 校验失败时，我通过 errorFormatter 把默认的"字段错误列表"拼接成了一行可读的信息。举个例子：输入非法 slug 时，前端弹的提示是slug: 只能包含小写字母、数字和横杠，而不是一串堆栈。

这套配置在开发期和联调期特别省心。以前前后端各猜各的错误码，现在错误信息本身就能作为沟通语言。

4. 从开发机到服务器：t3code部署阶段踩过的坑

4.1 Serverless 环境下的 Prisma 连接

如果只用next dev，Prisma 完全不会出问题。真正让人头疼的是部署。我们一开始把t3code部署到 Serverless 平台，结果线上的 Prisma 报Too many connections。原因不复杂：

Serverless 实例会弹性伸缩，每个实例启动时都会创建自己的数据库连接池。如果平台的单实例内存很小，Prisma 的默认连接池上限会显得格外高。更麻烦的是，冷启动时并发创建多个实例，瞬间把数据库连接数打满。

我的解决思路是按环境分流，本地和服务器用不同的连接策略：

# .env.development DATABASE_URL="postgresql://user:pass@localhost:5432/t3code" # .env.production DATABASE_URL="postgresql://user:pass@host:5432/t3code?connection_limit=1&pool_timeout=10"

重点是生产环境显式降低connection_limit，避免单实例占用过多连接。如果项目数据库是 Postgres，还可以在平台侧配置连接池代理，但那是另一个话题。教训是：上线前一定要压测一下数据库连接数，别等服务告警再改。

4.2 环境变量的分级管理

每个环境的变量都不一样，但t3code早期犯过一个很低级的错误：把DATABASE_URL直接写进了.env，提交到了 git 仓库。直到同事拉了代码，连的是我的本地数据库，才发现问题。

正确的做法是：

• .env.example提交到仓库，里面只写变量名和注释，不写真实值。
• .env.local、.env.production加入.gitignore。
• 部署平台的变量面板统一管理生产环境值。
• 如果有NEXT_PUBLIC_开头的变量，注意它会被打进浏览器 bundle，绝不能放密钥。

这一块多花十分钟整理，后面能少掉很多次"线上环境没生效"的排查。

4.3 tRPC 在 SSR 场景下的 hydration 问题

tRPC 在纯客户端调用没问题，但 SSR 时我们遇到过一个很典型的报错：前端组件拿到的是null，但后端明明返回了数据。排查半天，问题出在 superjson 序列化。

举个例子：Prisma 返回的DateTime字段是Date对象，如果不用 superjson，它会被序列化成 ISO 字符串；用了 superjson，结构变成{ json: ..., meta: ... }。如果 SSR 阶段没有正确经过 tRPC 的 transformer，客户端预取时就会解析失败。

解决方法是确保两端配置一致：

// src/trpc/client.ts import { createTRPCReact } from "@trpc/react-query"; import type { AppRouter } from "../server/api/root"; export const api = createTRPCReact<AppRouter>();

然后在_app.tsx或 App Router 的 provider 里统一 transformer 配置。如果你用 create-t3-app 的默认工程，它已经配好了 superjson，不要在改造过程中动这一块。我们为了"精简依赖"一度把 superjson 移除，结果花了整整一个下午把所有Date类型改成了格式化字符串，最后老老实实加回来。superjson 不是可选项，它是 tRPC 处理复杂类型的基础设施。

5. 性能优化：t3code从 Lighthouse 65 分到 95 分的调整清单

5.1 渲染模型的边界：RSC 和 tRPC 的配合

应用有个明显的性能瓶颈是首屏访问 Dashboard 时，整个列表页面都跑在客户端组件里。这意味着首屏 HTML 几乎是空的，所有内容都要等 JS 加载完再渲染，Lighthouse 的 LCP 直接红标。

优化方式是按"是否需要交互"来拆分：

• 纯展示部分（项目名称、描述、时间）放在服务端组件里，直接用 Prisma 查询，不经过 tRPC。
• 交互部分（创建项目、修改表单、按钮触发的数据变更）放在客户端组件里，走 tRPC。
• 如果必须在一个页面里混合使用，可以用Suspense或组件边界做内容隔离。

这里要澄清一个点：tRPC 不是不能用于服务端组件，而是看数据缓存的时机。Dashboard 的项目列表是"准实时数据"，服务端组件直接查询数据库更直接，还能借用 Next.js 的缓存能力；如果每个区块都走 tRPC 客户端调用，反而多了一层网络往返。

5.2 缓存策略和数据新鲜度

首屏渲染完成后，高危区域是频繁请求导致的白屏和等待。t3code里用了两套缓存策略：

• React Cache + Next.js fetch：服务端组件里复用fetch的缓存标签，项目详情 60 秒内不重复查询数据库。
• tRPC 客户端 query 的 staleTime：列表页的staleTime设为 30 秒，用户切回页面时优先用缓存，后台再静默刷新。体感上几乎不会有 loading 闪烁。

// src/modules/project/hooks.ts import { api } from "../../trpc/client"; export function useMyProjects() { return api.project.listMyProjects.useQuery(undefined, { staleTime: 30_000, }); }

这里有个容易忽略的细节：如果数据更新频率高于缓存时间，用户会看到短暂旧数据。所以在createProject的 mutation 成功后，一定要主动invalidate相关 query：

const utils = api.useUtils(); await utils.project.listMyProjects.invalidate();

5.3 图片、字体和包体积：分数从 70 到 95 的细节

性能优化没有银弹，全是细节叠加。t3code主要做了这几件事：

• 图片全部给足尺寸属性。Next.js 的Image组件如果不给width和height，会自动猜测尺寸，导致 CLS（布局偏移）扣分。项目列表里的部署状态图标原本是 64x64，实际渲染 24x24，浪费了 4 倍流量。
• 字体用next/font。默认system font在部分系统上触发文字重排，换成next/font/google后启用了预加载，CSS 和字体文件都走 CDN。
• 动态导入低频组件。比如创建项目的富文本编辑框，用next/dynamic做客户端懒加载，首屏根本没有它。
• Tailwind 的 purge。Tailwind 3 默认会清除未使用的类名，但如果你动态拼接类名，比如bg-${color}，这类代码会被误删。t3code里统一改成了完整的类名字符串，减少了踩坑。

做完整轮调整之后，Dashboard 首屏从 2.1 秒降到 1.1 秒左右。这不是什么魔法，就是把每个环节的浪费都抠掉一点。

6. 一些个人体感和后续方向

t3code做下来，我最深的感受是：类型安全不是玄学，它确实能显著降低那种"两个人盯着屏幕找字段名"的联调时间。以前一个星期里总有那么两三次因为接口字段对不齐而互相甩锅，现在虽然“甩锅”没有完全消失，但责任边界清晰多了——后端只要保证 router 的类型正确，前端就一定有正确的提示。

但我也必须说清楚它的局限：tRPC 更适合前后端团队合作紧密、共同维护一个仓库的场景。如果你公司前、后端完全分离，前端不能访问后端源码仓库，那 tRPC 的类型共享就无从谈起，这种情况老老实实用 OpenAPI 生成 SDK 可能更现实。另外，Prisma 的 migrate 在复杂数据库变更（比如一次改多个表的关联关系）时容易报错，我的建议是每次 schema 变更前先备份数据，并且把 migrate 文件与代码提交保持同步，不要让人在本地单独执行。

说回t3code这个名字。它从一开始就没打算做成一个公共轮子，更多是团队内部验证技术选型的一次"解剖手术"。但如果你也想在自己的项目里复制这套思路，不必从头搭——直接npm create t3-app@latest，然后把这篇文章里提到的目录拆分、错误处理、缓存策略逐步应用进去，你会得到一套比默认脚手架更贴合业务的全栈工程。项目后续我打算给它加一个独立的 job 队列来处理部署状态回调，让Deployment的status更新不再依赖轮询。等这块做完，有机会再写一篇偏工程实践的拆解。

最后再分享一个和我个人习惯相关的小技巧：t3code里我把所有 Prisma 查询都封装了一层带日志的入口函数，上线初期一旦有慢查询，日志会直接标记超过 300ms 的耗时。这个习惯帮我提前抓住了两个漏掉索引的查询，省了后面生产环境救火的时间。你的项目不一定需要完整的可观测平台，但给数据库操作留一双"眼睛"，任何时候都不亏。