企业官网建设流程全解析

t3code 这个名字，第一次看到的人可能会觉得是个密码，或者某个工具的内部代号，但真正在 Next.js 全栈开发里泡过一阵子的人，应该能立刻嗅到那股熟悉的味道：Tailwind、TypeScript、tRPC。没错，这不是什么新框架，而是把 T3 Stack 这套已经被验证过的技术组合，真正落到一个具体工程项目里的代码实践。我拿到这个标题的时候，脑子里浮现的是一整套从零初始化、路由组织、数据库接入、鉴权打通、再到线上部署排查的完整链路。这篇博文，就是围绕 t3code 这套基于 T3 技术栈的实战笔记，把我在搭建、迭代和排坑过程中的经验完整梳理一遍，给你一条可以直接照着走的路线。

先说清楚这篇文章能解决什么问题。如果你正准备用 Next.js 做一个全栈项目，又不想在“用 REST 还是 GraphQL”“ORM 选哪个”“样式方案怎么定”这些选择题上反复纠结，那 T3 技术栈就是一套现成的“黄金答案”。它不是一个框架，而是一套工具组合的约定，核心就三个字母：TypeScript、Tailwind、tRPC。再配上 Next.js、Prisma、NextAuth，刚好覆盖一个全栈应用从数据库到 UI 的全部环节。这篇内容适合谁？适合那些已经写过一些 React，知道 Next.js 是什么，但还没完整用 T3 Stack 做过项目的开发者；也适合已经上手但踩了不少坑，想看看别人怎么处理类型推导、服务端校验、部署配置这些细节的人。我会从为什么选这套组合讲起，拆到具体的目录结构、关键代码实现，最后整理一份常见问题排查表，全程都是可以直接抄作业的实操内容。

1. 内容整体设计与思路拆解

1.1 T3 Stack 解决的是“选择困难症”

任何一个用过 React 生态的人，面对新建一个全栈项目时，都会陷入一种熟悉的选择漩涡：前端框架用 Next.js 还是 Vite？数据请求用 fetch 封装还是 React Query？后端 API 用 Express 还是 NestJS？数据库访问直接写 SQL 还是上 ORM？每选一个，都意味着引入一整套新概念和新的调试方式。T3 Stack 的核心价值，就是把这些选择提前帮你做了，而且做成了一套默认约定。它的创造者 Theo 有句很出名的话：问题不是“工具不够多”，而是“决定太多”。t3code 这个项目，本质上就是把这个哲学落到了实实在在的代码里。

这套约定具体是：Next.js 负责页面和 API 路由，TypeScript 做全栈类型安全，Tailwind 解决样式，tRPC 替代 REST/GraphQL 做前后端数据通信，Prisma 操作数据库，NextAuth 处理鉴权。你可能会有疑问：tRPC 不是比 REST 冷门吗？为什么不用更主流的 Axios 加接口文档？这个问题我后面专门讲。你只需要先记住，这套组合最大的收益是“类型从数据库一路贯穿到 UI”，也就是说，你在 Prisma schema 里定义的一个字段类型，最终能在前端组件里被 TypeScript 自动提示出来，中间不需要手写任何接口类型定义。这种体验，用惯了 REST 的人第一次感受到时，真的会有种豁然开朗的感觉。

1.2 为什么选 Next.js 而不是纯前端方案

t3code 项目里，Next.js 承担的角色不只是一个 React 框架，而是整个应用的“外壳”。它同时提供了服务端渲染、API 路由、文件系统路由和中间件机制。在 T3 Stack 里，Next.js 的 API Routes 不是用来暴露传统 REST 接口的，而是作为 tRPC 的挂载点。这意味着，你写的一个函数，既可以被客户端直接调用，像调用本地函数一样带上类型，又可以通过 Next.js 的 serverless 能力部署到边缘节点。这和省掉一整套独立的 Node 服务，是有本质区别的。

我在实际搭建时也对比过用 Vite + Express 的方式：前端一个服务，后端一个服务，中间需要处理 CORS、部署两套、环境变量各管各的。而 Next.js + tRPC 的写法，是前后端放在同一个代码仓库、甚至同一个函数上下文里，开发环境只起一个 dev server，部署的时候也只需要一条流水线。对一个小型到中型的全栈应用来说，这种“单体应用”的架构成本是最低的。等到业务复杂到确实需要拆服务的时候，tRPC 也可以单独抽出来部署，Next.js 通过 HTTP Link 远程连接，迁移成本是可控的。

1.3 这套组合的核心哲学：类型安全优先

T3 Stack 的三个 T，真正串起全局的还是 TypeScript。类型安全在这套组合里不是一句话口号，而是被贯彻到了每一层：Prisma 根据数据库 schema 生成类型，tRPC 根据 router 定义推导出客户端调用签名，NextAuth 的 session 类型可以被扩展后注入到 tRPC context，再到前端组件，全程都是强类型。这就是“类型安全优先”的意思。它带来的直接好处是：你改了一个数据库字段名，如果漏改了某个前端组件，编译期就会直接报错，而不是等到运行时接口 500。

这套模式也有人质疑：有类型安全就一定好吗？我的看法是，类型安全不是银弹，但它极大地降低了大项目里“改了这头忘了那头”的隐性问题。尤其是团队协作时，新成员通过类型定义就能大致知道每个接口接收什么参数、返回什么数据，省去了翻接口文档的功夫。而 t3code 这样的实践，就是把 TypeScript 用到了“哪怕只有一个异步请求，也要让它的入参和返回值在编译期被完整推导”的程度。

2. 核心细节解析与实操要点

2.1 初始化项目：create-t3-app 的正确姿势

创建 t3code 项目，推荐直接用 create-t3-app 脚手架。它会引导你选择需要的模块。我通常在初始化时勾选：Next.js、tRPC、Prisma、NextAuth、Tailwind。如果项目里暂时不需要鉴权，可以先不勾 NextAuth，后面再加也不算难；但 tRPC 和 Prisma 建议第一次就带上，因为它们的目录结构和类型生成逻辑已经深度耦合了。

npm create t3-app@latest t3code

初始化完成后，你得到的不是一个“最小 demo”，而是一个带有完整分层目录的工程模板。让我带你快速过一遍最关键的几个目录：

src/ ├── pages/ # Next.js 页面和 API 路由 ├── server/ │ ├── api/ │ │ └── routers/ # tRPC 路由定义 │ ├── db.ts # Prisma 客户端单例 │ └── auth.ts # NextAuth 配置 ├── trpc/ │ ├── server.ts # 服务端 tRPC 初始化 │ └── client.ts # 客户端 tRPC 调用封装 └── styles/

这套结构背后有很多细节值得注意。比如db.ts里 Prisma 客户端一定是单例模式，因为在开发环境下 Next.js 的热更新会反复执行模块，否则会创建多个数据库连接实例，导致连接数爆掉。再比如trpc/server.ts里会定义一个createTRPCRouter和publicProcedure，后续所有业务路由都是基于这个基础实例扩展的。

2.2 tRPC route 的组织与命名约定

tRPC 的 router 设计，我建议按业务领域（domain）来划分，而不是按技术类型来划分。举个例子：如果你是做一个博客系统，那就建postRouter、userRouter、commentRouter，而不是建getRouter、postRouter。这个划分原则直接影响后续接口的扩展性。每个 router 内部再按“查询”和“变更”使用不同的 procedure 类型。

// server/api/routers/post.ts import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "../trpc"; export const postRouter = createTRPCRouter({ list: publicProcedure .input(z.object({ page: z.number().default(1) })) .query(async ({ ctx }) => { return ctx.db.post.findMany({ orderBy: { createdAt: "desc" }, }); }), create: publicProcedure .input(z.object({ title: z.string().min(1), content: z.string() })) .mutation(async ({ ctx, input }) => { return ctx.db.post.create({ data: input }); }), });

zod 在这里不只是做参数校验，它更是类型推导的源头。tRPC 会用z.infer从 zod schema 中提取 TS 类型，所以你不需要在 router 和前端各自维护一套类型定义。这一点非常关键：很多人刚用 tRPC 时，会习惯性地写type CreatePostInput = { title: string, content: string }，然后传到 zod 里，这其实是冗余的。正确做法是直接让 zod 当老板，TypeScript 类型都是它的“员工”。

2.3 Prisma 数据建模与迁移流程

对一个全栈项目来说，数据库 schema 设计几乎是地基。Prisma 的优势在于用 schema 文件声明式定义模型，然后自动生成客户端代码。我在 t3code 里通常先定义几个核心模型，然后跑一次迁移，让数据库真正建表。

// prisma/schema.prisma model Post { id String @id @default(cuid()) title String content String authorId String author User @relation(fields: [authorId], references: [id]) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

然后运行：

npx prisma migrate dev --name init

这里有一个新手很容易忽略的坑：Prisma 的migrate dev会在应用代码前检查数据库状态。如果你改了 schema，但忘了跑迁移，开发时功能看起来一切正常（因为 tRPC 调用的是基于旧 schema 生成的客户端），但部署到新环境时就可能出现表不存在的错误。另外，prisma generate这个命令会在迁移后自动执行，但如果你手动改了 schema 却没有跑迁移，generated client 也不会更新，类型提示自然就还是旧的。所以我习惯在写完 schema 后，第一时间执行迁移，保持 schema 和类型永远同步。

2.4 环境变量的管理与加密字段处理

T3 Stack 项目里，环境变量承载了很多关键配置：DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL 等。Next.js 本身对.env文件支持很好，但要注意一个细节：只有以NEXT_PUBLIC_开头的变量才会被打进客户端 bundle，其他变量只能在服务端使用。tRPC 的 router 运行在服务端，所以数据库地址、密钥这类变量完全不需要暴露给浏览器。我在本地开发时会准备.env.local文件，并且它一定要出现在.gitignore里。如果是团队项目，建议用.env.example维护一份变量清单，防止新同事拉代码后对着缺失的环境变量抓狂。

对于密钥类信息，比如 NextAuth 的 secret，我的建议是本地开发用一个随机生成的长字符串，生产环境则用部署平台提供的 secrets 管理功能，而不是直接写进 Docker 镜像或代码仓库。这一点不用多解释，但凡线上密钥泄露过的团队，都懂这里面的教训。

3. 实操过程与核心环节实现

3.1 逐步搭建一个带鉴权和 CRUD 的完整模块

光讲理论会太空，我用 t3code 里一个最常见的“文章发布”场景，带你从初始化走到页面渲染。先明确目标：用户能登录，登录后能创建文章，首页能看到文章列表。这个场景几乎覆盖了 T3 Stack 的所有核心机制。

第一步，配置 NextAuth。在初始化脚手架的基础上，打开server/auth.ts，设置 GitHub 或邮箱登录。我这里演示用邮箱 + 验证码的 Credentials 登录，因为它不需要第三方平台配置就能在本地测试。

// server/auth.ts 片段 import CredentialsProvider from "next-auth/providers/credentials"; export const authOptions = { providers: [ CredentialsProvider({ name: "credentials", credentials: { email: { label: "邮箱", type: "text" }, password: { label: "密码", type: "password" }, }, async authorize(credentials) { const user = await prisma.user.findUnique({ where: { email: credentials?.email }, }); // 校验逻辑... return user; }, }), ], session: { strategy: "jwt" }, };

第二步，在 tRPC context 里注入 session。这一步非常关键，它让所有 procedure 都能拿到“当前登录用户是谁”这个信息。T3 脚手架已经在createContext里做了这件事。

// server/api/trpc.ts 简版 export const createTRPCContext = async (opts: { headers: Headers }) => { const session = await getServerSession(authOptions); return { db: prisma, session }; };

第三步，写一个“仅登录用户可用”的 procedure。tRPC 的protectedProcedure就是从此处开始的。

import { TRPCError } from "@trpc/server"; export const protectedProcedure = publicProcedure.use(({ ctx, next }) => { if (!ctx.session?.user) { throw new TRPCError({ code: "UNAUTHORIZED" }); } return next({ ctx: { session: { user: ctx.session.user }, }, }); });

第四步，在 post router 里使用 protectedProcedure 实现创建文章。这里比较关键的是authorId的赋值：不能从前端传入，而应该从 session 里读，这是防止越权的基本功。

export const postRouter = createTRPCRouter({ create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string() })) .mutation(async ({ ctx, input }) => { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });

3.2 调用链路：从 React 组件到服务端

接下来看客户端怎么调用。tRPC 的调用封装在src/trpc/client.ts里，它返回一个带类型信息的trpc对象。你在 React 组件里写trpc.post.create.useMutation()，不用关心 HTTP 细节和请求路径，就像直接调用一个本地函数。这种体验的关键在于，客户端的trpc类型是从服务端 router 类型通过 TypeScript 的typeof推导来的。你只要保证前后端在同一个 monorepo，类型就能自动同步。

// components/CreatePostForm.tsx import { trpc } from "../trpc/client"; export function CreatePostForm() { const utils = trpc.useUtils(); const createPost = trpc.post.create.useMutation({ onSuccess: () => utils.post.list.invalidate(), }); return ( <form onSubmit={(e) => { e.preventDefault(); const formData = new FormData(e.currentTarget); createPost.mutate({ title: String(formData.get("title")), content: String(formData.get("content")), }); }} > <input name="title" placeholder="标题" required /> <textarea name="content" placeholder="正文" required /> <button type="submit">发布</button> </form> ); }

注意这个onSuccess里的invalidate操作。它做的事情是“让 tRPC 丢弃缓存并重新请求列表数据”。这是 React Query 和 tRPC 深度集成的结果。如果你看到数据没刷新，多数情况是你忘了写invalidate，而不是请求失败了。

3.3 首页服务端渲染与静态生成的选择

Next.js 页面支持多种渲染模式，t3code 项目的一般经验是：公开的、不依赖用户 session 的内容，用 SSG（静态生成）；需要带用户状态的内容，用 SSR 或者纯客户端渲染。以文章首页为例，由于文章列表是公开数据，可以在getStaticProps里调用 tRPC server 端的 caller 来获取数据，这样首屏直出 HTML，SEO 友好。

// pages/index.tsx import { createCaller } from "../server/api/root"; import { prisma } from "../server/db"; export async function getStaticProps() { const caller = createCaller({ db: prisma, session: null }); const posts = await caller.post.list({ page: 1 }); return { props: { posts } }; }

这里有个容易踩的坑：不要直接在getStaticProps里使用trpc.post.list这个客户端方法，那是为浏览器环境准备的。服务端要用createCaller生成一个“可调用版本”。二者的区别在于，客户端方法会用 fetch 发 HTTP 请求，而 createCaller 是直接以函数调用方式执行，省去网络开销。我见过不少人在这块绕了弯路，把服务端调用也当作 HTTP 请求来写，结果不仅慢，还可能在无网络环境下报错。

3.4 部署前必须检查的几项配置

t3code 如果部署到 Vercel，整体非常顺滑，但有几个配置项需要提前确认。第一是DATABASE_URL必须指向线上数据库，不能是localhost。第二是NEXTAUTH_SECRET必须设置，否则登录功能会直接报错。第三是NEXTAUTH_URL必须指向你的线上域名，连错的话回调地址会不对，表现为“登录成功后跳回首页，但状态没有保持”。

部署到其他平台时，比如 Docker 容器，需要注意 Prisma 的生成目录问题。在生产构建时，通常需要执行prisma generate后再next build。如果构建阶段无法连数据库，要注意migrate deploy和prisma generate的顺序。我个人推荐在不依赖数据库连接的条件下先生成 client，再让应用启动时自动跑迁移迁移策略，这个顺序能避免大部分容器化部署的奇怪错误。

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

4.1 tRPC 类型不匹配：改了后端类型，前端没有生效

这是 t3code 项目里出现频率最高的问题。比如在 postRouter 的list里增加了一个字段，前端调用返回的数据里却看不到。通常的原因是 tRPC 的类型被缓存了，或者 tRPC client 的类型没有重新生成。tRPC 不同于 REST，它的类型是 TS 层面的，并没有一个单独的“生成命令”。理论上只要你保存文件，类型就会更新，但编辑器（VS Code）有时会因为 tsserver 卡住而显示旧类型。遇到这种情况，最快的处理是重启 TS Server：在 VS Code 里按Ctrl+Shift+P，输入TypeScript: Restart TS Server。如果还不行，就删掉.next目录和node_modules/.cache再跑一次next dev，基本能解决。

另一个容易忽略的点：前后端类型依赖的是一种“结构一致性”。如果服务端函数签名变了，但前端某个组件仍用旧属性名访问，编译时会报错。如果你没报错，反而说明你根本没有从 tRPC 导出的类型里取值，可能在不经意间自己写了一个硬编码的接口类型定义，接上了静态的 fake 数据。

4.2 Prisma 连接池爆满，开发环境频繁断连

开发 Next.js 应用时，热更新会反复执行模块加载。如果没有做 Prisma 客户端单例化，每次加载都会新建一个 PrismaClient。开发服务器跑上半天，数据库连接池就会被占满。t3code 的脚手架里server/db.ts已经提供了单例写法，但如果自己手动改过，很容易破坏这个机制。这里的关键点是在全局对象上缓存 PrismaClient。

// server/db.ts import { PrismaClient } from "@prisma/client"; const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient }; export const prisma = globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV !== "production") { globalForPrisma.prisma = prisma; }

这个模式不只是 t3code 在用，很多 Next.js + Prisma 的项目都是这么写的。它背后的意义是：development 环境下模块会被多次 import，但我们要保证只存在一个数据库连接实例。

4.3 NextAuth 回调地址错误导致登录死循环

这是一个非常折磨人的问题。现象是：点击登录，跳到认证平台，认证成功后跳回/api/auth/callback，然后页面又跳回登录页，循环往复。排查步骤很简单，先看浏览器地址栏的回调 URL，再看服务端日志。绝大多数原因就是NEXTAUTH_URL配置不对。如果是本地开发，要确保它指向http://localhost:3000；如果是部署环境，要指向https://你的域名。另外，如果前端用了代理前缀类似/app的情况，还要在authOptions里配置basePath或者反代规则，否则回调路径会不对。

我还遇到过一个比较隐蔽的情况：同时存在两个.env文件，一个是.env.local，一个是.env，两个文件里的NEXTAUTH_URL不一致，导致 NextAuth 时而读到对的值，时而读到错的。解决方法是统一环境变量来源，最好只保留.env.local做本地开发，生产环境的配置交给部署平台。

4.4 表格：高频问题速查与解决建议

4.5 类型安全之外：运行时校验不能省

tRPC 的 zod 校验，给很多人一种错觉：只要类型对了，运行时就不会出问题。但类型检查只存在于编译期，运行时的数据可能由于用户手动构造请求带来意外值。举一个真实例子：前端代码声明page: number，但恶意请求或某个老版本客户端可能传入字符串"1"，这在 JS 里不报错，但可能导致 Prisma 查询异常。所以我坚持在每一个 procedure 的 input 上都写 zod schema，哪怕只是最小限度的z.string().min(1)。这同时还能体现在 API 文档自动生成时，让前端团队清楚地了解参数约束。用 tRPC 并不意味着可以省略输入校验，反而是以更优雅的方式内嵌校验逻辑。

4.6 一个我踩过坑的细节：useQuery和useMutation的闭包陷阱

在 React 组件里使用 tRPC 的useQuery，如果你在select或onSuccess回调中引用了组件外部的变量，要注意闭包捕获问题。例如在列表页中，如果select里引用了当前筛选条件keyword，而keyword是从 useState 来的，你会发现当keyword变化时，select回调可能仍然捕获旧值。解决办法是把keyword放进 query input，这样当keyword变化时，tRPC 会自动重新请求，而select只负责做纯转换。这类经验属于典型的“不踩一次不知道，踩了永远记得”的坑。

5. 从 t3code 延伸出去：这套模式还能怎么用

5.1 不只是 Next.js：tRPC 可以独立抽象

很多人在 t3code 这样的实践完成后，会思考一个问题：如果未来团队要把 BFF 层拆成独立服务，这套模式还成立吗？答案是成立的。tRPC 其实可以脱离 Next.js 使用，用独立 Node 服务承载，前端通过 HTTP Link 连接。这样的话，你保留的 router 定义、zod 输入校验、类型推导能力都不受影响，只是从“单体上下文”变成了“远程调用”。而 Next.js 应用则可以通过serverClient或者 wrapper 函数，把远程 tRPC 服务当作一个普通依赖来用。迁移成本主要集中在环境部署，而不是代码逻辑。

5.2 用 zod 统一校验和类型源头

t3code 实践下来，我最深的体会之一是：整个项目的类型源头，其实不在 TypeScript 的 interface 里，而在 zod schema。无论是 tRPC input、output，还是 Prisma 查询条件，zod 都能统一生成类型定义。后续如果想加一个 REST API 层来兼容移动端，可以直接复用 zod schema，用zod-to-openapi生成 OpenAPI 文档。这就是“一个 schema 多处使用”的收益，在业务迭代快时，省下的维护成本相当可观。

5.3 测试策略：给 tRPC router 写集成测试

t3code 项目做到一定规模后，测试就成了刚需。针对 tRPC router 的测试，我推荐用这种方式：直接创建一个createCaller，在测试环境里传入真实数据库或内存数据库上下文，把 router 当作普通函数调用。这样测试的是纯逻辑层，不走 HTTP，不需要启动 Next.js 服务，速度很快。

// post.test.ts import { createCaller } from "./root"; import { prisma } from "./db"; test("未登录用户不能创建文章", async () => { const caller = createCaller({ db: prisma, session: null }); await expect( caller.post.create({ title: "测试", content: "内容" }) ).rejects.toThrow(); });

这种测试写起来很自然，而且因为 tRPC 的 context 就是普通的对象，你甚至可以 mock session 来模拟不同权限。相比给 REST API 写集成测试要启动整个 HTTP 服务，这套方案简洁太多。我在做 t3code 时，给核心业务模块整理了几十条这种测试，后续重构时安全感大增。

5.4 监控与日志：别忽略服务器端错误捕获

tRPC 的客户端调用看起来像函数调用，但本质上还是网络请求。所以错误处理不能只在组件里 await catch，还需要在服务端 tRPC 的onError回调里统一做日志上报。在createNextApiHandler的选项里，有一个onError参数，在这里可以接入 Sentry 或自定义日志。我在 t3code 里接入了 Sentry 后，很多线上问题能第一时间看到错误堆栈和用户操作路径，定位效率提升很明显。

export const apiHandler = createNextApiHandler({ router: appRouter, createContext: createTRPCContext, onError: ({ error, path }) => { console.error("tRPC 请求错误", { path, error }); }, });

个人体会是，t3code 这种项目最迷人的地方不是某个单点技术有多炫，而是它把一整条链路上的工程细节都串联了起来：从数据库建模到 API 定义，从服务端鉴权到客户端缓存失效，从开发环境的连接池维护到生产环境的迁移策略。每个环节单独拎出来都不算复杂，但组合在一起，就会产生一种“边写边有编译器盯着”的安心感。

最后再分享两个小技巧。第一个：如果你发现 tRPC 的useQuery返回的数据明明变了，但 UI 没有刷新，检查一下是不是在select里返回了新的对象引用——React Query 的默认行为是引用比较，如果你的 select 每次都会return { ...item }，那么即使原始数据不变，也会触发重渲染。第二个：为了让开发体验更好，建议在tsconfig里开启strict: true。T3 脚手架默认是开启的，但如果你是从旧项目迁移来的，就一定要确认这一点，否则 zod 的z.infer在某些情况下产生的类型会变得不够严谨。这两点，再加上前面的问题速查表，基本覆盖了 t3code 从构建到维护阶段大部分让人摸不着头脑的场景了。