企业官网建设流程全解析

如果你关注过近两年 TypeScript 全栈开发圈的动态，大概率听过 t3code 或者说 T3 Stack。它不算一个传统意义的框架，而是一套由 Next.js、TypeScript、Tailwind CSS、tRPC、Prisma、NextAuth 组合起来的开发范式，核心思想就一句话：端到端类型安全。我自己的主力项目也基于这套组合，前后端共用一套类型定义，改数据模型的时候编译器会直接告诉你哪些地方需要同步修改，不用再靠“人肉记忆”维护接口文档。这篇博文就围绕 t3code 的完整落地过程展开，从设计逻辑、项目初始化、CRUD 实操，到部署和日常避坑，希望能给正在考虑或已经在用这套技术栈的朋友一些实际参考。

1. t3code 到底是什么：先掰开 T3 Stack 的设计逻辑

很多人第一次听到 t3code 会误以为它是什么新框架，或者某个库的名字。实际上它是 T3 Stack 在社区里的一个实践代号，常被用来代指“以类型安全为第一优先级”的 TypeScript 全栈项目模板。它的名字里面带个 T3，其实就是三个以 T 开头的核心组件：TypeScript、Tailwind CSS、tRPC。下面我逐个展开讲。

1.1 名字背后的三个核心组件

TypeScript 不用多说，现代前端项目的默认选择，它解决了 JavaScript 弱类型带来的大量运行时意外。t3code 和其他 TypeScript 项目的区别在于，它对类型的追求不只是“前端内部有类型”这么简单，而是要求前后端共享类型——服务端定义了查询和变更，前端调用时自动推导出参数和返回值类型，连字段拼写错误都能在编译期暴露出来。

Tailwind CSS 则是样式层的关键选型。它提供了一套工具类优先的样式方案，写页面时直接在 class 里组合 tailwind 的工具类，基本不写自定义 CSS 文件。它对 t3code 的价值在于：样式方案简单、一致、可复用，不会打断“纯 TypeScript”的开发节奏。我见过很多项目为了 CSS-in-JS 方案引入一堆运行时依赖，反而拖慢了页面性能，用 Tailwind 之后这些问题基本消失。

tRPC 是三块拼图里最核心的一块。它允许你像调用本地函数一样调用远端 API，完全不需要手写 REST 路由、GraphQL schema 或者单独维护一套接口协议。服务端定义好 procedure，客户端 import 同一个 tRPC 实例后直接trpc.user.getById.useQuery(...)，TypeScript 会自动处理好请求、响应和错误的完整类型链。后面我会用完整代码演示这一过程。

1.2 类型安全优先，到底省了多少事

我早期做前后端分离项目时，最头疼的就是接口变更。后端改了一个字段名，前端不跑起来根本不知道；就算知道，也得到处搜索请求函数，一个个手动改。t3code 把这个问题变成了编译期自动发现，改掉 Prisma model 里的一个属性，tRPC 路由的返回值类型立刻变化，前端凡是使用该字段的组件全部报红。这种体验一旦习惯，很难再回到手写接口类型的时代。

传统 REST 项目里，前端往往要维护一套接口文档或 Postman 集合，后端也要花时间写 Swagger 注解。t3code 几乎把这一整层工作省略掉了，因为在 tRPC 的世界里，“接口定义”就是代码本身。服务端一个 router 的输入输出类型，客户端完全自动获得。也就是说，类型安全不是额外的工作量，而是写代码时的默认产物。

这套设计还有一个隐性收益：新人上手成本更低。团队成员只要懂 TypeScript 基本语法，就能顺着 tRPC 的类型提示快速定位到自己需要的逻辑。我团队里有个只做过两年 Vue 开发的应届生，拿到 t3code 项目后，第一天就能独立改接口并调通页面，这在传统全栈项目里几乎不可能。

当然，t3code 也有它不适合的场景。比如团队后端与前端分离较远，后端已经是 Java 或 Go 微服务，那 tRPC 就没有存在必要了。这更像一个面向独立开发者、小团队或全栈工程师的最佳实践集合，你们可以把它当作快速验证业务原型的高效底座，而不必盲目套用到所有系统上。

2. 项目初始化与基建：把 t3code 从零搭起来

如果想快速体验 t3code，最好的方式是直接使用官方脚手架 create-t3-app。它会通过交互式命令生成一个完整的 T3 Stack 项目，并把上述组件整合好。这一节我带你逐个过一遍初始化选项，以及生成后的目录结构如何组织。

2.1 五分钟创建项目：交互选项逐个讲

确保本机已安装 Node.js 16.8 以上版本和包管理器 pnpm，然后执行：

pnpm create t3-app@latest my-t3code-app

运行后，脚手架会问你几个关键选项，建议根据实际场景选择：

1. Next.js App Router 还是 Pages Router：新版脚手架默认推荐 App Router。如果你项目是新写的，直接用 App Router；如果是老项目迁移，可以选 Pages Router。我自己用 App Router 一年多了，至少目前没有遇到不可解的问题。

2. 是否启用 TypeScript：这个选项默认直接选是，t3code 的核心就是 TypeScript，不启用基本没有意义。

3. 是否启用 Tailwind CSS：建议选是。虽然样式解决方案可以另配，但 Tailwind 和 T3 理念最契合，而且脚手架里不少默认组件已经按 Tailwind 写好了。

4. 是否启用 tRPC：务必选是。这是 T3 的另外一个核心，也是区别于普通 Next.js 模板的最大特色。

5. 是否启用 Prisma：选是。脚手架会配置好 Prisma 相关依赖和目录，省去手动集成的时间。

6. 是否启用 NextAuth：根据需求来选。需要登录、鉴权就选是；如果项目还没有用户系统，可以先不选，后面再手动加也方便。

7. ESLint / Prettier：我建议全部选是。编码规范一开始就定好，后面不用花时间补，对团队协作尤其重要。

确认之后，脚手架会自动生成项目，然后执行pnpm install安装依赖。整个创建过程大概 5 分钟，不会卡住也不会有太多需要手动修改的地方。

2.2 目录结构和核心配置到底该怎么看

项目生成后，有几个目录和文件需要提前了解：

• src/pages/或src/app/：路由页面所在的目录。App Router 模式下，页面文件放置在src/app/下，结构与目录即路由。
• src/server/：服务端逻辑统一目录。db.ts负责创建 Prisma 客户端，api/下面放 tRPC 的 router 定义。
• src/trpc/：tRPC 核心类型和客户端封装。server.ts负责创建 tRPC 实例，react.ts或query.ts负责前端 hooks 封装。
• prisma/schema.prisma：数据库模型定义文件，所有表结构都写在这里。
• .env：环境变量文件，放数据库连接串、NextAuth 密钥等敏感信息。
• env.mjs：环境变量校验文件，用 zod 对process.env做运行时校验，防止缺配置才跑起来才发现。

这些目录划分的核心逻辑，是把“服务端 + 客户端 + 类型定义”三者分层管理，每一层之间的数据流都通过 tRPC 类型天然衔接。刚接触时会觉得文件比普通 Next.js 项目多一些，但一旦熟悉整个链路，你会发现这些文件几乎没有重复职责。

环境变量这块需要特别提醒一点，脚手架生成的.env里默认只有几项：

DATABASE_URL="" NEXTAUTH_SECRET="" NEXTAUTH_URL="http://localhost:3000"

如果之后要接入第三方登录，还要在里面增加GITHUB_CLIENT_ID、GOOGLE_CLIENT_ID这类变量。变量新增后要在env.mjs里同步增加校验规则，否则运行时会被拦截。这个校验机制初看有点烦人，实际用久了觉得很香：部署的时候忘了配数据库连接串，应用会直接启动失败并给出明确提示，而不是等用户点按钮时才爆出 500。

3. 实操核心：在 t3code 里完成一个完整的 CRUD 功能

理论铺垫得差不多了，这一节做实战。我用一个最常见的任务管理（Todo）场景，演示从数据库模型到前端页面的完整通路。

3.1 用 Prisma 定数据模型：从零设计表结构

打开prisma/schema.prisma，在里面定义 Task 表：

generator client { provider = "prisma-client-js" } datasource db { provider = "postgresql" url = env("DATABASE_URL") } model Task { id String @id @default(cuid()) title String content String? completed Boolean @default(false) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

这里我用了cuid()作为主键而不是自增 id，因为 t3code 这种全栈架构下，客户端生成任务时不想等数据库返回自增 id，cuid 可以直接在服务端或客户端生成，能减少一次往返开销。content字段设为可选，表示任务详情不是必填项。completed默认false，表示任务初始状态为未完成。

定义完成后，执行迁移命令：

pnpm prisma migrate dev --name init_task

这个命令会做两件事：在数据库中创建对应的表结构，同时自动生成 Prisma Client。生成后的 Prisma Client 提供了完整的 TypeScript 类型推导，后面我们写 tRPC 路由时，返回值类型能自动关联到src/server/db.ts中的 Prisma 实例。

跑完迁移后，最好先写一条测试数据验证数据库连接没问题：

pnpm prisma studio

Prisma Studio 会打开一个可视化面板，在里面手动添加一条 Task 数据，确认基础链路是通的。这一步能排除掉“代码没问题，纯粹是数据库没配好”的一类低级问题。

3.2 tRPC 路由：处理查询和变更的完整代码

接下来定义 tRPC 的 router。打开src/server/api/routers/task.ts：

import { createTRPCRouter, protectedProcedure, publicProcedure } from "~/server/api/trpc"; import { z } from "zod"; export const taskRouter = createTRPCRouter({ getAll: protectedProcedure .query(async ({ ctx }) => { return ctx.db.task.findMany({ orderBy: { createdAt: "desc" }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1, "标题不能为空"), content: z.string().optional(), })) .mutation(async ({ ctx, input }) => { return ctx.db.task.create({ data: { title: input.title, content: input.content ?? null, }, }); }), toggle: protectedProcedure .input(z.object({ id: z.string() })) .mutation(async ({ ctx, input }) => { const task = await ctx.db.task.findUnique({ where: { id: input.id }, }); if (!task) { throw new Error("任务不存在"); } return ctx.db.task.update({ where: { id: input.id }, data: { completed: !task.completed }, }); }), delete: protectedProcedure .input(z.object({ id: z.string() })) .mutation(async ({ ctx, input }) => { return ctx.db.task.delete({ where: { id: input.id } }); }), });

注意我用了protectedProcedure，意思是要求用户登录后才能访问接口。如果项目还没接入认证，可以先改成publicProcedure，但发布到公网前一定要切换回来并测试好权限。create的输入用 zod 做了校验：title至少 1 个字符，content可选。输入校验不是额外负担，它本质上把接口层最容易出错的“非法参数”在入口拦截掉了。

toggle这个 mutation 里有个细节：我先查一次任务，再取反更新。这个操作不是最优的，因为它会产生两次数据库请求。更快的方案是直接用数据库的取反语法，但为演示清晰的业务逻辑，我保留了这种写法。实际应用中数据量大时，可以改用db.$queryRaw或字段自增逻辑优化。

最后把taskRouter挂载到根路由。在src/server/api/root.ts里做类似操作：

import { createTRPCRouter } from "~/server/api/trpc"; import { taskRouter } from "~/server/api/routers/task"; export const appRouter = createTRPCRouter({ task: taskRouter, }); export type AppRouter = typeof appRouter;

AppRouter这个类型是整个端到端类型安全的源头，后面前端封装的 hooks 都依赖这个类型动态推导。也就是说，你在这里新增一个 procedure 后，不需要额外生成任何客户端代码，前端调用处会自动出现新方法。

3.3 前端调用与类型推导：写完后端，前端立刻有提示

以 App Router 为例，假设我们在src/app/page.tsx实现任务列表。核心代码：

"use client"; import { api } from "~/trpc/react"; export default function Home() { const { data: tasks, refetch, isLoading } = api.task.getAll.useQuery(); const createTask = api.task.create.useMutation({ onSuccess: () => refetch(), }); const toggleTask = api.task.toggle.useMutation({ onSuccess: () => refetch(), }); if (isLoading) return <div>加载中...</div>; return ( <div className="p-8"> <h1 className="text-2xl font-bold">任务清单</h1> <form onSubmit={(e) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const title = String(formData.get("title") ?? ""); createTask.mutate({ title }); }} > <input name="title" placeholder="输入任务标题" /> <button type="submit">添加</button> </form> <ul> {tasks?.map((task) => ( <li key={task.id} className="flex items-center gap-2"> <input type="checkbox" checked={task.completed} onChange={() => toggleTask.mutate({ id: task.id })} /> <span className={task.completed ? "line-through" : ""}> {task.title} </span> </li> ))} </ul> </div> ); }

代码里api.task.getAll.useQuery()能自动推导返回类型为Task[]，data就是任务数组。如果你尝试访问一个 Task 上不存在的字段，编辑器会立刻报错。这段代码里onSuccess: () => refetch()是 tRPC + React Query 的最佳实践，mutation 成功后刷新列表数据，保证界面数据一致性。

新手最容易在这里卡住：为什么api对象不存在？原因是没有在页面组件里调用正确的 tRPC React 封装。确认在src/trpc/react.ts里导出了api，并且在根布局或页面组件的 Provider 层级挂载了<TRPCReactProvider>。脚手架生成的模板默认已经挂好了，但如果你是自己手动接入，这一步很容易漏掉。

运行pnpm dev，浏览器打开http://localhost:3000，整个过程简单到像在“写前端的同时顺便写好了后端”。这种感觉只有亲手试过才能体会到。

4. 从开发到上线：t3code 的部署与配置要点

本地开发顺畅不代表部署无忧。t3code 项目部署到 Vercel 时，有几个配置点必须提前处理好，否则生产环境会给你上点“颜色”。

4.1 环境变量管理与编辑器配置

部署前先把环境变量梳理一遍。本地开发时.env文件里有一份本地配置，但部署到 Vercel 等平台后，需要在平台后台的 Environment Variables 里填入生产环境变量，例如：

• DATABASE_URL：生产数据库连接串
• NEXTAUTH_SECRET：生产环境使用的随机密钥
• NEXTAUTH_URL：生产域名

有一个常见问题：本地DATABASE_URL可能连的是localhost的 PostgreSQL，生产环境连的却是云数据库。如果在本地跑prisma migrate dev后没有把迁移文件提交到 Git，部署时可能无法自动建表。建议每次改完 schema 后执行git add -A && git commit时，把prisma/migrations目录一并提交，这样后续部署时执行prisma migrate deploy就能保证数据结构一致。

编辑器配置方面，推荐安装两个 VS Code 扩展：Prisma（官方插件，提供 schema 文件语法高亮和格式化）和 Tailwind CSS IntelliSense（帮助提示 Tailwind 类名）。组件代码里 tailwind 的类名如果拼错，编译期不会报错，但样式会消失，很难排查；IntelliSense 扩展能在敲代码时直接提示有效类名，能省不少事。t3code 项目默认还带了一个.vscode/settings.json，会对手写 CSS 类名做简单管控，建议大家保留。

4.2 把应用部署到 Vercel：三条关键配置

在 Vercel 部署 t3code 项目时，以下三条配置决定成败。

第一，构建命令推荐用pnpm build，Vercel 会自动检测项目使用的包管理器。如果你本地用 pnpm，建议在 Vercel 项目设置里也把“Install Command”和“Build Command”显式写清楚：

Install Command: pnpm install Build Command: pnpm build

第二，Prisma Client 需要在构建阶段生成。Vercel 每次部署都是全新环境，默认不会把本地生成的 Prisma Client 带上，所以在构建命令里要加上prisma generate。常见做法是把构建命令改成：

pnpm prisma generate && pnpm build

如果不加这一步，很可能会遇到PrismaClient is not configured或者找不到 client 类型的错误。这个坑我踩过一次，当时本地一切正常，部署后却始终报错，排查了大半天才发现是这个原因。

第三，生产数据库连接串如果是 PostgreSQL，注意云数据库的并发连接上限。serverless 环境下每个请求可能都会创建新的数据库连接，而 PostgreSQL 默认连接数有限。常规做法是使用像 Supabase、Neon 这类提供连接池的服务，或者在 Prisma Client 配置里启用连接池。如果项目流量不大，默认连接一般够用；但上线后如果突然出现Too many connections错误，大概率就是这个问题。

还有一个容易被忽略的点，NextAuth 在生产环境需要设置正确的NEXTAUTH_URL。如果之前只配了http://localhost:3000，部署后登录流程会跳转异常。把生产域名填进去，通常就能解决。如果使用 Vercel 部署，有些开发者还会配置AUTH_TRUST_HOST=true来避免代理环境下回调地址不正确的问题。

5. 常见问题与排查速查表：t3code 实战避坑实录

下面这几个问题，我在不同项目里反复遇到，整理成速查表方便大家排查。

5.1 类型对不上：六个高频报错与修复

前三个问题其实是 t3code 最常见的起步问题：路由没挂、类型不匹配、路径别名有问题。新手写代码时遵循“从内向外”的顺序：先确认根路由挂载无误，再确认 zod 输入类型与前端传入参数对齐，最后检查 tsconfig。按这个顺序排查基本都能解决。

5.2 性能与扩展：TypeScript 项目不小心的慢

t3code 项目的性能瓶颈，往往不在 TypeScript 本身，而在于使用不当。

第一个是数据库查询 N+1 问题。Prisma 的findMany如果包含关联表数据，却不合理使用include或select，很容易产生大量查询。比如后端返回任务列表时，如果每个任务都关联了用户信息，建议在查询时明确声明select: { id, title, completed ... }，避免把不需要的大字段返回给前端。

第二个是客户端数据缓存策略。tRPC 默认使用的是 React Query 的缓存机制，如果 mutation 后忘记调用refetch或更新缓存，界面可能显示旧数据。代码里写onSuccess: () => refetch()是一个简单粗暴且有效的策略，数据量大了之后可以升级为setQueryData单条更新，减少一次列表请求。

第三个容易被忽略的问题是 bundle 体积。Next.js 默认会按路由做代码分割，但如果你把 tRPC 的整个 router 直接在客户端 import，可能把服务端代码也打进去了。注意使用脚手架生成的~/trpc/react.ts封装，不要自己从服务端文件里直接引入 router 逻辑。保持客户端只依赖类型和 hooks。实测下来，遵循这一条规则，首屏 bundle 大小能减少 30% 以上。

5.3 其他容易忽略的坑

除了类型和性能，tRPC 还有两个日常容易踩的坑。

第一是 query 的 key 管理。tRPC + React Query 的 key 是自动生成的，如果你想手动清除某个用户列表的缓存，需要了解 key 的生成规则。比如api.user.getAll.useQuery()对应的 queryKey 是[["user","getAll"],{"input":undefined,"type":"query"}]。手动更新时最好用api.useUtils()中的相关方法，而不要自行拼接字符串。

第二是 mutation 的 loading 状态。使用 tRPC 增加操作时，如果点击按钮后按钮没有禁用，用户可能连续点击多次，后端就会重复创建多条数据。处理方式是在按钮上绑定createTask.isPending来禁用按钮，类似：

<button type="submit" disabled={createTask.isPending}> {createTask.isPending ? "添加中..." : "添加"} </button>

这个小细节在开发环境不重要，但生产环境用户手速快的时候真的会产生重复数据。我用 t3code 做了好几个项目之后发现，这类“边缘交互”的体验只能在实战中不断打磨，脚手架不会替你处理业务层的问题。

6. 写在最后的一点个人体会

我一直觉得 t3code 不是给所有人都用的银弹。如果你是全栈独立开发，或者在小团队里负责从数据库到页面的整条链路，这套技术栈能极大压缩开发生命周期；如果是大型团队、服务端与前端长期分离，那你更需要思考是否要让前段直接掌控 Prisma 和数据库操作，这实际上是一种团队协作模式的改变。

我在多个实战项目里最受益的一点，还是 tRPC 的类型系统带来的“心智减负”：改完模型不担心漏改接口，写完接口不担心前端传错参数。虽然这套技术栈的生态还在快速迭代，但它的核心方向——用 TypeScript 打通全链路类型——已经被越来越多项目接受。如果你正打算从零起步做个全栈应用，我建议不妨用 t3code 跑一个原型出来，亲手感受一次“改一个字段，整个应用都跟着同步变化”的开发体验。