企业官网建设流程全解析

如果你过去两年在开发者社区里逛过，大概率见过一个叫 T3 Stack 的缩写。它不是一个新的框架，而是把 Next.js、TypeScript、Tailwind CSS、tRPC、Prisma、NextAuth.js 这套组合打包成一套最佳实践，通过 create-t3-app 这个脚手架，让你几十秒内拉出一个前端后端一体、类型安全贯穿始终的全栈项目。t3code 拆开看，其实就是 T3 生态里“以代码为主线”的实操视角——不聊理念，只看怎么把这一套东西真实落地。

这篇文章适合两类人：一类是听说过 T3 Stack 但一直没动手、想知道它到底解决什么问题的前端开发者；另一类是用过脚手架但遇到类型报错、部署失败、数据联动写不明白的全栈新手。我会从选型逻辑讲到目录结构，从 tRPC 路由链路讲到 Prisma 数据建模，最后把我在多个项目里踩过的坑和排查思路一并整理出来。全程没有玄学，所有结论都基于可复现的代码和配置。

1. 我为什么最终选了 T3 这套组合拳

1.1 T3 的核心理念：类型安全贯穿到底

T3 Stack 与其它全栈方案最大的区别，在于它把“类型安全”当成一等公民，而不是事后补救。传统的前后端分离项目里，前端用 axios 请求接口，后端返回 JSON，前端拿到的是一个 any。一旦后端改了字段名，前端不会在编译期报错，要等运行时才发现，这时候往往已经在生产环境了。

T3 Stack 的思路完全不同：Next.js 负责页面和 API 路由，tRPC 让你在后端写一个 procedure，前端直接通过一个类型安全的 client 调用，不需要生成 API 文档，不需要手写请求封装。Prisma 作为 ORM，定义了数据库表结构之后，会自动生成完整的 TypeScript 类型。也就是说，从数据库到后端路由到前端组件，整条链路的类型是“长”在一起的。改了一个字段，所有引用它的地方全部在编译期报红。

1.2 这套技术栈到底能解决哪些痛点

我最早做全栈项目用的是 Express + React，那时候最大的痛苦是接口文档维护。后端改一个参数，前端不知道，测试那边也不清楚，最后只能靠人肉口头传达。后来换过 GraphQL，类型是有了，但一套 schema 语言 + resolver + 前端 codegen，光配置就是不小的学习成本，对小项目来说是严重过载。

T3 Stack 的价值恰恰在于“刚好够用”。tRPC 不需要 schema 文件，不需要 codegen，它直接用 TypeScript 的 typeof 推断把后端路由的类型暴露给前端。你写一个 router，前端 import 之后自动获得智能提示，就像在调用本地函数一样。Prisma 则解决了 SQL 手写容易出错的问题，schema 即文档，迁移脚本自动生成，团队协作时不再需要口头确认表结构。

选这套组合还有一个现实考量：生态成熟度。Next.js 是 Vercel 主导的 React 框架，TypeScript 是主流语言的默认选择，Tailwind 的 utility class 方案已经被大量生产项目验证，Prisma 在 ORM 领域用户量巨大。T3 只是把这几块拼在一起，并没有引入什么“野路子”依赖，这意味着踩坑时有大量的社区解决方案可以参考，不必担心项目做到一半无依无靠。

2. 项目初始化与目录结构解析

2.1 脚手架安装与参数选择

创建一个 T3 项目非常简单，在终端里执行：

npm create t3-app@latest

接着它会问你要不要启用特定功能。我的建议是：新项目全部勾上，包括 NextAuth.js、Prisma、Tailwind CSS、tRPC。也许你会觉得 NextAuth 这东西用不上，但 T3 的脚手架已经把它的类型集成做好了，后续真要加登录的时候，你会发现省掉的配置时间远超现在多点的这一步。

初始化完成后，T3 会默认启用 Strict Mode TypeScript，这意味着代码里不允许隐式 any，每个变量都得有明确类型。刚开始会有点烦，但经过一段时间你会发现运行时出 bug 的概率明显下降。生产环境里多花两分钟写类型，换来的是半夜不需要被报警电话叫醒，这笔账很划算。

需要注意的是，create-t3-app 默认推荐的包管理器是 npm，但如果你本地装了 pnpm 或 yarn，你也可以使用它们。我个人一直用 pnpm，依赖安装速度和磁盘占用都更友好。不过有一点要提前说清楚：如果你用 pnpm 安装后发现某些依赖版本冲突，先检查 lockfile 是否正常，T3 和 Prisma 相关的依赖对版本比较敏感，不要随意用 --force 去解。

2.2 核心目录结构与“约定大于配置”

项目生成后，你会看到这样的结构：

├── prisma/ │ └── schema.prisma ├── src/ │ ├── pages/ │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ ├── trpc.ts │ │ │ └── root.ts │ │ ├── auth.ts │ │ └── db.ts

最需要理解的是src/server/api/这个目录。T3 把后端代码全部集中在这里，root.ts负责把所有子路由汇总成一个 appRouter，trpc.ts定义了 tRPC 的初始化实例和中间件逻辑，routers/目录放具体业务路由。src/server/db.ts导出 Prisma Client 单例，所有路由都通过它访问数据库。

这里有一个很多新手容易踩的坑：不要把业务逻辑写到 pages/api 里。T3 虽然保留了 Next.js 的 API 路由能力，但在 tRPC 的架构下，pages/api 只用于 NextAuth 的回调接口，真正的接口逻辑全部走 tRPC。如果把两者混用，类型安全和统一错误处理都会失效，等于自废武功。

Tailwind 的配置文件是tailwind.config.ts，主题色、字体、断点都在这里扩展。T3 默认生成的样式文件在src/styles/globals.css，通过@tailwind base; @tailwind components; @tailwind utilities;三条指令引入。很多教程会教你直接改这段 CSS，但我建议把自定义样式放在单独的 CSS 文件里，globals.css 保持简介，后期维护会轻松很多。

3. 关键环节落地：tRPC 路由与 Prisma 数据层

3.1 Prisma Schema 设计与数据库连接

Prisma 的起点是 schema 文件。我在实际项目中常用 PostgreSQL，下面是一段真实的模型设计示例：

model User { id String @id @default(cuid()) name String? email String? @unique emailVerified DateTime? image String? accounts Account[] sessions Session[] posts Post[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Post { id String @id @default(cuid()) title String content String published Boolean @default(false) authorId String author User @relation(fields: [authorId], references: [id]) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

@default(cuid())这个选择很关键。很多人习惯用自增 id，但在分布式部署或团队协作时，自增 id 容易产生冲突和遍历安全问题。cuid 这种随机字符串 id 不需要查询数据库就能在应用层生成，适合在服务端创建记录时直接使用。

写完 schema 之后要同步到数据库：

npx prisma migrate dev --name init

这个命令会生成一个迁移文件并应用到本地数据库，同时自动生成 Prisma Client。生成后的 client 会在node_modules/.prisma/client里，TypeScript 类型直接可以从那里导入。

如果你在团队协作，注意prisma/migrations目录要提交到 Git，schema.prisma 的改动必须走迁移而不是直接改数据库，否则同事同步代码后运行环境就跟不上数据表结构，这一块的教训我在第四节会详细讲。

3.2 从 Service 到 Procedure：tRPC 路由的完整链路

T3 里的“接口”叫 procedure，分为 query 和 mutation 两种：query 做查数据，mutation 做增删改。来看一个真实的例子，src/server/api/routers/post.ts：

import { z } from "zod"; import { createTRPCRouter, protectedProcedure, publicProcedure } from "@/server/api/trpc"; export const postRouter = createTRPCRouter({ list: publicProcedure.query(async ({ ctx }) => { return ctx.db.post.findMany({ orderBy: { createdAt: "desc" }, take: 50, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1).max(100), content: z.string().min(1), }) ) .mutation(async ({ ctx, input }) => { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });

注意create用的是protectedProcedure，它要求用户已登录，未登录时 tRPC 会直接返回 UNAUTHORIZED，不用自己在业务代码里写 if else。这就是为什么我说 T3 脚手架里集成 NextAuth 的价值其实很大，因为protectedProcedure和未登录跳转都已经帮你接好了。

zod在这里完成了 input 的运行时校验。前端传一个空字符串标题会直接报错，而不是等写进数据库才发现问题。同时 zod 的类型推断会自动应用到前端，前端在调用create时，如果没有传 title 字段，编辑器里直接就会标红。

最后记得在root.ts里挂载这个路由：

export const appRouter = createTRPCRouter({ post: postRouter, user: userRouter, });

只有挂载到 appRouter 里，前端才能访问到对应的 procedure。

3.3 前端调用：类型安全如何帮你少写 bug

后端写完之后，前端调用非常简单，不需要手写 fetch，不需要根据接口文档去拼 URL。页面里的用法是这样：

import { api } from "@/utils/api"; const posts = api.post.list.useQuery(); const createPost = api.post.create.useMutation({ onSuccess: () => { utils.post.list.invalidate(); }, });

api.post.list这个对象之所以存在，是因为@/utils/api里导出的api是基于后端 appRouter 的类型推断出来的。前后端共享同一份类型来源，删掉一个路由、改一个输入参数，前端会立刻编译报错。这种“接口即代码”的体验，用惯之后就回不去了。

这里我特别想讲一下invalidate的用法。它在 mutation 成功后让对应的 query 重新拉取数据。很多人会在 mutation 里手动 setState 去更新页面列表，其实没必要。tRPC 的缓存机制天然支持失效重取，你可以把utils.post.list.invalidate()看作用户手动刷新页面。页面会自动请求最新数据，UI 和数据永远是同步的。

如果某个 mutation 需要乐观更新（比如点击点赞按钮后立刻显示 +1），可以通过setData直接在缓存里写入预期结果。但除非交互要求极高，我建议先从invalidate入手，因为乐观更新在失败回滚时容易出问题，不如失效重取来得简单可靠。

4. 部署与生产环境配置

4.1 环境变量与数据库连接的组

T3 项目里有三个核心环境变量：DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL。如果用了 GitHub OAuth 等登录方式，还需要GITHUB_CLIENT_ID和GITHUB_CLIENT_SECRET。开发环境下这些都写在.env文件里，T3 的脚手架会帮你生成.env.example作为模板。

一个常见的部署事故是：本地跑得好好的，部署到服务器后所有数据库操作全部报错。排查到最后发现是.env文件没有复制到生产环境，或者DATABASE_URL指向了本地 localhost。为了避免这种问题，我强烈建议部署时用一个环境管理工具（比如 Vercel 的 Environment Variables 面板）统一管理，不要手动 SSH 到服务器上改.env，否则一旦服务重建，配置就丢失了。

NEXTAUTH_SECRET这个值可以用openssl rand -base64 32生成，不能直接复制别人文档里的示例值。它是用来加密 session cookie 的密钥，如果每次重启服务都换一个 secret，所有在线用户的登录态都会被强制退出。所以生成后要妥善保存。

数据库连接串还需要注意 Prisma 的连接池配置。如果你用的是 PostgreSQL，默认连接串是postgresql://user:password@host:5432/dbname，可以在末尾加?connection_limit=5和?pool_timeout=10。尤其当你的应用跑在 Serverless 环境下，每个请求都会实例化一次 Prisma Client，连接数消耗极快。T3 的src/server/db.ts已经做了全局单例处理，但连接串里的连接池参数仍然需要按你实际的数据库规格调整。

举个例子：如果数据库最大连接数是 100，每个 Serverless 实例又有冷启动的特性，那么并发上来之后极可能打满连接数。你可以用 PgBouncer 这类连接池代理工具，或者直接在连接串上调低connection_limit。我自己的经验是取 10 到 20，既能保证不撑爆数据库，又不会让并发请求排队太久。

4.2 构建优化与静态生成策略

Next.js 的页面支持三种渲染模式：静态生成（SSG）、服务端渲染（SSR）、客户端渲染（CSR）。T3 项目里默认是 SSR，因为你可能用到了getServerSession来获取用户登录态。但如果某个页面内容是全局公开的，例如博客首页的文章列表，你可以主动加export const revalidate = 60启用增量静态再生成（ISR），这样页面 60 秒内不会重新请求服务端资源，对数据库的压力会小很多。

这里有一个细节容易被忽略：tRPC 的 query 如果在客户端组件里调用，默认会先发一次请求到服务端，然后客户端再发一次。为了让数据在 SSR 阶段就准备好，Next.js 的serverSideProps里可以直接通过createCaller调用 tRPC 路由，而不需要发起 http 请求。T3 文档里推荐这种方式，但它要求你处理好 context 里的 session。如果项目中大多数数据请求都需要登录态，我建议直接用客户端 query 就行，SSR 阶段的性能收益对后台管理系统来说并不明显。

部署平台的选择上，我一般优先 Vercel，因为 Next.js 就是它的核心产品，构建缓存、边缘网络等优化都很省心。如果你需要部署在自己的服务器上，可以用 Docker，但一定要在 Dockerfile 里先复制 prisma 目录并执行prisma generate，因为 Prisma Client 是和 schema 绑定的。很多人在 Docker 构建时报错 Prisma Client 找不到，就是忽略了这一步。

4.3 日志与错误上报的设置

生产环境出问题，最怕的就是没有日志。我在 T3 项目里用两个工具：Sentry 负责前端异常和 API 错误上报，Pino 负责服务端结构化日志。tRPC 的错误可以通过 errorFormatter 统一处理，比如把 ZodError 的字段校验错误转成用户友好的中文提示。

src/server/api/trpc.ts里有一个errorFormatter，默认把错误类型转成 HTTP 状态码。你可以在这里扩展业务码，比如把UNAUTHORIZED变成 401，把INTERNAL_SERVER_ERROR变成 500。在前端捕获错误时，建议用api.post.create.useMutation().error.message展示给用户，而不是只弹一个“请求失败”。

5. 实际踩坑记录与排查思路

5.1 常见报错与解决方案速查

整理几个我在真实项目中经常遇到的 T3 报错，供你对照排查：

其中最容易忽略的是NEXTAUTH_SECRET不一致的问题。当你本地用一套 secret 登录过，然后把代码部署到线上时，如果线上的 secret 不一样，原来本地的 session cookie 是无法通过的。这通常不算 bug，但你会误以为登录逻辑坏了。解决办法是统一 secret，或者在切换环境时清掉浏览器缓存。

5.2 数据联动失效与缓存谜题

我在一个社区项目中写过这样的逻辑：用户发帖成功后需要刷新帖子列表和用户主页的帖子数。第一次实现时，我只调用了utils.post.list.invalidate()，结果用户主页的帖子数没变。原因是帖子数走的是另一个 query，比如api.user.getStats，它没有失效，所以缓存里还是旧数据。

正确做法是让同一个 mutation 的 onSuccess 里同时失效所有相关的 query。tRPC 对缓存的处理基于路径前缀，你可以调用utils.post.list.invalidate()、utils.user.getStats.invalidate()一起刷新。或者更省事一点，直接用utils.invalidate()清空所有缓存，但这样性能会差一些，不适合频繁操作。

还有一个经验：invalidate是异步的，mutation 的 onSuccess 里如果紧接着做跳转，页面可能先渲染了旧数据。虽然紧接着会触发重新拉取，但视觉上会有闪动。如果想要无缝体验，用await等待失效完成再跳转，或者用setData写入最新数据。

5.3 schema 变更导致的前后端类型断裂

T3 项目的类型安全是一把双刃剑：它保护你，但也意味着一次 schema 变更会波及到十几处代码。我在一次重构里把字段content改成了body，结果编译器直接报出 25 处错误。初次遇到会觉得很烦，但冷静下来想想，这些错误如果等发布后用户访问才暴露出来，后果严重得多。

处理这种大面积类型报错，我推荐一个顺序：先改 Prisma schema 并执行迁移，npx prisma migrate dev会同时重新生成 client；然后修改 server/routers 里的返回字段；最后修前端引用。因为 tRPC 的类型是从后端传导到前端的，后端不更新，前端永远会报错。按这个顺序来，报错数量会逐渐收敛，不会出现前后端互相干扰的情况。

5.4 独家的项目瘦身技巧

最后分享一个细节：T3 默认会在package.json里包含@types/node、eslint-config-next等大量 devDependencies。生产环境部署时，如果不小心用了npm install --production或者 Docker 里只安装 dependencies，Prisma Client 很可能因为缺少生成工具而报错。我建议 Docker 构建时分成多阶段：第一阶段完整安装依赖并执行prisma generate，第二阶段只拷贝.next产物和 node_modules 到运行镜像。这样既不会让镜像膨胀到几百 MB，又能保证 Prisma Client 完整可用。

写在最后的使用体会

做全栈开发这几年，我最大的感受是：工具链的意义不在于让你写更少的代码，而在于让你犯更少的低级错误。T3 Stack 的价值其实就是把它想做的事情做透——数据库字段和页面取数之间的类型流转、登录态在前后端之间的自动传递、缓存失效的标准化处理。这些能力单独看都像是“小优化”，但真正在多人协作的项目里，每一条都能省下大量的沟通成本。

如果你正准备新开一个全栈项目，我的建议是先别急着把大而全的架构设计好，用 T3 把最小闭环跑通。等业务扩张到需要拆分服务、引入消息队列或上微前端的时候，你会发现这套代码的边界依然清晰。类型不会说谎，它在编译期告诉你的问题，往往比你自己慢慢排查出来的更多、更准。希望这篇文章能让你少走一点我走过的弯路。