企业官网建设流程全解析

如果你最近在逛 GitHub Trending 或者 TypeScript 相关的技术社区，应该会看到 “t3code” 这个热词反复出现。它并不是某个单点工具，而是社区里对 T3 Stack 全栈工程实践的一种约定俗成叫法——一套由 Next.js、TypeScript、tRPC、Prisma、Tailwind CSS、NextAuth.js 组成的标准技术配方。这套配方的核心口号只有四个字：端到端类型安全。也就是说，从数据库表结构、服务端接口、页面组件到前端调用，所有数据的形状都被 TypeScript 盯得死死的，几乎不给你留运行时才发现拼错字段的机会。

这篇文章我准备一次性讲透 t3code 背后的选型逻辑、从零搭建的完整步骤、我在实际开发中踩过的 tRPC 边界坑，以及部署上线时值得注意的细节。适合谁看？一是正准备用 Next.js 做全栈项目但不确定怎么组合技术的同学，二是已经听过 T3 Stack 但没真正跑通的人，三是想了解 TypeScript 全栈工程化收益的老手。我的立场很直接：这套栈不是银弹，但在大多数中大型全栈项目里，它的收益是实打实的。

1. t3code 到底解决了什么问题：T3 Stack 选型逻辑拆解

1.1 从一套网红脚手架说起

t3code 这个名字，最早就是在社区讨论 create-t3-app 这个脚手架时被反复带出来的。create-t3-app 让开发者用一行命令初始化一个包含上述全部技术的项目，省掉了组合配置的漫长过程。但在使用之前，必须先理解一个关键问题：为什么这些技术偏偏被拼到了一起？

答案在于它们解决了全栈开发里的三个核心矛盾。

第一，API 层的类型断层。传统模式里，前端用 fetch 调后端接口，后端返回 JSON，前端再手动定义 interface。接口一多，类型定义就漂移——后端改了返回值，前端忘了同步，运行时才炸锅。tRPC 的存在，让前后端共享同一套 TypeScript 类型推导，你前端拿到的数据，形状就是后端函数返回值的形状，连手写类型都省了。

第二，数据建模与业务逻辑的割裂。Prisma 的 schema 文件既是数据库表结构的唯一真源，也是 TypeScript 类型的生成源头。你在 schema.prisma 里定义好的 model，立刻能在服务端代码里获得完整的类型补全。数据库表结构改了，类型跟着改，错误在编译期就会冒出来。

第三，认证状态的前后端同步。NextAuth 负责登录会话，tRPC 的 context 从 NextAuth 获取 session，然后注入到每个接口的调用链里。前端可以安全地根据 session 状态渲染界面，后端在同一类型系统下做权限校验，两边的“登录状态”永远一致。

这三个矛盾，几乎是任何全栈项目都会遇到的，而 T3 Stack 用一套紧密耦合的 TypeScript 工具链把它们一起解决了。这也是 t3code 这类项目会被社区大量复制的原因——它把可复用的工程范式沉淀成了模板。

1.2 TypeScript 全栈带来的“契约感”

我做过不少前后端分离的项目，最深的体会是：维护接口文档的痛苦，甚至超过了写业务本身。接口一多，文档就滞后；文档滞后，前端就靠猜；靠猜，线上就翻车。t3code 的做法本质上是把“文档”变成了编译器——你的接口签名本身就是文档，前端调用出错，编译器第一时间告诉你。

这不是玄学。当你把一个 tRPC procedure 从src/server/api/routers/post.ts里导出，再在客户端组件里调用api.post.all.useQuery()，IDE 立刻能补全出返回值的字段。加一个新字段，后端保存，前端刷新，类型自动出现。删一个字段，前端引用处直接红色波浪线。这种“契约感”会改变整个团队的协作方式，前端不需要天天追着后端问接口结构，后端也不用反复发接口定义文档。

1.3 这套选型的边界：不是所有项目都合适

但我也要说点泼冷水的话。T3 Stack 是有学习成本的，尤其是 tRPC 这个相对新颖的 RPC 方案，很多人第一次接触会觉得抽象。如果你的项目只是几十个页面的内容展示站，几乎没有交互、没有数据变更，那 Next.js 的 Server Component 直接查数据库就够了，完全不需要上 tRPC。或者你的项目是要给第三方开放大量公开 API，那 REST 或 GraphQL 仍然比 tRPC 更合适——因为 tRPC 依赖 TypeScript 类型共享，跨语言、跨团队的消费方用起来并不方便。t3code 这类模板最大的价值是给你一条高质量起点，但起点选对了，后续仍然需要你判断要不要在某些模块上“脱离轨道”。

2. 从零搭建一个 t3code 风格项目：脚手架、目录与数据模型

2.1 环境准备与初始化命令

T3 Stack 目前要求 Node.js 18.x 以上，建议直接用最新的 LTS 版本。同时准备好一个包管理器，我习惯用 pnpm，因为它对依赖的保存方式更严格，不容易出现“本地能跑、线上构建失败”的玄学问题。初始化命令如下：

npx create-t3-app@latest my-t3-app

执行后，终端会问你要集成哪些模块。我的建议是全部选中，包括 NextAuth、Prisma、Tailwind、tRPC，语言选 TypeScript。如果你不想用 Tailwind，也可以去掉，但我个人不建议这么做——后面你会看到 Tailwind 在快速搭页面时的效率优势有多明显。

初始化完成后，项目结构大致是这样：

my-t3-app/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── app/ │ │ ├── api/ │ │ │ └── trpc/ │ │ │ └── [trpc]/ │ │ │ └── route.ts │ │ ├── layout.tsx │ │ └── page.tsx │ ├── components/ │ ├── server/ │ │ ├── api/ │ │ │ ├── root.ts │ │ │ ├── trpc.ts │ │ │ └── routers/ │ │ ├── auth.ts │ │ └── db.ts │ ├── trpc/ │ │ ├── react.tsx │ │ ├── server.ts │ │ └── shared.ts │ └── styles/ │ └── globals.css └── .env

这个目录划分很有意思，src/server专门放服务端逻辑，src/trpc放 tRPC 的客户端和服务端共享配置，src/app放页面。它从一开始就把“服务端代码”和“客户端代码”隔开了，配合 Next.js 的 server-only 导入限制，能减少不小心的泄漏（比如在客户端组件里误引入数据库连接）。

2.2 Prisma 建模与数据库迁移：字段类型不是小事

Prisma 是这套栈的“地基”，schema.prisma 里定义的一切，都决定了后续所有代码的状态。我用一个博客场景来举例，这个例子我实际写过多次，能覆盖大部分常见需求：

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 emailVerified DateTime? image String? posts Post[] accounts Account[] sessions Session[] } model Post { id String @id @default(cuid()) title String content String? published Boolean @default(false) author User? @relation(fields: [authorId], references: [id]) authorId String? createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

这里我想特别提醒一件事：主键和自增 ID 的选择。t3code 模板默认用cuid()而非自增整数，这是有意的设计。cuid 由时间戳和随机数组成，完全分布式生成，不会被遍历猜测，而且字符串类型在前端做 URL 参数时不会暴露数据规模。如果你以前习惯了 MySQL 的自增 ID，换到 T3 Stack 后可以先忍住这个惯性，用一段时间 cuid 你会发现它其实更省心。

模型建好之后，运行迁移命令（这里以 SQLite 为例，生产用 PostgreSQL 时流程完全一致）：

npx prisma migrate dev --name init

这条命令会生成一个迁移文件夹，同时自动生成 Prisma Client。这里有个经验：迁移文件一定要提交到代码仓库。因为迁移历史就是数据库结构的版本控制，团队协作时其他人 pull 代码后执行prisma migrate dev就能把本地库升级到最新状态，而不是靠手工改表结构。

2.3 从 Prisma 到 tRPC：路由设计的基本套路

数据模型定好之后，就可以开始写 tRPC router 了。T3 Stack 的惯例是把不同业务域拆成不同的 router 文件，比如routers/post.ts和routers/user.ts，然后在root.ts里汇总：

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

一个典型的 post router 长这样：

// src/server/api/routers/post.ts import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; import { db } from "~/server/db"; const createPostSchema = z.object({ title: z.string().min(1, "标题不能为空").max(100), content: z.string().min(1), }); export const postRouter = createTRPCRouter({ all: publicProcedure.query(async () => { const posts = await db.post.findMany({ orderBy: { createdAt: "desc" }, }); return posts; }), byId: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ input }) => { return db.post.findUnique({ where: { id: input.id } }); }), create: publicProcedure .input(createPostSchema) .mutation(async ({ input }) => { return db.post.create({ data: input }); }), });

这里的核心是publicProcedure和input()。tRPC 用 zod 在服务端做校验，前端调用时传错参数，立刻会在开发环境抛错。这个校验行为不是可有可无的装饰，而是安全边界的一部分——别因为模板默认提供了publicProcedure就一直用 public，涉及用户数据的写操作，必须要用protectedProcedure，否则你的接口就是裸奔的。

3. tRPC 实践当中那些容易踩的坑：我替你趟过一遍

3.1 点亮 protectedProcedure：认证集成卡住全网新手的第一坑

T3 Stack 的模板里有一个src/server/api/trpc.ts文件，它定义了三样东西：createTRPCContext、createCallerFactory和基础 procedure。其中 context 会把 session 注入进来：

// src/server/api/trpc.ts import { initTRPC, TRPCError } from "@trpc/server"; import superjson from "superjson"; import { ZodError } from "zod"; import { getServerSession } from "next-auth"; import { authOptions } from "~/server/auth"; import { db } from "~/server/db"; export const createTRPCContext = async (opts: { headers: Headers }) => { const session = await getServerSession(authOptions); return { db, session, ...opts, }; }; export const t = initTRPC.context<typeof createTRPCContext>().create({ transformer: superjson, errorFormatter({ shape, error }) { return { ...shape, data: { ...shape.data, zodError: error.cause instanceof ZodError ? error.cause.flatten() : null, }, }; }, }); const enforceUserIsAuthed = t.middleware(({ ctx, next }) => { if (!ctx.session?.user) { throw new TRPCError({ code: "UNAUTHORIZED" }); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }); }); export const publicProcedure = t.procedure; export const protectedProcedure = t.procedure.use(enforceUserIsAuthed);

很多初学者在这里会犯一个错误：直接在业务里手动判断 session，而不用protectedProcedure。这样做的结果是每个接口里都要重复写认证异常，且容易漏。正确做法是在写业务前先看操作是否需要登录态——需要登录就立刻用protectedProcedure，把认证责任交给中间件层。这样后续的每个 mutation 都有统一的校验逻辑，不会因为某天忘了写认证而留下漏洞。

3.2 客户端调用与 loading 状态：useQuery 的优雅封装

服务端 router 写完，就要在 React 组件里调用。T3 Stack 给客户端提供了基于 React Query 的封装，在src/trpc/react.tsx里创建了api对象，实际使用非常舒服：

"use client"; import { api } from "~/trpc/react"; export function PostList() { const { data: posts, isLoading, error } = api.post.all.useQuery(); if (isLoading) return <div>加载中...</div>; if (error) return <div>出错了：{error.message}</div>; return ( <ul> {posts?.map((post) => ( <li key={post.id}> <h3>{post.title}</h3> <p>{post.content}</p> </li> ))} </ul> ); }

这里我想分享一个真实场景。早期我用 tRPC 时，总觉得isLoading只能用来显示“加载中”，直到做了个内部后台系统，才发现一个更妙的用法：把isLoading和isFetching区分开。isLoading是首次加载没有数据的状态，isFetching是已有数据后重新拉取的状态。淘汰刷新时如果直接用isLoading，页面会闪一下空白；用isFetching则可以在旧数据上显示一个顶部进度条，体验自然特别多。这些细节，React Query 的文档里都有，但很少有人告诉你组合到 tRPC 里该怎么用。

3.3 Server Component 能不能直接用 tRPC？

Next.js App Router 普及之后，我经常被问到：服务端组件里到底要不要通过 tRPC 拿数据？我的答案是：服务端组件直接调用服务端代码逻辑就行，不必绕 tRPC。比如在 RSC 里你可以直接 import db 查数据，或者调用一个封装的 service 函数。tRPC 的价值主要体现在客户端组件需要主动发起请求、跨网络执行调用的时候——包括 mutations、基于路由的 query、缓存失效等。

如果你在 RSC 里也调用api.post.all，走的是 HTTP 请求而不是函数直调，反而增加了序列化开销和额外延迟。模板没有阻止你这么做，但实际项目里最好把“RSC 直连 db”和“客户端组件走 tRPC”这两条路径区分清楚。这不是教条，而是我对比过两种方式在接口耗时上的明显差异后才得出的结论。

4. 数据校验、错误处理与类型安全：t3code 项目的骨架细节

4.1 Zod 不只是校验，更是类型推导引擎

t3code 项目会把 zod、tRPC、Prisma 三者串成一条生产线。zod 负责输入校验，tRPC 负责把校验后的类型传递到前端，Prisma 负责输出类型。整个过程每个环节的类型都是闭环的，正因如此，zod 的用法需要非常规范。

一个常见误区是：只在 tRPC mutation 里写 zod 校验就算了，数据库层的字段校验完全不管。更好的做法是在 zod schema 与 Prisma model 之间建立一种“共识”。比如 Post 表里title是必填且上限 100 字符，那么 zod 里就写z.string().min(1).max(100)，两边保持一致。将来表结构调整时，zod 校验不会自动跟着变，所以改 Prisma 迁移后要顺手检查一遍 router 里的 zod schema 是否需要同步更新。这不复杂，但漏了会在运行时报错，特别是在已有旧数据的生产环境里。

4.2 错误信息如何优雅地传递到前端

tRPC 的errorFormatter里有个我很欣赏的设计：自动把 Zod 的flatten()结果塞进响应里。这就让前端的表单校验体验变得很方便——后端校验失败后，前端能直接拿到字段级的错误信息：

"use client"; import { api } from "~/trpc/react"; import { useState } from "react"; export function CreatePostForm() { const utils = api.useUtils(); const [title, setTitle] = useState(""); const createPost = api.post.create.useMutation({ onSuccess: async () => { await utils.post.all.invalidate(); setTitle(""); }, onError: (error) => { const zodError = error.data?.zodError; if (zodError?.fieldErrors?.title) { alert(zodError.fieldErrors.title[0]); } }, }); return ( <form onSubmit={(e) => { e.preventDefault(); createPost.mutate({ title, content: "test" }); }} > <input value={title} onChange={(e) => setTitle(e.target.value)} /> <button type="submit">发布</button> </form> ); }

这里的关键技巧是utils.post.all.invalidate()——每次创建成功后，把列表缓存标记为失效，tRPC 会自动重新拉取最新数据。这个流程完全省掉了手工维护缓存状态的心智负担。我见过很多初学者在 onSuccess 里手动 setState 刷新列表，其实完全没必要，掌握invalidate就够了。

4.3 Superjson 与 Date 类型：小细节暴露大问题

模板在trpc.ts里默认配置了 superjson 作为 transformer。很多人不明白这是干嘛的，直到他们发现 tRPC 返回的Date类型在客户端变成了普通字符串。superjson 的存在就是为了解决这个问题——它能安全地序列化和反序列化 JavaScript 的Date、Map、Set等特殊类型，保证服务端传出的Date对象到了前端依然是Date对象。

这个细节直接影响你用 Prisma 查出的createdAt字段。如果没有 superjson，你的前端可能要对日期字段做各种格式转换；有了 superjson，一切保持原样。所以动手改模板配置时，superjson 一定要保留，别把它当无用配置删掉。

5. 部署与上线：从本地跑通到生产环境的完整经验

5.1 构建阶段最容易忽略的坑

T3 Stack 项目在生产构建时要执行 Prisma Client 的生成。如果你用 Vercel 部署，一定要在 build command 里包含迁移或至少生成客户端：

npx prisma generate && next build

如果是带着迁移一起执行，则可能是：

npx prisma migrate deploy && npx prisma generate && next build

很多人的构建失败都源于一个常见的错误：迁移文件已经存在，但因为.env里的DATABASE_URL没配置到生产环境，导致构建阶段 Prisma 无法确定数据库地址，直接报错退出。这个问题的特点是报错信息长得吓人，实际上就是环境变量缺失。

5.2 数据库连接在 Serverless 环境下的连接池问题

如果你选择把 Next.js 部署到 Serverless 平台（Vercel 或者 AWS Lambda），会遇到一个 Prisma 特有的大坑：每个请求都是一个独立函数实例，如果每个实例都发起新的数据库连接，瞬间就会把数据库连接数打爆。

解决办法是用连接池。如果是 PostgreSQL，可以在 DATABASE_URL 上添加连接池参数。比如：

DATABASE_URL="postgresql://user:password@host:5432/dbname?pgbouncer=true&connection_limit=5"

或者使用 PgBouncer / Prisma Accelerate 这类代理服务。更简单的本地开发做法是保留普通的 DATABASE_URL，部署时再换成带池化参数的地址。这个坑我建议在项目一开始就规划，不要等到线上出现 “Too many connections” 告警再补救，那种被动排障相当痛苦。

5.3 环境变量的分类管理

t3code 模板里的.env.example文件值得好好利用。把项目需要的全部环境变量列一份到这个文件里，提交到仓库，让团队成员 clone 项目後直接复制为.env就能本地跑起来。我见过太多项目把环境变量只存在自己电脑里，换台电脑就再也跑不起来。

项目里至少要分成三类环境变量：

NEXTAUTH_SECRET 这个变量我单独说一句：不要手动拍脑袋编一个“23333”，要用npx auth secret或openssl rand -base64 32生成。密钥强度不够，生产环境有被伪造 session 的风险。

6. t3code 之后，我对全栈工程的几点重新理解

6.1 类型安全本质上是在给团队“划边界”

用了一段时间 T3 Stack 再回头看，我最大的感受是：t3code 这类模板带来的最大收益其实是“边界变得清晰了”。数据库层有 schema 文件，API 层有 router 定义，认证层有 procedure 中间件，UI 层有组件边界。每一条边界都有类型系统把关，出了错，编译器会第一时间指出问题。

这种清晰度在团队协作里是很值钱的。两个人同时改一个模块，类型错误的冲突会在集成时暴露出问题，而不是上线后用户替我们发现问题。我经历过太多“原型没问题，一联调就崩”的项目，对比之下，t3code 风格的 TypeScript 全栈，是真的把这部分成本前置到了开发阶段。

6.2 哪些认知比我预期中更“香”

有几个点，是我实际使用前低估了的。

一是 Tailwind CSS 的 class 结构与 tRPC 的组件化配合。用 tRPC 把数据逻辑封装成 hooks 之后，UI 组件里几乎没有副作用代码，一个个函数式组件只管渲染。再配合 Tailwind 原子类，写页面的速度确实比写一串自定义 CSS 文件快不少。二是 React Query 的缓存失效模型，和 tRPC 的 procedure 路由天然契合，useUtils().xxx.invalidate()这套心智模型一旦建立，几乎可以复用到底。三是超级严格的服务端类型提示，当你把鼠标悬停在db.post.create({ data: ... })上时，IDE 会直接弹出完整的字段列表，这种体验是“非全栈 TypeScript”项目很难复刻的。

6.3 我不建议无脑套用 t3code 的场景

最后说点个人经验。如果你是做一个快速验证的 demo，或者一个小型个人网站，我建议直接 Next.js + 简单的 Server Actions 就够了，不必把 tRPC、Prisma、NextAuth 全都搬上来。工具链越多，依赖更新和配置成本就越高。反过来，如果你的项目预期会有多个业务域、需要权限控制、需要前后端协作，那从 t3code 起步是相当划算的——你省下来的不只是搭建时间，还有一套经过验证的工程规范。

我在实际项目里，有一次把一个几十个接口的 REST 服务迁移到 tRPC，前后花了两天。迁完之后，前端删掉了大约五百行手写类型定义和接口封装代码，整个团队联调效率上了一个台阶。这种体感是真实的。所以我的建议是：如果条件允许，找个中小型项目完整地走一遍 t3code 流程，把 tRPC、Prisma、NextAuth 三个核心组件真正用熟，之后你会对“全栈类型安全”这个概念有彻底不一样的认知。