用T3 Stack构建全栈应用：从类型安全到部署实战

最近一直在折腾一个代号叫 t3code 的项目。说直白点，这就是一个用 T3 Stack 从零搭起来的全栈 Web 应用，核心是把 TypeScript 的类型安全从数据库一路贯穿到前端界面。过去做全栈开发时，我经常遇到前后端类型不同步导致的低级 Bug，比如前端用了post.createAt，后端字段实际叫post.createdAt，编译时没人提醒，跑到页面上一片 undefined。t3code 想解决的，就是这个“类型失联”的问题。如果你已经会用 React，但对全栈应用的工程化组织、类型设计、数据流这些还处于“知道但没亲手搭过”的状态，这篇文章应该能让你少走不少弯路。接下来我会把 t3code 从技术选型到部署上线的完整过程，包括每一步为什么这么做、踩过什么坑，一次性讲透。

1. T3Code是什么？为什么T3 Stack值得搞一套全栈项目

1.1 T3 Stack到底是什么：四个工具拼出的组合拳

T3 Stack 并不是什么新框架，它更像是一套被反复验证过的技术栈模板。它的主力工具是四个：Next.js、TypeScript、Tailwind CSS、tRPC。Next.js 负责应用框架和渲染策略，TypeScript 给全栈代码提供静态类型，Tailwind CSS 负责样式，而 tRPC 则把前后端的接口调用变成了“像调用本地函数一样”的类型安全过程。如果往下扩展，通常还会加入 Prisma 做数据库 ORM、NextAuth 做登录鉴权，总共不过六七个工具包，却能覆盖一个现代应用从页面到数据库的所有环节。

很多人第一次听到这套组合时会觉得“又是弄一个新概念”，但实际使用后你会发现，它的核心思路非常朴素：把“类型安全”当成第一优先级。以前写全栈项目，前端要把接口返回的数据手动定义成 interface，后端也要维护同名的类型，两边一旦有人忘记同步，脏数据和运行时崩溃就来了。tRPC 的妙处在于，后端函数的输入输出类型可以自动被前端推导，前端调用trpc.post.list()时，拿到的数据类型就是后端函数返回值的真实类型，中间没有任何手写拷贝。

我自己的类比是，以前两个同事合作，A 负责写需求，B 负责实现，靠一份口头描述和聊天记录互相猜。T3 Stack 相当于两个人打开同一个共享文档，A 改了字段名，B 的编译器立刻会跳出来提示“你这里还引用旧的字段”。这种体验在 t3code 里感受特别明显，尤其是项目从几百行涨到几千行时，类型系统帮我挡掉了大量本会在联调阶段才暴露的问题。

1.2 技术选型：为什么我没有选择REST或GraphQL

在定 t3code 的技术路线之前，我其实认真考虑过几组替代方案。第一组是“Next.js + REST API”，也就是所有交互都靠手写 fetch 请求。REST 的好处是直观，每个接口就是一个 URL，但坏处也很明显：接口路径、请求参数、响应结构的约定全部靠人肉维持，前端每个模块都要自己定义返回类型，后端一旦加字段，前端容易不知不觉漏掉。对单仓全栈项目来说，这属于“简单但粘稠”的方案。

第二组是 GraphQL。GraphQL 的类型系统确实强，配合 codegen 也能自动生成前端类型，但它需要额外维护 schema、resolver、query fragments 这一整套东西，工具链复杂度会明显上升。对于一个以“快速迭代、保持类型安全”为目标的全栈应用来说，GraphQL 不是不行，而是有点杀鸡用牛刀。反观 tRPC，它不需要定义独立 schema，后端函数签名本身就是协议，前端调用时类型自动对齐。我把三组方案放在一起对比了一下：

这个表格不是说某一种技术绝对差，而是选型必须结合项目形态。t3code 是典型的同仓库全栈应用，绝大部分接口只给自家前端用，tRPC 自然是最顺手的方案。需要对外提供接口时，再在 Next.js 的 Route Handler 里单独写 REST 也不迟，两者并不冲突。

2. 从零搭起T3Code：项目架构与核心设计拆解

2.1 目录结构设计：先搞清楚东西往哪放

很多新手拿到 create-t3-app 生成的模板后，第一反应是“文件夹怎么这么多”，然后顺手把代码到处乱塞。我建议在写业务之前，先把目录边界划清楚。t3code 的核心目录结构是这样：

prisma/ schema.prisma src/ app/ page.tsx layout.tsx api/trpc/[trpc]/route.ts server/ api/ root.ts trpc.ts routers/ post.ts db.ts auth.ts trpc/ react.ts server.ts env.js tailwind.config.ts next.config.mjs

src/app放路由页面，src/server/api/routers放按业务模块拆分的 tRPC 路由，src/server/db.ts负责统一导出 Prisma 客户端，src/env.js负责启动时校验环境变量。这个分层的意义在于数据流可追踪：页面组件要么在服务端直接访问db，要么通过trpc调用路由；路由再访问数据库；业务逻辑和页面渲染互不污染。

拿 t3code 里的“文章列表”来举例，如果页面偏展示、需要 SEO，我会在 Server Component 里直接用 Prisma 查数据，渲染成 HTML 返回。如果用户要提交表单、点赞、删除，就通过 tRPC 的 mutation 走一遍权限校验和输入校验。这种“两条腿走路”看起来很基础，但能避免一个常见误区：把所有数据请求都发给客户端，导致明明可以做 SSR 的页面变成一串 loading 骨架。

2.2 tRPC + Prisma 联动：类型安全是怎么贯穿全栈的

类型安全能贯穿全栈，依赖的是 TypeScript 的类型推导链路。数据库表的结构由 Prisma Schema 描述，运行时生成类型定义；Prisma 返回的数据类型是强类型的；tRPC 函数的参数和返回值又基于这些类型。所以只要从底层把类型定义好，上层想出错都难。

我在 t3code 里定义了一个简单的 Post 模型：

model Post { id String @id @default(cuid()) title String content String published Boolean @default(false) authorId String createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

定义完 schema 后执行npx prisma migrate dev --name init，再跑一次npx prisma generate，Prisma 就会生成一整套类型。接下来在 tRPC 路由里写一个查询逻辑：

import { z } from "zod"; import { createTRPCRouter, protectedProcedure, publicProcedure } from "~/server/api/trpc"; export const postRouter = createTRPCRouter({ list: publicProcedure.query(({ ctx }) => { return ctx.db.post.findMany({ orderBy: { createdAt: "desc" }, select: { id: true, title: true, content: true, createdAt: true, }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1), 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, }, }); }), });

这段代码里有两个细节值得展开。第一，list查询是publicProcedure，不需要登录就能读；create是protectedProcedure，未登录用户会被拦截，这和“前端隐藏按钮”是两码事，权限必须放在服务端。第二，入参用了 Zod，运行时校验和类型推断同时存在，前端传一个缺失字段，请求在进业务逻辑之前就会报错，脏数据没法入库。

前端调用时，只需要这么写：

"use client"; import { trpc } from "~/trpc/react"; export function PostList() { const { data, isLoading, error } = trpc.post.list.useQuery(); if (isLoading) return <p>加载中...</p>; if (error) return <p>{error.message}</p>; return ( <ul> {data?.map((post) => ( <li key={post.id}> <h2>{post.title}</h2> <p>{post.content}</p> </li> ))} </ul> ); }

trpc.post.list.useQuery()返回的数据类型，和你后端findMany的select字段完全一致。改后端字段时，如果前端还引用旧的字段名，TypeScript 在编译阶段就能发现。这个能力我不常吹嘘，但它是 t3code 里最让人安心的地方。

2.3 Tailwind定制：用设计令牌统一t3code的视觉风格

样式部分，我坚持用 Tailwind，而不是 CSS Modules 或原生 CSS，核心原因是设计约束。Tailwind 的默认色板、间距刻度、字号体系天然构成一套“设计令牌”，你会在写类名时被迫在有限的选项里选值，而不是随手写一个#f2f3f5。这样做了三个月之后回头看，全站的颜色和视觉节奏会比较统一。

t3code 里我在tailwind.config.ts中扩展了主题，把品牌色、成功色和圆角统一定义：

import type { Config } from "tailwindcss"; export default { darkMode: ["class"], content: ["./src/**/*.{ts,tsx}"], theme: { extend: { colors: { brand: { 50: "#eef2ff", 500: "#6366f1", 700: "#4338ca", }, }, borderRadius: { xl: "0.75rem", }, }, }, plugins: [], } satisfies Config;

另外我的经验是，不要在页面里直接堆几十个 Tailwind 类名，尤其是同一个视觉组件被复用四五次时。合理的做法是抽成 React 组件，比如Card、Button、Badge，把类名收敛到组件内部。这样既保留 Tailwind 的自由度，又不会让业务页面变成“类名糊墙”。如果你想要更现成的组件集合，可以试试 shadcn/ui，它本身就是基于 Tailwind 和 Radix 的，和 T3 生态衔接非常顺。

3. 实操实录：T3Code核心功能一步步做出来

3.1 初始化脚手架：10分钟跑起开发环境

t3code 的起点是官方脚手架create-t3-app。命令行执行直接创建一个叫 t3code 的项目：

npm create t3-app@latest t3code

交互式命令行里会让你勾选要使用的工具。我的建议是：第一，TypeScript、Next.js、Tailwind CSS、tRPC、Prisma 都勾上；第二，路由方式选择 App Router；第三，如果你暂时还不想折腾登录鉴权，可以先不勾 NextAuth，但这里我建议还是勾上，因为后面protectedProcedure会用到。项目生成后，第一件事不是急着写代码，而是把环境变量配置好。create-t3-app会生成一个.env，本地开发我把数据库临时指向 SQLite：

DATABASE_URL="file:./dev.db" NEXTAUTH_SECRET="随便生成一个长随机字符串" NEXTAUTH_URL="http://localhost:3000"

之后执行初始化迁移：

npx prisma migrate dev --name init npx prisma generate npm run dev

打开http://localhost:3000，脚手架自带一个演示首页，说明环境已经通了。本地用 SQLite 最大的好处是零成本，不需要开容器、不需要连接远程数据库。当然 SQLite 只适合开发和演示，真正部署时我会切到 Postgres，后面会专门讲。

3.2 实现文章发布与列表：一次完整的tRPC流程

搭好基础设施后，我拿 t3code 的“文章系统”来练手。这能完整覆盖 Prisma schema、tRPC query/mutation、客户端 hooks 的核心流程。

先在prisma/schema.prisma中加 Post 模型，执行迁移和 generate。然后创建src/server/api/routers/post.ts，写入前面贴过的那段postRouter代码。最后在src/server/api/root.ts里把子路由挂到根路由上：

import { postRouter } from "~/server/api/routers/post"; import { createTRPCRouter } from "~/server/api/trpc"; export const appRouter = createTRPCRouter({ post: postRouter, });

前端这边，我写了一个发布表单组件：

"use client"; import { useState } from "react"; import { trpc } from "~/trpc/react"; export function PostForm() { const utils = trpc.useUtils(); const [title, setTitle] = useState(""); const [content, setContent] = useState(""); const createPost = trpc.post.create.useMutation({ onSuccess: () => { setTitle(""); setContent(""); utils.post.list.invalidate(); }, }); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); createPost.mutate({ title, content }); }; return ( <form onSubmit={handleSubmit} className="space-y-4"> <input value={title} onChange={(e) => setTitle(e.target.value)} placeholder="标题" required /> <textarea value={content} onChange={(e) => setContent(e.target.value)} placeholder="内容" required /> <button type="submit" disabled={createPost.isPending}> {createPost.isPending ? "发布中..." : "发布"} </button> </form> ); }

这里的关键一步是utils.post.list.invalidate()，它会让 tRPC 自动重新拉取文章列表数据，不需要手动刷新页面。很多新手会纠结“提交成功后怎么刷新”，tRPC 的写法就是 clear query 缓存，让列表重新执行一遍list。另一个细节是createPost.isPending，它在 mutation 过程中给按钮加一个禁用状态，避免用户连续点击重复发布。

有一个常见的坑：后端返回的createdAt在序列化之后可能从 Date 对象变成 ISO 字符串。前端如果直接写post.createdAt.toLocaleDateString()，运行时就会报toLocaleDateString is not a function。稳妥的做法是在渲染之前先new Date(post.createdAt)再格式化，或者统一用 dayjs 这类库处理。这类问题不会在编译期暴露，只能靠经验提前绕开。

3.3 SSR页面实践：怎么样又快又稳

t3code 的文章列表页面，我用了 Next.js App Router 的 Server Component 来做首屏渲染。这样最大的好处是用户最先看到的不是空白页或 loading 圈，而是已经渲染好的 HTML，对 SEO 和首屏时间都有帮助。

import { db } from "~/server/db"; export default async function HomePage() { const posts = await db.post.findMany({ orderBy: { createdAt: "desc" }, take: 20, }); return ( <main className="mx-auto max-w-3xl px-4 py-12"> <h1 className="text-3xl font-semibold">t3code 最新文章</h1> <div className="mt-8 space-y-6"> {posts.map((post) => ( <article key={post.id}> <h2>{post.title}</h2> <p>{post.content}</p> </article> ))} </div> </main> ); }

这段代码的本质是：在服务器端拿到数据库数据，直接渲染成 HTML 响应给浏览器。它不经过客户端的 fetch，也不需要useQuery。很多初学者会混淆一个概念：既然有 tRPC，为什么还要直接访问db？我的取舍标准很简单——如果这段数据纯粹用于服务端渲染、不需要用户操作，直接查库；如果涉及用户身份、权限、实时更新，走 tRPC。两种方式在 t3code 里并存，不冲突。

需要特别注意的是，Server Components 里不能直接调用 tRPC 的useQueryhooks，因为那些 hooks 依赖客户端运行时。如果非要在服务端调用 tRPC，可以用createCaller生成一个 server caller，但大多数“纯展示”场景直接用 Prisma 反而更简单，没必要绕一层。

3.4 部署上Vercel：从本地SQLite切换到Postgres

在本地开发阶段，SQLite 足够用，但部署到 Vercel 这种 Serverless 平台时必须切到 Postgres。原因很简单：Serverless 函数每次执行都可能在不同的实例上，SQLite 这种本地文件数据库没法跨实例持久化，数据会丢失或错乱。我选用了 Neon 的免费 Postgres，因为它提供 Serverless 访问方式，延时相对可控。

切换步骤并不复杂。先在 Neon 后台创建一个 project，拿到连接串，然后修改.env：

DATABASE_URL="postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/t3code?sslmode=require"

需要执行一次数据库迁移，让 Postgres 实例里创建对应的表：

npx prisma migrate deploy

然后把项目推到 GitHub，在 Vercel 里导入仓库。环境变量在 Vercel 的 Project Settings 里逐个添加，DATABASE_URL、NEXTAUTH_URL、NEXTAUTH_SECRET一个都不能少。Build Command 一般不用动，create-t3-app 的默认配置已经处理好了，但如果构建日志里出现PrismaClientInitializationError，大概率就是DATABASE_URL没配好。

部署成功之后，别忘了把本地 SQLite 里的演示数据清一清，因为生产库和开发库是两套数据。如果以后想在上面加后台管理，直接在src/app/admin下新建页面，权限校验用protectedProcedure或服务端 session 判断都可以，整个架构还能继续扩展。

4. 踩过的坑与排查技巧：T3Code实战答疑

4.1 常见错误速查表：从报错信息看问题根源

开发 t3code 的过程中，很多报错都极其相似，光靠记忆容易混淆。我整理了一张速查表，把最常见的现象和处理思路放一起：

这里我要特别提一下 Zod 校验导致 400 的情况。tRPC 的input校验失败时，返回的错误信息往往是一个很长的聚合字符串，新手很容易只看到“400”就以为网络问题。实际上只要点开 Vercel 或本地终端里的日志，就能看到具体是哪个字段缺失、哪个字段类型不匹配。解决问题的关键是“先看完整报错，再改代码”，不要凭感觉猜。

4.2 性能优化与调试：N+1、缓存和日志那些事

t3code 进入功能迭代后，我开始关注性能问题。第一个容易踩的是 ORM 的 N+1 查询。比如文章列表需要展示作者头像，如果在遍历每篇文章时单独查一次作者，数据量一大就慢得明显。Prisma 里比较好的做法是用include或select把关联数据一次性取出：

await ctx.db.post.findMany({ include: { author: { select: { name: true, image: true }, }, }, });

第二个建议是给 React Server Components 加缓存。Next.js 的cache函数可以避免同一个请求里重复查库：

import { cache } from "react"; import { db } from "~/server/db"; export const getLatestPosts = cache(() => { return db.post.findMany({ orderBy: { createdAt: "desc" } }); });

在同一个渲染流程中，多个组件同时调用getLatestPosts()时只会触发一次数据库查询，这能明显减少 Serverless 环境的数据库压力。

调试方面，我习惯给 tRPC 加一个日志中间件。在src/server/api/trpc.ts里包裹一层middleware，把每次请求的路径和耗时打印出来：

export const createTRPCRouter = t.router; const loggerMiddleware = t.middleware(async ({ path, type, next }) => { const start = Date.now(); const result = await next(); console.log(`${type} ${path} - ${Date.now() - start}ms`); return result; }); export const publicProcedure = t.procedure.use(loggerMiddleware);

这个日志在开发环境特别有用。接口慢了、报错了，一眼就能看出是哪条路径、哪个调用出的问题，省得在客户端和数据库之间来回猜。

4.3 几个值得长期坚持的开发习惯

最后聊几个我在 t3code 里养成的开发习惯。第一条，改完 Prisma schema 后立刻执行prisma generate，不要让编辑器带着旧类型运行。第二条，环境变量只在.env里写，同时维护一个.env.example记录所有变量名，方便新同事或未来的自己快速复原环境。第三条，tRPC router 按业务模块拆分，不要把 post、user、order 的逻辑全部堆在一个文件里，否则文件膨胀后几乎没法维护。

还有一条很重要：写组件前先想清楚它应该是 Server Component 还是 Client Component。不要顺手就在每个组件顶部加"use client"。t3code 里大部分纯展示组件其实都用不到客户端状态，加了反而损失 SSR 性能，还可能在 hydration 时出现序列化不一致的报错。我自己吃了好几次亏之后，现在都是先问一句：“这个组件需要用户交互吗？需要浏览器 API 吗？如果都不需要，它就没资格带use client。”

Zod 输入校验也是一样，不要因为前端已经做了表单校验，就省略服务端校验。攻击者完全可以绕过你的前端直接调接口，服务端不做校验就等于把数据库暴露在不可信的数据面前。t3code 的protectedProcedure加input(z.object(...))这套组合，就是最简单的双保险。

我个人在实际折腾 t3code 的过程中，最大的体会是“类型安全”不是一个口号，它是可以落到每一个函数签名上的收益。改字段、加接口、重构组件时，编译器替我抓出了大量低级错误，这让我敢于在架构上做更大胆的调整。如果你也想搭一个类似的项目，建议按这个顺序走一遍：先用 create-t3-app 生成基础骨架，然后实现一个带 Prisma model、tRPC query、mutation、页面渲染的完整小功能，再部署一次试试。等你跑通这一套，后面再扩展登录鉴权、支付回调、后台管理，都会是非常自然的事情。最后再提醒一句，开发时随手把报错信息完整记录下来，很多坑你只需要踩一次，就能成为后面调试的“速查手册”。