企业官网建设流程全解析

如果你最近一两年混迹在 Web 开发相关的技术社区，肯定见过 t3code 这个词。它不是某个具体的开源库，而是对一个全栈技术方案的代称，背后是一套以 TypeScript 为绝对主线的 React 全栈架构——Next.js + TypeScript + Tailwind CSS + tRPC + Prisma + NextAuth.js，也就是大家常说的 T3 Stack。这套组合自打出现之后就迅速在独立开发者、中小型团队和个人项目圈子里火了起来，几乎成了“端到端类型安全”的代名词。

我第一次看到 T3 架构是在一个独立开发者分享自己 SaaS 项目技术选型的帖子里。当时最打动我的不是某个组件有多强，而是它的整体设计思路：每一个库只专注做好一件事，然后用 TypeScript 把它们像榫卯一样严丝合缝地扣在一起。你写前端时能拿到后端的类型，写后端时能直接调用数据库模型，CRUD 接口不再需要单独维护和两边对接——那种“一处改动、全链路跟着变”的体验，对长期维护一个中大型应用的人来说，诱惑力几乎是致命的。

这篇文章我会从整套方案的设计思路讲起，拆开每个组件的职责和选择理由，再带你把一个完整的任务管理 Demo 从零搭出来，最后讲讲我在实际项目中踩过的坑。无论你是刚想了解 T3 生态的新手，还是已经在用但想优化细节的老手，这篇都值得花十分钟读一遍。

1. 内容整体设计与思路拆解：T3 到底在解决什么问题

1.1 为什么是这六个组件，而不是一个大而全的框架

传统全栈开发最让人头疼的，就是前后端之间的类型断层。前端写fetch('/api/users')，后端返回什么全靠猜；后端改了个字段名，前端一编译才发现一堆undefined。T3 的思路不一样：它不做一个包揽一切的巨型框架，而是选择六个各司其职的库，用 TypeScript 把它们“绑”在一起。

• Next.js：应用框架，负责页面渲染、路由和 API 层承载。App Router 模式下天然支持 Server Component，正好和 tRPC 在服务端的执行方式互相配合。
• TypeScript：整个方案的类型基础。没有它，后面所有“从数据库到 UI 全链路带类型”的体验都无从谈起。
• Tailwind CSS：原子化样式方案。不强制 UI 组件的层叠结构，和 React 组件的组合模式非常搭。
• tRPC：远程过程调用库。不需要写 REST 路由和接口文档，前端直接“调用”后端函数，类型自动从服务端传到客户端。
• Prisma：ORM 和数据库迁移工具。用 Schema 定义数据模型，自动生成类型安全的查询客户端。
• NextAuth.js：认证解决方案。支持 GitHub、Google、邮箱等多种登录方式，和 Prisma 的 Session 模型能直接对接。

这六个组件不是随便拼的。它们有一个共同点：全部围绕“类型安全”这个核心展开。换句话说，T3 想让你的整个应用——从前端事件处理、后端逻辑、数据库查询到用户身份——都处于同一个类型系统之下。

1.2 端到端类型安全的价值：告别“接口文档焦虑症”

很多人在中小型项目里不用全套 T3，主要原因是觉得“Java 那套接口定义 + Controller 的写法我也熟了，何必折腾 tRPC”。但真正体验过 T3 之后，你会发现它解决的其实不只是“少写几个接口”的问题。

以我自己的经历为例。以前做前后端分离项目，我习惯先用 Swagger 定接口文档，再写后端实现，最后前端对着文档写调用代码。项目大了之后，最大的成本不在写代码，而在“保证前端拿到的数据和后端定义的类型一致”这件事上。改一个字段，文档、后端实体、前端 DTO、页面展示四处都要动，漏掉一处线上就可能出 bug。

T3 用 TypeScript 把这个链路彻底打通了。数据库Task模型加了dueDate字段，Prisma 客户端自动更新类型，tRPC 的返回值跟着变，前端调用处如果不传这个字段，编译直接报错。这种感觉就像你写本地方言也能让远处的人完全听懂，不再需要中间翻译。

适合场景：数据密集型应用、内部管理系统、SaaS 多人协作工具、需要频繁迭代数据模型的 MVP 项目。不适合场景：纯展示型官网、静态博客这类不需要复杂数据交互的站点。

1.3 这套架构的优势和代价

优势非常明显：开发效率高、类型可靠、代码量少。一个简单的查询接口在 REST 方案里可能要写 controller、service、dto、路由注册四层，在 tRPC 里就是一个protectedProcedure.query()的事。

但代价也不能忽略。首先是学习曲线，你需要同时具备 React、TypeScript 和数据库基础才能顺畅上手，对纯前端转全栈的人不太友好。其次是架构约束，T3 的很多设计假设你用的是 Next.js，如果你突然要在客户端渲染场景中用 WebSocket 做实时推送，tRPC 的体验就不如直接开一个 Socket 服务。还有一点，生态相对年轻，tRPC 社区里遇到疑难问题时，能搜到的实战案例比传统 REST 少得多。

一句话总结：T3 是一套把 TypeScript 潜力压榨到极致的组合，但它不是银弹，它只适合愿意接受它设计哲学的人。

2. 六组件深度拆解：每个库的核心价值在哪里

2.1 Next.js App Router：Server Component 是 tRPC 的最佳搭档

T3 脚手架默认使用 App Router。很多人疑惑为什么不用 Pages Router，毕竟传统getServerSideProps那一套看着更直观。我的理解是：App Router 带来的 Server Component 能力，和 tRPC 在服务端直接调用 procedure 的方式是天然互补的。

tRPC 有一个server caller的概念，你可以在 Server Component 里直接调用api.task.list()，不需要发起一次 HTTP 请求。它少了一次网络往返，而且类型是真实的 TypeScript 函数调用，不是字符串拼 URL。这种体验在 Pages Router 时代是做不到的，因为那时候每个页面的数据获取要么写在getServerSideProps，要么在客户端 useEffect 里 fetch，没有一个干净的“页面组件内部直接调用后端逻辑”的通道。

App Router 也带来了一些新的心智模型。比如“use client”边界，你的组件如果用了 onClick、useState，就必须标记为客户端组件，而它不能直接调用api.xxx.query()（那个只能用在服务端）。刚开始很容易踩这个边界混乱的坑，后面我会专门写一节排查。

2.2 tRPC：为什么说它是 T3 的灵魂

如果只能用一个词形容 tRPC，我会选“零成本远程调用”。它不生成任何中间代码，也不要求你写路由表。你定义一个 router：

export const taskRouter = createTRPCRouter({ list: protectedProcedure.query(async ({ ctx }) => { return ctx.db.task.findMany({ where: { authorId: ctx.session.user.id }, }); }), });

前端直接写：

const tasks = api.task.list.useQuery();

你会发现，后端函数定义处没有写任何“导出接口”的代码，调用处也没写任何 URL、参数序列化或响应类型断言。类型完全靠 TypeScript 的编译期推导传递。这让 tRPC 在代码量上有巨大优势——尤其是在写 CRUD 类功能时，至少省掉三分之一的接口样板代码。

tRPC 的底层实现其实不复杂：在服务端维护一个 procedure 注册表，客户端通过一个/api/trpc/*的 HTTP 端点发起 POST 请求，把 procedure 路径和输入参数带上；服务端匹配注册表、执行 handler、把 JSON 序列化返回。类型之所以能自动推导，靠的是 TypeScript 声明文件里的类型映射。理解这层原理之后，你就知道为什么 tRPC 不能用“动态字符串”来调用——类型系统做不到对任意字符串做自动推导。

提示：tRPC 是 T3 里最容易被低估也最值得花时间学习的库。面试官问你对 tRPC 的理解时，不要只说“不用写接口”，把 procedure 注册表和类型推导原理讲清楚，才说明你真懂。

2.3 Prisma：一个 Schema 搞定模型、迁移和类型客户端

Prisma 的定位是数据库工具链，不只是 ORM。你写一个schema.prisma文件定义模型：

model Task { id String @id @default(cuid()) title String completed Boolean @default(false) createdAt DateTime @default(now()) authorId String author User @relation(fields: [authorId], references: [id]) }

然后跑prisma migrate dev，它会生成 SQL 迁移文件；跑prisma generate，它会生成一个类型安全的客户端对象PrismaClient，你可以在任意地方用db.task.findMany()查询，返回的每个字段都有精确类型。如果查了个不存在的字段，编译直接报错——这在传统 ORM 里要到运行时才能发现。

Prisma 的 Schema 语法也解决了一个痛点：数据库表结构成为团队里唯一可信的数据模型定义。以前我见过太多团队里“后端代码一套模型、数据库一套、前端拿到的响应又是一套”的混乱情况，用 Prisma 之后，数据库结构就是类型系统的源头，改动一处，全链路同步。

不过 Prisma 也不是没有缺点。复杂查询（比如多个聚合层级嵌套、动态查询条件非常多）的 SQL 表达能力比裸 SQL 弱一等；有些特定场景下，它还支持$queryRaw写原生 SQL，必要时候也能用得上。

2.4 NextAuth.js：认证模块也要类型安全

登录认证一直是全栈开发里麻烦的部分，因为涉及 Session 存储、Cookie 处理、第三方 OAuth 回调等环节。NextAuth.js 把大部分流程封装好了，你只需要配置 providers 和一个authOptions：

export const authOptions: NextAuthOptions = { providers: [ GitHubProvider({ clientId: env.GITHUB_CLIENT_ID, clientSecret: env.GITHUB_CLIENT_SECRET }), ], callbacks: { session({ session, user }) { return { ...session, user: { ...session.user, id: user.id } }; }, }, };

然后在 tRPC 的createTRPCContext里读取 session，就能在 procedure 里头拿到当前登录用户：

export const protectedProcedure = t.procedure.use(({ ctx, next }) => { if (!ctx.session?.user) { throw new TRPCError({ code: "UNAUTHORIZED" }); } return next({ ctx: { ...ctx, user: ctx.session.user } }); });

这样一旦标记为protectedProcedure，前端没登录的请求就直接被拦下，而且这个过程同样是类型安全的——你可以在 handler 里放心地用ctx.user.id，不用做运行时判空。

2.5 Tailwind CSS：为什么团队愿意放弃组件库

如果问 T3 用户为什么选 Tailwind，大多数人的回答是“快”。确实，Tailwind 的原子类写法可以直接在 JSX 里完成大部分样式调整，不需要来回切 CSS 文件，也不需要为一个按钮专门写一个.btn-primary类。更关键的是，Tailwind 的 JIT 编译机制让最终产出的 CSS 文件只包含你用到的类，避免样式冗余。

但你得接受它的代价：JSX 会变啰嗦。一个按钮的分类可能占三行，阅读体验确实不如语义化 CSS 类名。我的处理方式是用clsx或cn工具函数封装一些高频类组合（比如卡片、按钮、表单输入），既享受 Tailwind 的高效，又不至于让 JSX 看起来像一团乱麻。

如果你已经习惯了 Element Plus 或 Ant Design 这类组件库，用 T3 可能会有一段时间的“裸奔感”。但用久了就会发现，Tailwind 搭配 shadcn/ui 这类 Copy-paste 风格的组件方案，自由度远高于传统 UI 框架，很多页面只需少量代码就能实现独特视觉效果。

3. 从零搭建一个 t3code 项目：脚手架实战演练

3.1 初始化项目和选项选择

官方脚手架是create-t3-app，一条命令就能建好全套项目骨架。

npm create t3-app@latest

交互式提问会让你选择启用哪些模块，我建议第一次接触时全部勾选：

• Next.js
• TypeScript
• Tailwind CSS
• tRPC
• Prisma
• NextAuth.js

它会询问你是否用 Docker 启动数据库、是否用 ESLint/Prettier。我个人习惯先选“否”跳过 Docker，本地直接用一个 PostgreSQL 实例；ESLint 和 Prettier 一定要开，T3 默认的代码规范很严格，团队协作时能避免很多“为什么这个 CI 失败了”的问题。

注意：T3 默认要求使用T3 Turbo吗？不是。create-t3-app 生成的是单仓库模式，不是 monorepo。如果你项目复杂到需要拆前端后端多个包，可以后期自行改造，但第一次做不建议手动切 monorepo，徒增复杂度。

脚手架生成完，目录结构大概长这样：

src/ ├── app/ │ ├── _components/ │ ├── layout.tsx │ ├── page.tsx │ └── api/ │ └── auth/[...nextauth]/ │ └── trpc/[trpc]/ ├── server/ │ ├── api/ │ │ ├── routers/ │ │ └── root.ts │ ├── auth.ts │ └── db.ts ├── trpc/ │ ├── query.ts │ ├── react.tsx │ └── server.ts └── env.js

其中src/trpc/server.ts里创建了一个 server caller 对象，供 Server Component 调用 tRPC procedure；src/trpc/react.tsx创建了 React Query 的 hooks 客户端，供客户端组件使用。这两个文件是后续开发中接触最多的。

3.2 配置环境变量与数据库

T3 依赖环境变量非常多，初次启动最容易在这里翻车。你需要去.env里填好：

DATABASE_URL="postgresql://username:password@localhost:5432/t3code?schema=public" NEXTAUTH_SECRET="openssl rand -base64 32 生成的一段随机字符串" NEXTAUTH_URL="http://localhost:3000" GITHUB_CLIENT_ID="" GITHUB_CLIENT_SECRET=""

这些变量会被src/env.js里的createEnv函数校验。T3 用了一整套运行时校验机制，如果某个变量缺失，应用启动就会直接报错，而不是跑到一半才发现。对于团队协作来说，这个设计很宝贵——新人拉取代码后，能在第一时间发现问题，而不是等部署到线上才被环境变量问题坑惨。

NEXTAUTH_SECRET用 OpenSSL 生成即可。如果你决定登录 Provider 先用 GitHub，那需要到 GitHub OAuth Apps 页面注册一个新应用，Callback URL 填http://localhost:3000/api/auth/callback/github，拿到 client id 和 secret 再填进去。

3.3 定义 Prisma 模型与生成客户端

拿一个“团队任务管理”的例子来说，我们要做三步：定义模型、跑迁移、写 tRPC 调用。

先编辑prisma/schema.prisma，把默认的示例模型清空，换成：

model User { id String @id @default(cuid()) name String? email String? @unique emailVerified DateTime? image String? accounts Account[] sessions Session[] tasks Task[] } model Task { id String @id @default(cuid()) title String description String? status TaskStatus @default(TODO) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt authorId String author User @relation(fields: [authorId], references: [id]) } enum TaskStatus { TODO IN_PROGRESS DONE }

然后执行：

npx prisma migrate dev --name init npx prisma generate

第一次跑 migrate 时会自动建表，同时会调用 generate。之后再改动模型，只需重复这两条命令。如果数据库里已经有数据，迁移过程会给出警告，需要你手动确认一些破坏性操作。所以在早期阶段就建立“每天迁移一次”的习惯，避免积累太多变更后再一次性迁移，那才是噩梦。

3.4 写第一个 tRPC Router

在src/server/api/routers/下新建task.ts：

import { createTRPCRouter, protectedProcedure } from "~/server/api/trpc"; import { z } from "zod"; export const taskRouter = createTRPCRouter({ list: protectedProcedure.query(async ({ ctx }) => { return ctx.db.task.findMany({ where: { authorId: ctx.session.user.id }, orderBy: { createdAt: "desc" }, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1).max(100), description: z.string().max(500).optional(), }) ) .mutation(async ({ ctx, input }) => { return ctx.db.task.create({ data: { title: input.title, description: input.description, authorId: ctx.session.user.id, }, }); }), toggleDone: protectedProcedure .input(z.object({ id: z.string() })) .mutation(async ({ ctx, input }) => { const task = await ctx.db.task.findUniqueOrThrow({ where: { id: input.id }, }); if (task.authorId !== ctx.session.user.id) { throw new Error("无权操作该任务"); } return ctx.db.task.update({ where: { id: input.id }, data: { status: task.status === "DONE" ? "TODO" : "DONE", }, }); }), });

注意这里用了protectedProcedure——它内部已经检查了 session，所以 handler 里可以直接用ctx.session.user.id，不会出现空指针。

然后在root.ts里注册：

import { taskRouter } from "./task"; export const appRouter = createTRPCRouter({ task: taskRouter, }); export type AppRouter = typeof appRouter;

启动项目npm run dev，访问http://localhost:3000/api/trpc/task.list，应该能看到一个 JSON 响应（如果未登录会返回 UNAUTHORIZED）。

3.5 在页面里消费 tRPC

如果是客户端组件，用 React Query hooks：

"use client"; import { api } from "~/trpc/react"; export function TaskList() { const { data: tasks, refetch } = api.task.list.useQuery(); const createTask = api.task.create.useMutation({ onSuccess: () => refetch(), }); return ( <div> {tasks?.map((task) => ( <div key={task.id}>{task.title}</div> ))} </div> ); }

如果是 Server Component，用src/trpc/server.ts导出的api：

import { api } from "~/trpc/server"; import { TaskList } from "./TaskList"; export default async function DashboardPage() { const initialTasks = await api.task.list(); return <TaskList initialTasks={initialTasks} />; }

两种方式各有适用场景：Server Component 适合不需要频繁交互的页面首屏数据；客户端 hooks 适合需要人工刷新、缓存、状态管理的交互操作。一个页面里可以混用，但注意“use client”边界，客户端组件不能直接调用api（server caller）。

3.6 环境变量、Session 与页面联调

启动登录流程后，你还需要在页面里展示当前用户信息。用 NextAuth 的getServerSession：

import { getServerSession } from "next-auth/next"; import { authOptions } from "~/server/auth"; export default async function DashboardPage() { const session = await getServerSession(authOptions); if (!session?.user) { redirect("/auth/signin"); } return <div>欢迎回来，{session.user.name}</div>; }

这一套联调下来你会发现，几乎所有链路都不需要手写 HTTP 请求，数据从数据库一路到页面，类型从未失稳。这才是我坚持用 t3code 架构做中后台项目的核心原因。

4. 端到端类型安全的真正威力：一次需求变更的完整演示

4.1 场景：给任务增加“截止日期”字段

假设产品经理突然要求每个任务增加dueDate字段。在 T3 项目里，改动路径很短：

1. prisma/schema.prisma的Task模型增加一行：

dueDate DateTime?

2. 执行npx prisma migrate dev --name add_due_date。

3. tRPC 的 create 入参加上可选校验：

.input( z.object({ title: z.string().min(1).max(100), description: z.string().max(500).optional(), dueDate: z.date().optional(), }) )

4. 前端调用处补上传参：

createTask.mutate({ title: input.title, description: input.description, dueDate: input.dueDate ?? undefined, });

如果前端某个地方把dueDate的类型写错了，比如传了一个字符串，TypeScript 编译器立刻就能报错，不会等到线上才发现Invalid Date。这就是“端到端类型安全”最直观的体验。

4.2 类型推导的原理：声明类型的力量

tRPC 的客户端之所以能自动推导，是因为AppRouter这个类型被导出，并通过 React Query hooks 的泛型转换映射成了对前端可见的调用签名。

AppRouter └── task (TaskRouter) ├── list (Procedure<query>) ├── create (Procedure<mutation>) └── toggleDone (Procedure<mutation>)

在src/trpc/react.tsx里，createTRPCReact<AppRouter>()返回的对象，本质上是一个“类型映射函数”，它把 router 结构映射为 hooks：

• router.task.list映射为useQuery()
• router.task.create映射为useMutation()
• 参数类型和返回类型都取之于 server 端定义

理解了这层映射关系，你在调试类型问题时就不会觉得 tRPC 是“黑魔法”了。它只是比较巧妙地利用了 TypeScript 泛型和函数返回类型推导，没有用到任何运行时代码生成。

4.3 Server Component 与 tRPC 的协作要点

在 App Router 下，tRPC 官方提供了一种 server caller 的写法。你在src/trpc/server.ts里会看到一个类似这样的实现：

import { createTRPCProxyClient, httpBatchLink } from "@trpc/client"; import { appRouter } from "~/server/api/root"; import { createTRPCContext } from "~/server/api/trpc"; export const api = createTRPCProxyClient<AppRouter>({ links: [httpBatchLink({ url: "/api/trpc" })], });

但注意：这个api只能在 Server Component 里使用。如果是客户端组件里使用，会发起真实 HTTP 请求，而且类型不直接携带 session context，很容易出现权限判断遗漏。所以我的习惯是：

• Server Component 里的数据获取用api.xxx.query()
• 交互操作事件用api.xxx.useMutation()
• 不要在“use client”组件里调用 server caller

还有一个细节：如果 Server Component 和客户端组件都要同一个列表数据，我通常会把 Server Component 查到的数据作为initialData传给客户端组件里的 useQuery。这样首屏渲染很快，后续交互又能享受 React Query 的缓存能力。tRPC 的useQuery在 SSR 时会自动从缓存里收集数据，所以你甚至可以不做 initialData 传递，只在客户端组件里写useQuery，首屏也会正确显示。

4.4 什么时候不该用 tRPC 的自动推导

虽然 tRPC 很强，但它不适合所有接口。当你需要和第三方客户端（非 TypeScript 环境）通信时，tRPC 的类型安全优势就不存在了。比如：

• 做一个公共 OpenAPI 给外部开发者调用
• 和微信小程序原生端对接
• 和别的部门维护的 Go/Java 后端服务通信

这些场景下，tRPC 客户端无法使用，你必须自己包一层 HTTP 接口，或者退回去用传统 REST 网关。T3 的实际项目中，最常见架构是：内部模块之间用 tRPC，对外暴露少量 REST 接口给第三方用。两者并存是可以的，只要记得把对外接口独立成路由，别和 tRPC router 混在一起。

5. 常见问题与排查技巧实录

5.1 tRPC 泛型报错：类型不匹配但看不懂

新手常遇到的报错是Argument of type '...' is not assignable to parameter of type '...'。这通常是因为 input 的 z 校验和你前端传入的参数不完全一致，比如服务端定义z.string()，前端传了number。

排查思路：先看报错位置是在useMutation调用处还是useQuery的 select 回调里。前者看 input 校验，后者看返回类型。如果是返回类型导致的报错，检查 Prisma 模型是否改了但没有prisma generate。这个坑特别常见——务必记住：每改一次 schema.prisma，必须在项目根目录执行npx prisma generate，否则类型还是旧的。

我见过不止一个新人改了 Prisma 模型之后，前端编译一直报错，怎么也找不到原因，最后发现是忘了 regenerate types。这个操作很机械，但极其容易遗漏。

提示：在 package.json 的 postinstall 脚本里加上"prisma generate"，可以避免团队其他人 clone 后忘记生成类型。

5.2 NextAuth session 在 Server Component 里拿不到用户

典型报错是ctx.session.user为undefined。排查步骤：

首先检查 NEXTAUTH_URL 是否配置正确。本地跑是http://localhost:3000，部署到生产必须是 HTTPS 域名。其次检查authOptions里的sessioncallback 是否正确返回了 user id。如果一切正常，再看 tRPC context 的创建是否基于getServerSession而不是getToken。

我踩过一次最隐蔽的坑：在createTRPCContext里直接用了getServerSession(authOptions)，但由于我在 app router 下没有正确设置cookies()的读取逻辑，导致 session cookie 一直取不到。后来改成从headers.cookies()里手动读取并传给getServerSession才解决。

5.3 “use client”边界混乱导致的调用报错

在 App Router 里，如果你在客户端组件里引用了~/trpc/server里的api，运行时一定会报错，因为 server caller 依赖的是 Node.js 环境。报错信息往往含糊，常见的是Record或Headersis not defined。

解决方案是严格分离：

• ~/trpc/react里的 hooks 给客户端组件用
• ~/trpc/server里的 server caller 给服务端组件用

如果实在需要跨边界调用，把数据获取逻辑拆成一个 server-only 的模块，通过 props 把结果传给客户端组件。

5.4 React Query 缓存导致的“页面不更新”

客户端组件里的useQuery默认有缓存和 staleTime，在某些场景下，你调用了 mutation 成功更新了数据库，但页面上数据还是旧的。

我的做法是：在 mutation 的onSuccess里清掉相关 key 的缓存：

const createTask = api.task.create.useMutation({ onSuccess: () => { utils.task.list.invalidate(); }, });

这里的utils是从api.useUtils()拿到的，它让你能精确失效某个 procedure 的缓存。还有一种粗暴方案：直接设置useQuery({ refetchOnWindowFocus: true })，不推荐，因为它会造成无谓的请求。

5.5 Prisma 多对多关系和嵌套查询的类型陷阱

如果你给 Task 增加了“标签”多对多关系：

model Tag { id String @id @default(cuid()) name String @unique tasks Task[] }

查询时想连表取标签，可以直接在findMany里加include: { tags: true }，返回的类型会自动推导。但如果你做的是嵌套include且层级很深，TypeScript 的类型推导偶尔会遇到“递归深度”错误。

我的建议是：不要在一个查询里把所有关系都一次性 include，拆成多个 procedure 调用。代码可读性更好，类型推导也更稳定。

5.6 常见问题速查表

6. 写在最后的个人体会

T3 这套东西，我用了一年多，做过两个从零到上线的 SaaS 项目和一个内部工具平台。总体感觉得远大于失。它最大的价值不是“少写代码”这种速效收益，而是它让你在公司级别的小团队里能够真正实现“一个人闭环全栈”——我一个人用这套架构，从数据库设计到页面交互，全部不需要切换语言环境，头脑里始终有一个统一的类型流动节奏。

如果你是一个独立开发者或者只有三五人的小团队，我强烈建议你用 t3code 做你的下一个业务项目。但如果你所在的团队已经有很重的 REST 接口资产、外部系统依赖多、或者前后端成员分工非常明确且不想互相学习对方的工具链，T3 可能并不会给你的协作带来多少改善。

最后分享一个实战小技巧：一定要把prisma studio用起来。npx prisma studio可以启动一个本地数据库可视化面板，快速查看和调试数据关系，开发调试效率提升巨大。很多新手因为打包编译复杂而弃用这个工具，实际上它对 T3 项目来说几乎是刚需。

t3code 不难，但它要求你放下一些惯性思维。一旦你适应了这种“全链路类型安全”的开发方式，再回去写传统 REST + 手写类型，你真的会浑身难受。