企业官网建设流程全解析

真正跑完一个基于 T3 Stack 的全栈项目之后，我对“t3code”这个词的理解不再是某个仓库名或者命令行的关键字，而是一种代码的组织方式。简单说，t3code 指的就是以 T3 Stack（Next.js + TypeScript + Tailwind CSS + tRPC + Prisma）为底座的那一整套全栈开发范式——从数据库表结构到页面按钮，自始至终被类型系统串在一起。这篇文章不打算复述官方文档，而是把我亲手搭项目时拆过的轮子、踩过的坑、最后沉淀下来的那套能直接抄的流程写出来，给正在纠结要不要上车，或者已经上车但被各种类型报错折磨得不轻的朋友做个参照。

1. 项目脉络与设计思路拆解

1.1 什么叫“t3code”：一套被类型系统贯穿的全栈写法

T3 Stack 这个名字最初来自 t3.gg 的社区推火，核心就干一件事：用 TypeScript 把从数据库到 UI 整条链路上所有数据流动的类型都变成显式的。传统前后端分离项目里，前端要维护 API 的类型定义，后端要维护接口文档，数据库模型又是另一套关系映射，每一层都有自己的类型世界，对接全靠人肉 review。t3code 的思路是把语言层面的类型系统作为唯一的事实来源，数据库用 Prisma 生成类型，API 层用 tRPC 推导类型，前端组件直接消费这些类型，中间不需要手写一行业务类型的 interface 复制粘贴。

它的关键组合是这五样：

我自己的体会是，这套东西真正厉害的地方不在于某一个工具多强，而在于每一层都舍得把“类型定义”这种活交给工具去生成，人的精力集中在业务逻辑上。

1.2 为什么选这套开发范式：从“对接 API”切换到“调用函数”

做过几年业务开发的应该都有这种经历：后端把 Swagger 文档甩过来，前端照着文档手写 axios 的泛型，接口一变更，前端某个模块就静默地跑到运行时才开始报错。t3code 的体感是完全相反的随着路径——后端定义函数，前端直接按函数去调用，端到端类型安全让很多错误在编译期就被兜住了。

我最初也怀疑这玩意是不是只适合小项目，后来拿一个带权限、分页、关联查询的客户端项目验证完之后，发现它反而在中型项目里收益最大。开发语言统一为 TypeScript 以后，数据库查出来的行类型、传给 rpc 的参数类型、页面里展示的 props 类型，全部可以做到从一个点追溯出来的闭环。

1.3 t3code 适用人群与场景边界

适合用 t3code 的场景非常明确：以 CRUD 为主、表单密集、后台管理系统、内部工具、内容型产品的最小 MVP。只要团队全员 TypeScript 基础在线，这套范式能把开发效率拉到非常高的水平。不太适合的场景是：纯前端项目没有 Node 后端、团队以 Java/Go 为主、需要暴露大而全的公共 API 给第三方用。这类需求下 tRPC 的类型安全优势会被削弱，反而因为 RPC 的私有语义让协作变麻烦。

2. 深入拆解四个核心组件的细节与搭配逻辑

2.1 Next.js App Router 作为应用骨架

在 t3code 项目里，Next.js 不只是“React 框架”，它承担了路由、渲染策略、服务端资源访问三个职责。App Router 下的 Server Component 是默认的页面表现方式，这对 t3code 极其有利，因为 tRPC 的 server caller 可以直接在 Server Component 里用，页面首屏数据完全不用走客户端绕一圈。

实际搭建时我建议直接把app目录当作“页面只有数据索取和 UI 组装”的壳，所有逻辑收敛到server层。比如一份用户列表页：

// app/users/page.tsx import { api } from "~/trpc/server"; export default async function UsersPage() { const users = await api.user.all(); return <UserList initialData={users} />; }

这种写法让页面天然是服务端渲染，前端组件只负责交互增强。客户端组件只保留需要状态和事件的部分，比如表单、弹窗、无限滚动。只要遵循“尽量 Server，必须才 Client”的原则，项目整体性能表现很均衡，不需要额外引入复杂的缓存方案。

2.2 tRPC 为什么能保持端到端类型安全

tRPC 的魔法在于它复用了 TypeScript 的函数签名作为传输协议。后端定义一个 router：

// server/api/routers/user.ts import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; import { z } from "zod"; export const userRouter = createTRPCRouter({ list: publicProcedure.input(z.object({ page: z.number().default(1) })) .query(async ({ ctx, input }) => { return ctx.db.user.findMany({ skip: (input.page - 1) * 10, take: 10 }); }), });

前端引用起来就像调用一个本地函数：

// app/hooks/useUsers.ts import { api } from "~/trpc/react"; export function useUsers(page: number) { return api.user.list.useQuery({ page }); }

具体到请求传输层面，它用TRPCClient把调用信息序列化成 POST JSON，后端通过createContext解开请求注入数据库等依赖，再找到对应 procedure 执行。整个过程没有代码生成步骤，靠的是 TypeScript 的推导全链路。因为类型来自同一份源码，后端改逻辑、前端不需要改类型定义，更不可能出现文档和代码不一致的尴尬。

2.3 Prisma 模型的类型源头地位

Prisma 在 t3code 里不只是 ORM，它负责 schema 定义、数据库迁移、类型生成。大多数时候我们的 schema 一开始不需要建得很完美，按业务直觉把表建出来即可，关键是得尽早跑一次prisma migrate，因为所有下游类型都依赖生成的 Prisma Client 类型。

以一本个人图书管理项目为例，schema 可以写成：

model Book { id String @id @default(cuid()) title String author String pages Int? finished Boolean @default(false) createdAt DateTime @default(now()) ownerId String @map("ownerId") owner User @relation(fields: [ownerId], references: [id], onDelete: Cascade) }

这里的Book类型会直接进入 tRPC 的 query 返回类型链。前端写book.title时甚至不需要翻数据库表结构，编辑器里自动带着字段列表。天坑的地方在于：每当 schema 变过，必须重新跑一次prisma generate，否则 tRPC 的推导会停在旧状态，那种报错非常迷惑，因为代码看起来完全是新的，但类型提示是旧的，看起来就是“明明没错误却编译不通过”。

2.4 Tailwind 在 t3code 里的真实定位

很多人以为 Tailwind 只是“用 class 写样式”偷懒，但在 t3code 里它的意义是让样式不需要离开组件文件。你写一个卡片组件时，直接堆原子类就能完成布局、响应式、暗色模式，不需要去维护 CSS 文件、BEM 命名、样式作用域，这点对全栈开发来说大大减少了“切页面”的上下文切换。

<div className="rounded-xl border border-gray-200 p-4 shadow-sm dark:border-gray-800"> <h3 className="text-lg font-semibold">{book.title}</h3> <p className="text-sm text-gray-500">{book.author}</p> </div>

我的经验是不要把组件拆得特别细，在这套体系下组件之间主要通过 props 传递完整的数据对象类型，而不是一堆分散的原生字段。因为类型都长在同一棵树上，粗粒度地拆组件反而能减少类型推导的开销和心智负担。

3. 从零搭设一套 t3code 的完整实操

3.1 初始化项目：命令与选项

拿到一台干净的电脑，最痛快的方式就是直接用脚手架初始化：

npm create t3-app@latest my-t3code

交互式选择一般我会推荐这样勾选：Next.js 选 App Router，tRPC 和 Prisma 一定选，Authentication 根据项目需求选 NextAuth（新版本可能你更想直接接 Clerk，不过为了少钻研就选 None 也行），Tailwind 是默认勾选的。如果你不想初始化时被繁琐的提示卡住，可以直接加参数：

npm create t3-app@latest my-t3code -- --yes

初始化完成后目录结构是这样：

my-t3code/ ├─ app/ # Next.js 应用路由页面 ├─ components/ # 通用 UI 组件 ├─ server/ │ ├─ api/ # tRPC router 定义区域 │ │ ├─ routers/ # 业务模块按文件拆分 │ │ ├─ root.ts │ │ └─ trpc.ts │ └─ db.ts # Prisma Client 实例 ├─ trpc/ # 客户端/服务端 tRPC 调用封装 ├─ prisma/ │ └─ schema.prisma # 数据模型定义 └─ env.js

这个骨架已经帮你把 tRPC 的 provider、invalidate 工具、server caller 都配置好了，动手前先跑一遍：

npm run dev

如果能打开http://localhost:3000看到那个默认欢迎页，说明地基没问题。

3.2 定义数据库模型并完成首次迁移

假设我们要做的是一个“团队推荐书单”的小应用，含用户、书籍、评分记录三张表。prisma schema 按下面的形式定义：

generator client { provider = "prisma-client-js" } datasource db { provider = "sqlite" url = env("DATABASE_URL") } model User { id String @id @default(cuid()) name String email String @unique books Book[] ratings Rating[] createdAt DateTime @default(now()) } model Book { id String @id @default(cuid()) title String author String pages Int? addedById String addedBy User @relation(fields: [addedById], references: [id], onDelete: Cascade) ratings Rating[] createdAt DateTime @default(now()) } model Rating { id String @id @default(cuid()) score Int comment String? bookId String book Book @relation(fields: [bookId], references: [id], onDelete: Cascade) userId String user User @relation(fields: [userId], references: [id], onDelete: Cascade) createdAt DateTime @default(now()) }

然后执行：

npx prisma migrate dev --name init npx prisma generate

迁移完成之后会自动生成 client 类型，接下来到 tRPC router 里写实际的数据获取逻辑。

3.3 tRPC router 的编写规范：query、mutation 与中间件

在server/api/routers/book.ts里定义书籍相关的 process。比如先定义一个带评分的书籍列表，加上一个添加书籍的 mutation：

import { z } from "zod"; import { createTRPCRouter, protectedProcedure, publicProcedure } from "~/server/api/trpc"; export const bookRouter = createTRPCRouter({ listWithRatings: publicProcedure.query(async ({ ctx }) => { return ctx.db.book.findMany({ include: { ratings: { select: { score: true, comment: true } }, addedBy: { select: { name: true } }, }, orderBy: { createdAt: "desc" }, }); }), add: protectedProcedure .input(z.object({ title: z.string().min(1), author: z.string().min(1), pages: z.number().int().positive().optional() })) .mutation(async ({ ctx, input }) => { return ctx.db.book.create({ data: { title: input.title, author: input.author, pages: input.pages, addedById: ctx.session.user.id, }, }); }), });

这里能看到两个不同 procedure：publicProcedure给所有访问者读公开数据，protectedProcedure则自动检查会话里有没有用户。context 在server/api/trpc.ts中被构造，把 Prisma Client 实例和 session 注入进来。这样处理的好处是权限只管 procedure 这一层，业务函数里不需要反复写认证判断。

3.4 前端调用链路：从 useQuery 到 invalidation

前端页面拿到步骤 3.3 里的缩放类型，直接调用：

"use client"; import { api } from "~/trpc/react"; export function BookList() { const { data: books, isLoading } = api.book.listWithRatings.useQuery(); const addBook = api.book.add.useMutation({ onSuccess: () => { // 让列表自动重新拉取 utils.book.listWithRatings.invalidate(); }, }); if (isLoading) return <p>加载中...</p>; return ( <div> {books?.map((book) => ( <div key={book.id}> <h3>{book.title}</h3> <p>{book.author}</p> </div> ))} </div> ); }

invalidate是 tRPC 里最顺手的刷新机制：执行完 mutation 之后，把相关 query 的缓存标记为过期，然后自动拉新。我建议团队约定所有写操作都要带上对应的 invalidation，否则一多就容易漏掉，页面数据会残留在旧状态。

3.5 服务端调用与页面预取

如果你希望列表第一屏就是服务端渲染的，可以用 tRPC 的 server caller 在 Server Component 里直接取数：

// app/page.tsx import { api } from "~/trpc/server"; export default async function HomePage() { const books = await api.book.listWithRatings(); return <BookList initialData={books} />; }

此时客户端组件BookList接收initialData作为首屏数据，tRPC 会自动 hydration，不会有闪烁与请求重复。这个模式在 t3code 里非常顺滑，几乎每个列表页都值得这么搞，唯一的注意点就是别在 Server Component 里直接调用依赖浏览器状态的操作，比如必须经过登录态保护的 mutation 逻辑，那个还是得放客户端水合完之后再触发。

4. 实战中常见的坑与排查实录

4.1 类型不刷新的幻觉问题

最典型的坑：改了 Prisma schema 加了个字段，npx prisma migrate跑了，prisma generate忘了跑，前端编辑器也提示不了新字段，怎么弄都报类型错。排查路径非常固定：

• 先看node_modules/.prisma/client/index.d.ts里到底有没有新类型
• 没有就重新跑npx prisma generate
• 还有问题就重启 TS Server（VSCode 里TypeScript: Restart TS Server）

这个坑不是代码逻辑问题，是构建管线未刷新类型缓存导致的，看起来神出鬼没，但解法很机械。

4.2 类型推导丢失：input 泛型裸奔

写 tRPC procedure 时，偶尔会把 input 定义得特别宽松，例如：

export const badRouter = createTRPCRouter({ search: publicProcedure.input(z.object({ q: z.string() })).query(...) });

看起来没问题，但如果你在组件里写成api.search.useQuery({ q: "vue" })时，因为 tRPC 的 query 泛型依赖缩窄，偶尔会出现类型推导丢失变成any。解决方案是给createTRPCRouter加一层类型参数明确 router 类型，或者在函数定义处显式标注返回类型。我通常建议在root.ts拼装 router 的时候导出AppRouter类型，前端引用它：

// server/api/root.ts import { bookRouter } from "./routers/book"; import { createTRPCRouter } from "./trpc"; export const appRouter = createTRPCRouter({ book: bookRouter, }); export type AppRouter = typeof appRouter;

客户端trpc/react.ts里的createTRPCReact<AppRouter>()一旦没标注这个泛型，前端调用时类型就会变宽，快速排查方法就是去trpc/react.ts文件看泛型有没有正确传入。

4.3 会话失效带来的 401 误报

protectedProcedure在未登录状态下会直接抛 401。看起来是 tRPC 报错，但很多时候问题出在 NextAuth 的 session 配置上，尤其是数据库存储 session 而不是 JWT 时，如果 session 刷新不及时，刚登录完调用 protected 接口反而 401。这种情况我会先看浏览器网络请求里的 cookie，确认 session cookie 是有效的，再看服务端getServerSession的实现。大部分时候把 NextAuth 的secret配上，并把session: { strategy: "database" }改成用 JWT 能绕开很多诡异问题。

4.4 无限渲染与依赖数组问题

用.useQuery时如果不小心在组件里传了一个内联对象形的 input，比如{ page: 1 }，每次渲染都会生成一个新对象引用，tRPC 内部可能认为参数变化连续发请求。踩过几次坑之后，我把所有 input 都做成了常量或 memo：

const input = useMemo(() => ({ page }), [page]); const { data } = api.book.byPage.useQuery(input);

这种问题在列表分页、筛选条件比较多的时候很容易踩到，诊断方法也简单，看网络请求是不是重复无限发。

4.5 Server Component 里使用 tRPC 的注意事项

在 Server Component 直接用api.book.list()很方便，但如果误把它塞到一个有useState的客户端组件里，就会直接编译报错。另一个闹心点：如果在服务端调用里混入了cookies()读取逻辑，并且浏览器端也尝试走这条路径，会引发 hydration 不匹配，表现为首页偶尔闪一下空白或者样式跳变。我会把服务端取数的逻辑全部收敛到app目录叶子页面，不让组件里再做复杂的服务端取数。

5. t3code 的边界问题与扩展思路

5.1 什么情况下应该放弃 tRPC

t3code 并非银弹。如果你有独立的移动端 App 需要直接访问 API，或者需要给三方开放通用 REST/GraphQL 接口，那 tRPC 的 RPC 语义就对“外部不可见”有了约束。此时更合理的做法是把 t3code 当“内部后台”，再用 Next.js 的 Route Handler 对第三方暴露标准 HTTP API。反正类型安全是在内部跑，对外部接口用 OpenAPI 保持契约，两边可以不冲突，只是代码里会存在两条数据通道，但这比强行让外部适配 tRPC 舒服得多。

5.2 从单机部署到上云：t3code 的部署扩展

把一个小型 t3code 项目从本地跑通到实际部署，比较顺的路线是：数据库不用 SQLite 而是提前切到 Postgres（比如本地用 Docker 起一个），然后部署到 Vercel；如果不想绑 Vercel，也可以用单台 Node 服务器直接跑next start。此时 Vitest 或者 Playwright 这些测试工具可以逐步接进来。因为项目本质就是个 Next.js 全栈应用，部署路径和普通 Next.js 项目没有区别。

值得注意的一点：tRPC 在 serverless 环境下的冷启动会比传统 REST 略高一点点，因为每个请求都要载入整个 router 注册表。如果团队规模不大、流量不大其实不用担心；真到需要优化时，可以考虑把不需要 serverless 的模块做成 Node 长驻服务。

5.3 团队协作时的代码规范沉淀

t3code 项目里协作效率高，很重要的原因是代码结构天然规范。但还需要额外补几条内部约定才能防止 entropy 变高：

• router 文件按业务域拆，不要在一个文件里堆上百个 procedure
• 所有 mutation 的 input 必须用 zod schema 声明，不允许裸类型
• 禁止在客户端组件里直接import { db }访问数据库
• 命名上统一：query 用名词（list, getById），mutation 用动词（add, delete, update）

遵守这些约定之后，新成员上手速度非常快，因为找代码的路径基本可以靠猜：前端想用某个数据，去找对应 router 的同名词条；想加字段，去 schema.prisma 里加，跑一遍迁移，前端立刻就能用。

5.4 进一步打磨：加入缓存与实时能力

t3code 的默认写法是请求走 tRPC，客户端渲染。如果项目开始追求更快的页面响应，可以往两方向扩：一是 Server Component 预取首屏加 ISR，列表页变成静态生成定期刷新；二是接实时能力，在 tRPC router 里增加 subscription，配合pusher或websocket实现评论、通知等场景。这两种扩法都不改变 t3code 的类型安全底座，tRPC 的 subscription 在类型定义上和 query/mutation 几乎一致，上手平滑。

写在最后的体会

我实际用 t3code 写了大概两三个完整项目之后，最大的感受是它把“沟通成本”压缩得很极端：后端不用写接口文档，前端不用关心接口地址前缀，数据库改一张表，整个链路自动感知。前期最需要适应的是“类型无处不在”的思维方式，习惯之后很难退回传统前后端分离的那种开发节奏。如果非要提一条建议，那就是不要急着塞进太多额外抽象，先把 T3 Stack 原生的五个成员用好，等团队对类型链路有了肌肉记忆，再去叠加缓存、消息、CI 之类的复杂能力，这样能尽可能减少踩到“由于过度设计导致的坑”的概率。