企业官网建设流程全解析

t3code这个称呼，是我上个月给自己手头一个全栈项目起的内部代号。代号的意思很简单：T3 Stack + code。当时我准备把一套老旧的“Next.js页面 + Express接口 + 手写TypeScript类型”的代码库彻底改造掉，调研了一圈，最后用了T3 Stack这套组合重新搭地基。项目跑了一段时间，线上稳定、迭代效率明显上来，今天就把这套完整实践过程、踩坑记录和我的选型逻辑整理出来。这篇内容适合正在纠结全栈技术选型的前端同学、想给团队引入类型安全体系的负责人，也适合只是听说过T3 Stack但不知道从哪开始的朋友。

T3 Stack，往简单里说就是由 Next.js、TypeScript、Tailwind CSS 和 tRPC 四件套组成的全栈开发方案，再配合 Prisma、NextAuth.js 这些周边工具。它的核心卖点不是某一项技术多新颖，而是把“端到端类型安全”这件事做透了：从前端组件里的一个字段，到后端函数里的入参和返回值，再到数据库表结构，全链路强类型，编译期就能拦住一大半错误。这个理念和 t3code 这个项目的改造诉求正好对上：我们希望少写胶水代码、少维护重复的类型定义。

1. 整套方案的定位与选型逻辑

1.1 T3 Stack究竟是哪几层组合

T3 Stack 这个概念最早是从社区里流行起来的，后来官方把它做成了 create-t3-app 脚手架，一条命令就能生成一个干净的全栈项目。名字里的“T3”指的是三个以 T 开头的核心：TypeScript、Tailwind CSS 和 tRPC。不过实际项目里它几乎总是带上 Next.js、Prisma 和 NextAuth.js，就像打包好的全家桶。社区里常说的“T3”其实就是这么一套：前端框架用 Next.js，样式用 Tailwind，数据通信用 tRPC，数据库层用 Prisma，登录用 NextAuth。

这每一层单独拿出来都不算多新鲜：Next.js 是当下最流行的 React 框架之一，Tailwind 用原子类写样式，Prisma 是省心好用的 ORM，NextAuth 解决了第三方登录的重复轮子问题。但这套组合在一起，才产生真正的化学反应——全链路 type-safe。前端调用后端接口，在编辑器里能直接看到返回类型，参数错了编译期就报错；数据库表字段变了，Prisma client 重新生成，所有用到这个字段的地方立即收到类型修正。这是传统“前端写一套 d.ts、后端写一套 interface”的模式给不了的体验。

我刚决定用 T3 重写 t3code 的时候，第一反应是“这不就是把以前那套技术栈换了个马甲吗”。但真正上手写完第一个功能后，我才意识到差别不在某个库，而在开发范式：你不再需要为“接口文档同步”“字段命名不一致”“前后端类型漂移”这类问题反复开会。团队新成员上手，看着类型提示就能沿着整个业务链路走完，这对长期维护成本是实打实的降低。

1.2 为什么不直接选REST或GraphQL

很多从传统前后端分离项目转过来的朋友会问：现在 REST 已经很成熟，社区工具也多，为什么非要换 tRPC？我的看法是，得分场景。如果项目是“前端和后端完全独立部署、各自团队独立维护”，那 REST 加 OpenAPI 就是更稳妥的选择，因为接口边界是明确契约，而且往往要面向外部调用方开放。可 t3code 这种内部业务系统、中小型全栈项目，前后端本来就是同一个仓库、同一个团队在改，REST 的优势就变成了负担：每个接口要写路由、写请求校验、写响应类型，然后再在客户端写一遍对应的请求函数和类型引用。两头维护，漏一处就开始出 bug。

GraphQL 我也认真考虑过。它的强项是字段级查询和客户端自由度，但引入 GraphQL 意味着要维护 schema、写 resolver、处理缓存策略、选客户端库，这套成本对一个小团队来说并不低。而 tRPC 的思路极其简单：把后端的函数直接“暴露”给前端调用，借助 TypeScript 的类型推导，连 URL 拼接都省了。没有 schema 描述文件，不需要额外生成代码，调一个后端方法跟调一个本地函数一样自然。

当然 tRPC 也有它的边界。它依赖 TypeScript 和 HTTP，天然适合同构应用；如果以后要开放第三方 API 给外部系统，用 tRPC 就得做适配层，这种情况我一般建议对外路由继续走 REST，内部循环走 tRPC。t3code 项目目前就是这种结构：内部管理系统全部用 tRPC，对外开放的少量接口保持 REST，两边互不干扰。这个边界划清楚之后，项目没有出现那种“万能工具反而处处别扭”的尴尬。

2. 从初始化到目录结构的实操细节

2.1 create-t3-app 一键起步的正确姿势

搭建项目，我用的是官方脚手架 create-t3-app，一条命令搞定。这里有点经验想分享：不要用老版本 npm 去跑，我习惯先用 pnpm。装包快、磁盘占用小，而且 pnpm 的依赖管理在这个多包技术栈下很少遇到“依赖冲突”问题。命令很直接：

pnpm create t3-app@latest t3code

执行后脚手架会让你选择要包含哪些模块：Next.js（必选）、Tailwind CSS、tRPC、Prisma、NextAuth.js、App Router。第一次跑，我的建议是贪心一点，全选，别怕依赖多。因为 T3 的脚手架初始化非常干净，每个模块都是按需集成的，多选后期可以手动去掉，但后续再补就比较麻烦，类似“逆向配置”容易改坏。全选跑完之后，项目根目录会有一个干净的 src 目录、prisma 目录和 .env.example 文件，说明基础骨架已经搭好。

关于包管理器，还有个容易踩的坑：脚手架默认支持 npm、pnpm、yarn、bun，但选哪个最好从最开始就固定下来，不要中途切换。因为 pnpm 和 npm 装出来的依赖树结构有差异，切换到另一个包管理器后，偶尔会出现 node_modules 里的软链接异常，导致 Next.js 重启时各种奇怪的 “module not found”。我在 t3code 项目里遇到过了一次这种问题，后来统一用 pnpm、删掉 node_modules 重新 install 才恢复。

接下来第一件事是复制 .env.example 为 .env，把数据库连接串和 NextAuth 的密钥填上。很多新手在这步卡住，因为看一眼 .env.example 会觉得字段有点多。其实核心就两个：DATABASE_URL 指向你的数据库，NEXTAUTH_SECRET 是加密 session 的密钥。本地开发可以先用一个随机的强密码字符串，上线前记得换掉。至于 NEXTAUTH_URL，新版脚手架里基本会自动推断，本地开发可以暂时不管，但部署时如果遇到回调地址不对，多半是它配置出了问题。

2.2 目录结构设计：前后端职责的一次性梳理

项目生成后，目录结构大概是这样：

src/ app/ api/auth/[...nextauth]/route.ts layout.tsx page.tsx server/ api/ routers/ post.ts user.ts root.ts trpc.ts auth.ts db.ts trpc/ server.ts client.ts query-client.ts styles/ globals.css prisma/ schema.prisma

这里最关键的是 src/server 和 src/trpc 两个目录的划分。src/server 是纯后端区域，专门放数据库客户端、鉴权逻辑和 tRPC 路由定义；src/trpc 是前后端共享的 tRPC 工具层，负责创建服务端调用上下文、客户端请求入口。页面组件想调后端数据，从 src/trpc 导入 API，而不是直接从 src/server 导入。这个约定非常重要，一旦理解了它，就不会出现“服务端代码被客户端组件意外打包”的问题。

在 tRPC 的设计里，所有的业务接口都被组织成一棵“路由树”，根节点在 src/server/api/root.ts 里聚合所有子路由，然后通过 createTRPCRouter 注册成 appRouter。页面端使用的类型，就是从 appRouter 的类型里自动推导出来的。组件里只需要写：

import { api } from "~/trpc/react";

这个 api 对象会天然带上完整的类型信息，后端有个路由叫 user.byId，前端用 api.user.byId.useQuery({ id: 1 }) 的时候，IDE 会直接告诉你入参、返回值是什么类型。不用定义任何 helper 函数，也不用在客户端维护一份接口类型的副本。这种“类型从服务器流向客户端”的设计，是 t3code 项目里我使用频率最高、也最省心的机制。

2.3 配置文件中容易忽略的联动关系

脚手架生成的项目有几个配置文件值得单独说，因为它们不是各管各的，而是互相联动的。首先是 .env，它决定 Prisma 连接哪个数据库、NextAuth 用什么密钥、tRPC 某些环境变量是否开启。改数据库连接后，不光 Prisma 要用，连 Next.js 服务端的依赖都会隐式关联，所以换库时最好一条龙操作：改 .env → 跑 prisma migrate → 重启 dev server。

其次是 tsconfig.json。T3 模板里默认配了路径别名，比如 @/ 和 ~/ 都指向 src 根目录。如果团队惯用根路径引用，建议统一用 ~；如果习惯花括号 @props 这种写法，用 @/ 也顺。但要注意，改了 tsconfig 里的 paths，Next.js 的编译器也会读同一份配置，两边是通的，不需要在 next.config 里再配一遍 resolve.alias。这块是 Next.js 特意做通的，比常规 Webpack/Vite 项目方便很多。

最后是 tailwind.config.ts 和 postcss.config。T3 脚手架已经帮我们接好了 content 路径，告诉 Tailwind 去扫描哪些文件。你在 tailwind.config 里加自定义颜色、字体时，要注意 src/app（页面）、src/components（组件）这些目录必须在 content 列表里，否则样式会莫名消失。这类问题排查起来很隐蔽，因为不是报错，而是“我的类名明明写了怎么没生效”。我之前在 t3code 项目里就遇到过 Tailwind 扫描目录不全导致的样式丢失，最后是打开浏览器看编译产物才发现样式压根没有生成。

3. 核心功能实现：以用户管理系统为例

3.1 数据模型设计与Prisma迁移

t3code 这个项目里，我先实现的是最典型的用户管理模块：用户表、角色字段、创建时间、最后登录时间，再加一张操作日志表。用 Prisma 定义 schema，非常直观：

model User { id String @id @default(cuid()) name String? email String? @unique passwordHash String? role String @default("USER") createdAt DateTime @default(now()) updatedAt DateTime @updatedAt logs Log[] } model Log { id String @id @default(cuid()) action String userId String? user User? @relation(fields: [userId], references: [id]) createdAt DateTime @default(now()) }

定义好 schema 之后，跑：

pnpm prisma migrate dev --name init

这条命令做了三件事：把 schema 和现有数据库状态对比，生成 SQL 迁移文件；执行迁移；重新生成 Prisma Client。核心好处是数据库结构从此能进入版本管理，之后的每次改动都有迹可循——想回滚到某个状态，看迁移历史就够了。很多项目数据库结构一乱，一大半原因是“直接手改数据库表结构，没走迁移”，用 Prisma 这种 ORM 配合迁移文件，就从源头上掐掉了这个问题。

设计字段时有几个细节可以参考：主键用 cuid 而不是自增 id，好处是分布式环境下生成 ID 不需要依赖数据库的自增计数器，也避免了暴露业务数据量。密码字段直接存 hash，不要明文，这个不用多说。另外 role 字段用字符串而不是枚举，是因为业务扩展时角色类型会变，字符串类型在 Prisma 里改动成本最低。等角色类型稳定了，再迁成 enum 也不迟。

3.2 tRPC接口定义与类型推导

数据层准备好了，就轮到 tRPC 路由。先看一个简单例子，查询当前用户列表和单个用户：

import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; import { db } from "~/server/db"; export const userRouter = createTRPCRouter({ list: publicProcedure.query(async () => { return await db.user.findMany({ orderBy: { createdAt: "desc" }, }); }), byId: publicProcedure .input(z.object({ id: z.string().min(1) })) .query(async ({ input }) => { return await db.user.findUnique({ where: { id: input.id } }); }), });

注意这里的 publicProcedure 是公开过程，任何人都可以调用。业务里真正的查询通常要登录权限，后面第 3.4 节会说怎么变成 protectedProcedure。这组代码最值得品的是：list 和 byId 的返回类型，会完全由 Prisma 查出来的真实类型推导。你先不用管前端如何传类型，只要后端字段变了，前端引用该接口的组件在编译时就会收到红色波浪线。这种体验，是“前后端各写各的类型，靠吼同步”永远达不到的。

入参校验用 zod，这是 t3code 项目里我强烈推荐的组合。zod 的好处是可以把校验完全声明化，比如 email 字段校验、字符串长度限制，用一个 schema 对象就能描述清楚，而且这个 schema 还能拿到前端做表单校验复用，一鱼两吃。我在实际项目里把“输入校验要不要做”从口头约定变成了强制约束——只要用了 tRPC，接口天然有校验壳，越界请求直接被拦住，不再出现那种“前端传了空字符串，后端也没检查，导致数据库某个 NotNull 字段炸掉”的线上事故。

3.3 页面接入与React Query的配合

tRPC 背后挂的是 React Query（TanStack Query），脚手架已经注册好了 QueryClient 和 Provider。所以前端调用后端的写法极简，以用户列表为例：

import { api } from "~/trpc/react"; export default function UserTable() { const { data, isLoading, error } = api.user.list.useQuery(); if (isLoading) return <div>加载中...</div>; if (error) return <div>出错了：{error.message}</div>; return ( <table> {data?.map((user) => ( <tr key={user.id}> <td>{user.name}</td> <td>{user.email}</td> <td>{user.role}</td> </tr> ))} </table> ); }

没有手动写 fetch、没有 axios 请求地址拼接、没有 useLayoutEffect 触发加载，所有加载态、缓存、重试、错误处理都由 React Query 在背后接管。像 api.user.list.useQuery() 这种调用返回的 data 类型，就是后端 list 的真实返回类型。它不是“挂着 Promise 的盒子”，而是一等一的 TypeScript 原生类型。

写修改操作也差不多，用 useMutation，比如删除用户的按钮：

const deleteUser = api.user.delete.useMutation({ onSuccess: () => { utils.user.list.invalidate(); }, });

注意一行关键逻辑：调用成功后，用 invalidate 刷新列表缓存。这是 React Query 的核心心智——用“缓存失效”代替“手动重新请求”。刚开始用容易忘，但养成习惯后，你会发现页面数据永远跟新，不再需要在接口回调里 setState 一份数据再手动合并。至于 delete 这个 mutation 的入参类型，同样自动推导，传少了或传错了类型，编译期直接拦下来。

3.4 登录态与权限控制

tRPC 的公开过程只能用于确实不需要登录的接口，比如首页展示数据、找回密码之类。一旦业务要求“必须登录才能操作”，要换成 protectedProcedure。T3 脚手架里这两者都准备好了，保护过程在 src/server/api/trpc.ts 里定义：

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

这里的 ctx.session 就是 NextAuth 注入的用户会话。底层逻辑是：每次 tRPC 请求进来时，通过中间件从 NextAuth 的 session 读取登录态，把 user 信息挂到 context 上；protectedProcedure 先检查有没有用户，没有就直接抛 Unauthorized 错误，有才继续执行。页面端要做鉴权，可以配合中间件或根据 session 状态跳转，但最核心的防护一定在 server 端，这件事不能想当然。

我用 t3code 实践过的一个比较完整的鉴权流程是：用户登录（NextAuth 支持 Credentials 或 OAuth）→ session 写入 cookie → tRPC 请求自动携带凭证 → protectedProcedure 校验 → 业务逻辑根据 ctx.session.user.role 判断是普通用户还是管理员，再决定是否放行。管理员接口可以再做一层 adminProcedure，在 protectedProcedure 的基础上多判断一个 role 字段。分层之后，“能查列表”和“能删用户”这两个权限就被天然隔开了，权限模型可以平滑地从小系统扩展到多角色系统。

注意：权限判断必须在服务端完成，不要只依赖页面跳转和按钮显隐。前端隐藏按钮只是体验优化，真正的安全防线永远是服务端那条 procedure。

4. 部署、性能与常见问题排查

4.1 部署平台与数据库连接串的几个坑

t3code 项目我最后部署在 Vercel，理由很简单：Next.js 官方托管、默认支持 Serverless、零配置支持 tRPC 的 HTTP 层。但部署过程绝不是“连上就行”，有几个坑必须提前埋好避雷针。

第一个坑是环境变量。部署平台的环境变量区域里要填一份和本地 .env 一致的变量，否则线上直接连不上数据库。我犯过一次低级错误：本地和线上各用一套数据库，却把本地数据库连接串带了上去，导致线上功能调通后第二天数据全写到开发库了。建议生产环境的数据库连接串、NextAuth 密钥、以及可能的第三方 API key，全部单独维护，且不要提交进 git 仓库。

第二个坑是 Prisma Client 的生成时机。本地开发时我们经常在 postinstall 或手动执行 prisma generate，把 client 生成到 node_modules 里，但部署到 Serverless 平台时构建环境是临时目录，没有本地的 node_modules 缓存。我建议在 package.json 的 postinstall 脚本里加一行 prisma generate，确保每次部署时重新生成，避免“找不到 PrismaClient”这类低级报错。另外，如果数据库是外部服务，要在部署平台的后台放行对应地域的访问，最好用环境变量区分 dev 和 prod 连接串。

第三个坑是 Serverless 环境下 NextAuth 的 session 策略。Serverless 函数按需冷启动，如果数据库连接是常驻连接，高峰期容易把连接池打满。Prisma 连接池大小默认是 CPU 核数的两倍加一，在 Serverless 里每个实例都会持有若干连接，可能出现 too many connections。我实践下来相对稳妥的做法是：只建立一个 PrismaClient 单例，并采用连接复用方案，避免冷启动时反复建立新连接。

4.2 热更新失效与缓存问题

开发 t3code 的时候我遇到过几次“改了代码但页面完全不变”的情况，多半不是代码逻辑问题，而是开发服务器的缓存和工作流卡住了。最典型的场景：改完 Prisma schema 后没有重新生成 client，tRPC 路由引用的 model 就不存在了，Next.js dev server 却还在用旧的类型缓存，表现就是不报错但功能异常。这种问题排查办法很直接：先执行 prisma generate，再重启 dev server，如果还不行，删掉 .next 目录重启。

另一个容易迷惑的是 React Query 缓存。修改后端接口的返回结构后，前端 useQuery 的 data 还是旧结构，因为 React Query 会在一定时间内复用缓存，不重新发请求。这不是 bug，是缓存机制本身的行为。要强制刷新，可以在浏览器强制刷新、用 devtools 的 invalidate，或者调整 query 默认的 staleTime。我在项目里就把 staleTime 从默认的 0 改成 5 秒，既保证了数据的及时性，又减少了无效请求。

4.3 tRPC类型不更新的经典排查

tRPC 的类型是从服务端推导到客户端的，这在设计上很优雅，但也带来一个特性：如果你改了后端 router 的入参或返回类型，前端组件里不会立刻看到新的类型，因为 TypeScript 的类型推导需要一次“类型收集”。很多新手以为是自己代码写错了，实际上只是类型缓存没刷新。

正确的处理姿势是：改了 router 文件后，等一两秒让 TS 完成收集；如果前端还是老的类型，直接重启终端里的 dev server，或者重启 IDE 的 TS server。在 VS Code 里可以按 Ctrl+Shift+P 调出 “TypeScript: Restart TS server”，基本立刻生效。这里要特别提醒：不要为图方便绕过类型推导，比如在 useQuery 时强转 as any，一旦你开始这么干，收益就全没了，类型系统就形同虚设。

还有一个真实遇到过的问题：服务端返回对象里包含了 Date 类型，前端拿到的数据却不是 Date，而是字符串。这不是类型错误，是 HTTP 传输时 Date 被序列化成了 ISO 字符串。解决方案很简单，在 tRPC 的 link 层配置 superjson 这类转换器，让 Date 类型在序列化时保留格式。T3 栈自带 superjson 支持，需要在服务端初始化 tRPC 时启用，位置在 src/trpc/server.ts 里配置 transformer，在客户端也要保持一致。这个问题处理不当，会出现“编译类型是 Date，运行时是 string”，属于最坑的运行时类型错觉。

5. 让我效率翻倍的经验技巧

5.1 把zod schema变成前后端共享校验的“契约”

前面提到过 zod schema 可以在前端复用。具体做法是把常用的校验逻辑抽成独立文件，放到 src/server/validation 或 src/shared 目录。比如注册用户时，邮箱格式、密码强度的校验规则，后端 tRPC 过程直接使用这个 schema 做 input 校验，前端表单组件在 onSubmit 前也用同一个 schema 做预检。这样前后端就共用了同一套校验规则，不会出现“前端说密码必须 8 位，后端实际没限制”的尴尬。

一个 zod schema 还能通过 z.infer 自动产出 TypeScript 类型：

const signupInput = z.object({ email: z.string().email(), password: z.string().min(8), }); type SignupInput = z.infer<typeof signupInput>;

这样定义一次，类型、校验、文档三合一。我在 t3code 项目里品尝到这种方案的甜头之后，基本上所有新增接口都会先写 zod，再写业务逻辑，开发顺序彻底变了。你不再需要担心接口入参格式失控，因为每个接口的入参都有一层声明式校验罩着。

5.2 封装通用Hook，让列表页少写一堆样板

React Query 的 useQuery 用起来方便，但每次调用都要写 data、isLoading、error 三件套也烦。我在项目里按业务场景封装了几个通用 Hook，比如 useUserList、useLogList，内部统一处理加载态、空数据、错误、刷新时机。这样业务组件里只需要一行代码拿数据，后面想加权限判断或者额外过滤条件，只改 Hook，不用动每个页面组件。封装拆得好不好，直接决定大型功能迭代的幸福感。

封装 Hook 时留意一个原则：不要让 Hook 隐藏太多类型信息。返回的数据类型、参数类型要明确，并且在函数签名上讲清楚，否则团队里的人用 Hook 时需要猜返回结构，就废掉了类型安全的优势。具体做法是：Hook 的返回值直接复用 useQuery 的推断类型，不手动声明成 any。一旦为了省事把类型抹掉，后面的所有调用点都会失去保护，得不偿失。

5.3 调试时善用日志链路

tRPC 调用过程是黑盒还是透明，完全取决于调试手段。我在项目里给 tRPC 加了一个简单的 requestId 中间件，在每个请求前后打印日志，把方法名、入参、耗时、状态码记录下来。线上排查问题时，日志往往是突破口。比如之前线上出现某个接口慢，就是通过耗时日志定位到是因为某个列表查询没有加索引，而不是业务逻辑问题。

日常开发也可以善用浏览器 network 面板，查看 tRPC 请求的地址、响应格式。tRPC 的 HTTP 层走的是 POST，URL 通常是 trpc/user.list?input=...，看起来不直观，但请求体本身就是 JSON。多观察几次，就会习惯这套协议。我不太建议在调试上堆一堆炫酷工具，一条可靠日志链路比任何花哨工具都实用。

5.4 定期清理依赖与构建产物

T3 全家桶依赖不少，随着功能扩展，node_modules 体积会肉眼可见地膨胀。我养成的习惯是每隔几周做一次 pnpm outdated，看看哪些大版本升级；同时定期 pnpm prune，清掉没有再引用的包。另一方面，部署到线上后，本地构建产生的 .next 目录也会占不少磁盘空间，记得清，否则下次构建变慢，还容易被旧缓存坑。

还有一个很多人不知道的细节：dev server 跑久了，Next.js 的缓存会出现一些莫名其妙的“代码没生效”情况。遇到这种问题，别在代码里反复改，先停掉 dev server，删掉 .next，重新启动。这个操作看似简单，却能解决我遇到的 70% 的诡异开发问题，是性价比最高的一招。

最后再分享一个使用感受。t3code 这个项目跑了几个迭代后，我最大的收获不是某个库怎么用，而是这套“类型即文档、编译期能找到问题”的开发节奏。因为 tRPC 把前后端的接口边界变成了 TypeScript 编译器能检查的对象，很多过去要开会确认、靠文档同步、靠联调找 bug 的事情，都消失在类型系统里了。如果你也被“前后端类型不一致”“改个字段要全局搜索”折磨过，真的值得花一两天把 T3 这套东西完整跑一遍——先做一个只需要登录和 CRUD 的骨架，把流程走通，再往里填业务。上手门槛没那么高，但一旦适应这种开发模式，回头再写老式全栈项目，你会觉得处处别扭。这就是我眼中 T3 生态最大的价值。