企业官网建设流程全解析

做全栈开发的人大概率都有过这种经历：后端把接口文档写好，前端照着文档手写类型定义，联调时后端悄悄改了一个字段名，前端页面直接白屏，查了半天才发现是类型没对上。我第一次接触 t3code，就是在一次被这种问题折磨到不行的项目重构讨论里。t3code 本质上是把 T3 Stack 这套“端到端类型安全”的理念落成一整套可复用的项目范式，核心就一句话：用 TypeScript 把后端数据模型、接口、前端调用串成一条类型互通的链路，让编译期替你抓住联调阶段最常见的错误。这篇文章我会把它的设计思路、技术选型逻辑、从零搭建的完整过程、以及落地过程中踩过的坑，一次性讲清楚，适合正在做全栈项目、以及被前后端联调和类型维护折磨过的开发者参考。

1. t3code 项目范式：看起来是工具，本质是一套协作方式

1.1 从 T3 Stack 说起

T3 Stack 这个名字最早来自社区里流行的一组技术组合，T 代表 TypeScript、Tailwind CSS、tRPC，后来实践中大家几乎都会加入 Prisma 补全数据访问层。t3code 这类项目名在社区里通常指的就是“以 T3 技术栈为基础的全栈代码模板或脚手架”，它不是一个需要单独安装的框架，而是一个把上述技术按照特定方式组织起来的项目骨架。你可以把它理解为一套“装修标准”：不规定你用哪面墙、哪个地板，但规定水电怎么走、图纸怎么画、各个环节怎么交接。

换言之，t3code 的价值不在某个单一框架，而在框架之间的衔接方式。比如 Prisma 定义了数据库模型后，类型能直接生成给后端用；tRPC 把后端函数暴露给前端时，参数和返回值的类型能自动推导到 React 组件里；Zod 负责校验输入，同时把校验规则共享给前端做表单验证。这一套组合下来，从数据库字段到 UI 组件的 props，类型全链路贯通，中间不需要人肉维护任何一份接口定义文件。

1.2 它到底解决了什么问题

传统前后端分离架构里，最痛的不是写代码，而是维护共识。后端写一份 Swagger，前端写一份 API 类型定义，数据库 migration 改一次，Swagger 更新一次，前端类型再改一次，三次修改只要有一次遗漏，联调就开始出鬼故事。t3code 的核心思路是把“共识”变成编译器推导出来的结果：数据库 schema 变了，Prisma Client 类型自动变；后端 router 改了，前端 useQuery 拿到的返回值类型自动变。类型不一致本身变成了编译错误，而不是运行时的白屏。

用生活类比来说，传统模式像是装修队各画各的图纸，电工按自己的理解布线，木工按自己的理解做柜子，等家具进场发现插座被柜子挡住；t3code 模式相当于所有工种共用同一套三维模型，你挪了柜子位置，插座位置在模型里跟着变，冲突在设计阶段就能看见。这个类比基本就是 t3code 解决的问题：消灭信息差，让类型系统成为团队之间的“同一种语言”。

2. 技术选型拆解：为什么是这五个东西组合在一起

2.1 TypeScript 是地基，不是装饰

很多项目用 TypeScript 只是给前端加类型标注，后端还是 JavaScript，这样类型安全就断了一截。t3code 要求全栈 TypeScript，后端接口返回的类型可以无缝流转到前端组件。这里的关键不是“用了 TS”，而是“前后端共享同一套类型推导链”。比如后端一个 Prisma 模型生成的 TypeScript 类型，既能约束 API 返回值，也能让前端的表格组件自动拿到列定义，这不是巧合，而是架构决策的结果。

在实际项目中，我发现很多人会问“到底要不要上 TypeScript 全栈”，我的经验是：只要你的业务里存在跨端数据流转，就必须全栈 TS。纯前端项目只用前端类型没问题，但一旦有 API，类型断裂的成本会随着接口数量呈指数上升。t3code 把 TypeScript 摆在所有技术栈最底层，不是因为它潮，而是因为后面所有步骤——Prisma 生成类型、tRPC 推导类型、Zod 推断类型——都需要一个共同的类型系统作为前提。

2.2 Prisma：让数据库 schema 成为唯一事实来源

Prisma 在 t3code 里的角色很特殊，它既是 ORM，又是类型生成器。你在 schema.prisma 里定义 model User、model Post，执行 prisma migrate 生成数据库表，同时 prisma generate 会生成一套完整的类型定义。这套类型定义可以直接被 router 拿来当返回值类型，前端通过 tRPC 拿到的数据天然带有这些类型信息。

选 Prisma 而不是其他 ORM，一个重要原因是它的多数据库支持和 migration 工作流。开发环境用 SQLite，生产环境切 PostgreSQL，只需改 datasource 配置，模型定义基本不用动。这对个人项目和中小企业项目很友好。另一个原因是它生成的类型非常干净，没有 Hibernate 那种复杂的代理对象心智负担，就是简单的 Plain Object 结构，配合 TypeScript 的 interface 直接可用。

2.3 tRPC：不写 REST，直接“调用函数”

tRPC 是整个链路的关键一环。它跟 REST 或 GraphQL 不同，不定义 URL 路由、不写请求方法、不设计接口文档，而是把后端函数直接暴露给前端调用。前端像调用本地 async 函数一样调用后端的 query 或 mutation，类型自然推导。比如后端定义了 postRouter.list，前端自动得到一个带类型的 useQuery，参数和返回值都能获得完整的编辑器提示和编译期检查。

有人会问，那 REST 是不是就该淘汰了？不是。REST 的价值在于通用性：任何语言、任何客户端都能访问，适合开放 API、跨语言生态对接。tRPC 的价值在于效率：前后端都是 TypeScript 时，不需要维护一套文本协议描述，直接函数调用即可。t3code 之所以选 tRPC，是因为它面向的场景就是“前后端都是自己的、语言都是 TypeScript 的内部 API”，在这种情况下，REST 的很多仪式感是额外负担。

实际使用中我建议把 tRPC 当成一套“带类型推导的 RPC 框架”来理解，而不是什么黑魔法。它底层仍然是 HTTP 请求，只是把序列化和反序列化的细节封装掉了。你可以在任何 React 组件里直接写 const { data } = api.post.list.useQuery()，不用关心它最终请求了哪个 URL，如果哪天需要调试，Network 面板里仍然能看到实际请求。

2.4 Zod：在信任的边界设置安检

Zod 是一个模式校验库，它跟 TypeScript 互补：TS 类型是编译期约束，Zod 是运行期校验器。t3code 里 Zod 通常出现在两个位置：一是 tRPC router 的 input 参数校验，二是环境变量的校验。比如定义一个创建文章的输入模式：

import { z } from "zod"; export const createPostSchema = z.object({ title: z.string().min(1).max(100), content: z.string().min(1), published: z.boolean().default(false), }); export type CreatePostInput = z.infer<typeof createPostSchema>;

这里 z.infer 能从 Zod 模式反推出 TypeScript 类型，一份代码同时产生运行时校验和编译期类型。前端做表单时可以直接复用这套 schema，后端收到请求时先用它校验，校验通过才进入业务逻辑。这样做的好处是，默认情况下外部输入都是“不可信的”，在信任边界做一次校验，后续逻辑就能信任数据。

Zod 的另一个好处是错误信息可定制。比如标题为空时返回“标题不能为空”，而不是笼统的“参数错误”。这在给前端对接错误提示时省了很多事，不需要前端再根据 error code 映射一次文案。t3code 的 api 层通常还会包一层 error formatter，把这些校验错误统一转换成前端容易处理的格式。

2.5 Tailwind CSS：把样式心智负担降到最低

Tailwind 在 t3code 里的角色看着不如前几个重要，实际上很影响开发体验。纯 CSS 或 CSS Modules 最大的问题是命名：每个组件要起类名、维护层级、处理作用域，样式越多心智负担越重。Tailwind 用原子类的方式把常用样式组合成工具类，大多数场景下不需要离开 TSX 文件去写 CSS。

更重要的是 Tailwind 和组件库之间没有绑定，你可以自由组合。t3code 项目里常见做法是 Tailwind + headlessui 或 radix-ui 这类无样式组件，样式自己用 Tailwind 类控制，这样既不会跟组件库内置样式打架，也不会被组件库的设计语言绑架。配合 dark mode 的 class 方案、以及 tailwind.config 里的主题变量定制，基本能覆盖绝大多数 UI 需求。

3. 实操过程：从零搭一个 t3code 风格的完整项目

3.1 初始化项目与目录结构

最省事的方式是使用社区脚手架 create-t3-app 创建基础项目。交互式命令会依次询问你使用哪些模块，建议全选：Next.js、TypeScript、Prisma、tRPC、NextAuth、Tailwind。生成完成后，目录结构大致如下：

. ├── prisma │ └── schema.prisma ├── public ├── src │ ├── env │ │ └── env.mjs │ ├── pages │ │ ├── api │ │ │ └── trpc │ │ │ └── [trpc].ts │ │ └── index.tsx │ ├── server │ │ ├── api │ │ │ ├── root.ts │ │ │ └── routers │ │ │ ├── post.ts │ │ │ └── user.ts │ │ └── db.ts │ └── styles │ └── globals.css ├── package.json └── tsconfig.json

这个目录结构本身就是 t3code 范式的体现：前后端代码都放在 src 下，server 目录放所有服务端逻辑，routers 按业务资源拆分，trpc 的 API 入口是一个 catch-all 路由文件。Next.js 的 pages/api 只用来挂载 tRPC 处理器，不再逐个写 REST 路由，所以这一层非常薄。

初始化后第一件事是检查 env.mjs 里的环境变量。这里用了 Zod 做校验，启动时如果缺 DATABASE_URL 会直接报错，而不是等到查询数据库时才报一个晦涩的错误。我见过不少项目在这个环节偷懒，结果部署时踩坑。t3code 里环境变量校验是标配，强烈建议保留。

3.2 定义数据模型并生成 Prisma Client

以最简单的用户发布文章为例，在 prisma/schema.prisma 里定义模型：

generator client { provider = "prisma-client-js" } datasource db { provider = "sqlite" url = env("DATABASE_URL") } model User { id String @id @default(cuid()) email String @unique name String? posts Post[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } 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 }

写完后依次执行两条命令：

npx prisma migrate dev --name init npx prisma generate

migrate dev 会创建数据库表并生成 migration 文件，generate 会生成本地 Prisma Client。注意顺序不能反，generate 默认按最新 schema 生成，如果数据库还没迁移到最新状态，运行时查库会报表不存在。这个坑我踩过不止一次。对于已有数据的环境，生产环境应该用 prisma migrate deploy，而不是 migrate dev，这一点后面部署部分还会说。

3.3 编写 tRPC Router 与业务逻辑

数据模型定义好后，下一步是暴露 API。t3code 的推荐做法是按资源拆分 router，然后在 root.ts 里合并。先看一个典型的 post router：

import { z } from "zod"; import { createTRPCRouter, protectedProcedure, publicProcedure } from "../trpc"; export const postRouter = createTRPCRouter({ list: publicProcedure .input(z.object({ cursor: z.string().optional() }).optional()) .query(async ({ ctx }) => { const posts = await ctx.db.post.findMany({ orderBy: { createdAt: "desc" }, take: 20, }); return posts; }), create: protectedProcedure .input( z.object({ title: z.string().min(1), 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, }, }); }), });

这里有几个关键点。publicProcedure 表示无需登录可访问，protectedProcedure 表示必须登录，内部通过 ctx.session 拿到当前用户。query 用来读数据，mutation 用来写数据。参数用 Zod 校验后，ctx.db 是 Prisma Client 的实例，在 createTRPCContext 里统一注入，这样每个 router 里都通过 ctx.db 访问数据库，不散落 new PrismaClient 的调用。

关于返回类型，我建议不要直接返回 Prisma 模型实体，尤其不要返回包含密码字段的 User 对象。常见做法是在 router 里用 select 挑选字段，或者映射成 DTO 结构。虽然 Prisma 提供了默认类型，但直接暴露整个实体容易把敏感字段带出去。养成习惯：每次 mutation 返回之前，想一下前端真的需要哪些字段。

root router 合并很简单：

import { createTRPCRouter } from "./trpc"; import { postRouter } from "./routers/post"; import { userRouter } from "./routers/user"; export const appRouter = createTRPCRouter({ post: postRouter, user: userRouter, }); export type AppRouter = typeof appRouter;

AppRouter 类型导出的作用非常重大，它是前后端类型推导的源头。前端所有 API 调用都基于这个类型，所以这个文件里的改动会实时反映到前端的编辑器提示里。

3.4 前端页面接入：类型安全的数据流

前端以 Next.js 页面/组件为入口，通过 react-query 和 tRPC 的 hooks 访问后端。以文章列表页为例：

import { api } from "~/utils/api"; export default function PostListPage() { const { data, isLoading, error } = api.post.list.useQuery(); if (isLoading) return <div>加载中...</div>; if (error) return <div>加载出错：{error.message}</div>; return ( <ul> {data?.map((post) => ( <li key={post.id}> <h2>{post.title}</h2> <p>{post.content}</p> </li> ))} </ul> ); }

api.post.list.useQuery 中的 api 来自 src/utils/api.ts，类型就是 AppRouter。写代码时当你输入 api.post.，编辑器会自动补出 list 和 create，当你拿到 data，编辑器会推导出 Post[]，根本不用查接口文档。任何一个字段名拼错，编译阶段就会报错。这是 t3code 使用体感最直观的时刻。

创建文章的场景也一样：

const utils = api.useUtils(); const createPost = api.post.create.useMutation({ onSuccess: () => { utils.post.list.invalidate(); }, });

mutation 成功后调用 invalidate 让文章列表重新拉取，这个操作几乎成了 t3code 项目的标准动作。相比手动刷新页面或手动拼接新数据，invalidate 让数据同步变得简单可靠。

3.5 环境变量与部署要点

项目写好后，部署往往比本地跑通更容易翻车。先看环境变量校验的典型写法：

import { z } from "zod"; const envSchema = z.object({ DATABASE_URL: z.string().url(), NEXTAUTH_SECRET: z.string().min(32), NEXTAUTH_URL: z.string().url(), }); export const env = envSchema.parse(process.env);

这段代码在服务启动时执行，环境变量不对直接拒绝启动。生产环境最容易遇到的问题有三个：一是部署平台没有设置 DATABASE_URL；二是数据库 migration 没有执行；三是连接池配置不对。对应方案分别是：提前在环境变量面板配置；部署流程里加 npx prisma migrate deploy 这一步；PostgreSQL 生产环境建议用 Prisma 提供连接池配置。

构建命令一般是这样：

npm run build npx prisma migrate deploy npm run start

注意顺序：先 build 还是先 migrate 要看项目情况。如果页面里 SSG 阶段就要查库，那 migrate 必须在 build 之前；如果是 SSR 或纯客户端渲染，build 之后再 migrate 也来得及。实操上我会把 migrate deploy 放在 build 之前，避免生成静态页面时查不到表。另外，如果用了多实例部署，要确保 migrate 只在一个实例上执行，否则并发执行会互相锁表。

4. 落地过程中的高频问题与排查技巧

4.1 问题速查表

我在多个 t3code 风格项目里实测下来，以下问题出现频率最高：

这些问题是社区里提问最多的几个方向，也是我在实际开发里反复遇到的。每次排查都可以沿着“先看类型是否正确、再看数据是否正确、最后看权限是否正确”这条路径走，大部分问题都能定位到。

4.2 三个印象深刻的实战坑

第一个坑是 Prisma Client 版本和 tRPC 类型不匹配。曾经在升级依赖时，prisma generate 生成了新版本 client，但 tRPC 版本还停留在旧版，前端拿到的是 never 类型。这种问题眼神排查根本看不出来，最后是删掉 node_modules 和 lockfile 重新安装才解决。经验是：tRPC、Prisma、Next.js 这几个核心依赖尽量一起升级，不要拆开单独升。

第二个坑是 directUrl 配置。Prisma 新版引入了直接连接地址的概念，如果你在 datasource 里只配了 url，而是用了连接池地址，本地没问题，生产环境会出现连接池耗尽或超时。解决方案是明确区分连接池地址和直连地址，确保在数据迁移时使用直连地址，运行时使用连接池地址。

第三个坑是在 getServerSideProps 或 getStaticProps 里直接调用 tRPC router。很多人想把 tRPC 调用放进 SSR，结果发现类型复杂、异常处理混乱。实际上 tRPC 在服务端更推荐通过 server client 的方式调用，而不是直接 import router 跑一遍。如果你发现服务端调用代码很难写，写成一个小的 helper，统一封装 server api 的调用方式，别在页面里散落各种调用逻辑。

4.3 团队协作与代码组织建议

t3code 范式看着技术性强，实际最值钱的是它建立的代码边界。多人协作时，每个人负责自己的 router，改自己的 schema，不太会互相踩脚。但前提是得有约定：router 按业务资源划分，不要搞一个巨大的 rootRouter 里几百行 query；输入校验统一用 Zod schema，不要有的地方用、有的地方裸奔；错误处理统一走 error formatter，不要有的返回中文、有的返回英文。

我常用的组织方式是：prisma/schema.prisma 只放模型，不写业务逻辑；server/api/routers 尽量薄，只做参数校验、权限判断和编排，复杂计算抽到 service 层；页面组件里不直接访问数据库。这样下来，代码阅读成本和交接成本都低很多。前端同事只需要看 router 的 input 和返回值类型，就能接手一个页面的开发，不需要翻数据库表结构。

5. 进阶扩展：从 Demo 项目到生产级应用

5.1 身份鉴权：NextAuth 与 protectedProcedure

t3code 项目里默认集成了 NextAuth，但很多人只用到登录功能，没有把 session 和 tRPC 权限体系打通。正确的做法是在 createTRPCContext 里注入 session，然后在需要登录的 router 上用 protectedProcedure。一个典型的 context 实现：

import { getServerSession } from "next-auth"; import { authOptions } from "~/server/auth"; export const createTRPCContext = async (opts: { headers: Headers }) => { const session = await getServerSession(authOptions); return { db, session, ...opts, }; };

protectedProcedure 内部通过 middleware 检查 session 是否存在，不存在则抛出 UNAUTHORIZED 错误。这样做的好处是权限逻辑收敛在 tRPC 层，页面组件里不需要自己判断 session，也没有冗余的守卫逻辑。对于需要角色权限的场景，可以自己扩展 middleware，比如检查 session.user.role 是否为 admin，不满足时抛出 FORBIDDEN。

5.2 数据缓存与 SSR 优化

tRPC 默认使用 React Query 作为数据请求层，所以缓存策略其实是 React Query 的配置。常用的几个配置项：staleTime 表示数据在多少毫秒内视为新鲜，不重新请求；gcTime 表示不活动缓存保留时间。对于不经常变化的数据，比如字典列表、配置信息，建议设置较长的 staleTime，避免每次切换页面都发请求。

SSR 场景下，tRPC 早期版本不支持自动预取，需要手动用 generateSSRHelpers 或 server client 的方式在服务端取数。我个人建议，优先保证用户体验，列表页用 CSR 也没问题，首屏要求极高的营销页再考虑 SSR 预取。不要一开始就把所有页面都改成 SSR，那样做会明显增加服务端压力，收益却很有限。实测下来，一个内部管理系统，95% 的页面用 CSR + 合理的 staleTime 就够快了。

5.3 测试策略：router 层集成测试

很多人问 t3code 项目怎么写测试。我的建议是不要一开始就写大量端到端测试，而是先给 router 写集成测试。tRPC router 是纯 TypeScript 函数，你可以构造一个模拟的 context，传入 mock 的 db，直接调用 router 上的 query 和 mutation，断言返回结果。

import { postRouter } from "~/server/api/routers/post"; test("create should require auth", async () => { const ctx = { db: prismaMock, session: null, }; await expect( postRouter.create({ ctx, input: { title: "t", content: "c" } }) ).rejects.toThrow(); });

这种测试覆盖了校验逻辑、权限逻辑、业务逻辑，但不需要真的起数据库实例，用内存数据库或 mock prisma 就能跑。前端组件测试放在更后面，等核心业务逻辑稳定后再补。测试的价值在于让 router 重构时有安全感，不用每次改动都手工点一遍页面。

5.4 Monorepo 与多包架构

项目规模大了之后，可以考虑把 schema、类型定义、服务端逻辑拆成独立包。常见的做法是用 Turborepo 管理多个应用，比如一个 admin 管理后台、一个用户端、一个共享包放 zod schema 和类型定义。这样多个应用之间可以共享同一套校验规则和类型，避免每个应用各自维护一份重复定义。

不过我不建议一开始就上 monorepo。个人项目或中小团队项目，单个应用把目录结构理清楚已经能应付大多数情况。等真正出现“两个应用要共享同一套 schema”的需求，再做拆分也不迟。过早的架构拆分只会增加构建复杂度和依赖管理的负担。

最后分享几个实际使用中的体会

用了很长时间 t3code 风格的项目结构后，我最大的感受是：它并不能让开发变快，但能显著减少“莫名其妙”的时间。所谓莫名其妙，就是那种接口没变、代码没动、前端突然报错的联调现场。类型系统拦住了大量的低级错误，让我把精力放在真正的业务逻辑上。

我自己还有一个小习惯：每次改 schema.prisma，第一件事不是写业务代码，而是先跑 prisma migrate dev，然后看一眼生成的 migration 文件和 Prisma Client 类型。确认类型符合预期后，再写 router。这个习惯让我少踩了很多数据模型和 API 不一致的坑。另外，如果你所在的团队对 TypeScript 掌握普遍一般，t3code 的上手曲线会比传统 REST 高一点，这很正常，但一旦团队成员习惯了“改 schema 后类型自动全链路更新”的工作方式，没人愿意再回去人肉维护接口文档。

最后补充一点：t3code 这套范式适合前后端全部由自己掌控的业务系统，但不适合开放 API、第三方对接、以及需要强兼容多语言客户端的场景，那种情况 REST 或 GraphQL 仍然是更好的选择。选型没有绝对的对错，关键是想清楚你的项目到底卡在哪里。如果你的项目每天都因为类型不一致或者接口联调扯皮，那 t3code 提供的这套思路，值得你花一个周末搭个 Demo 试试。