企业官网建设流程全解析

两年前我第一次接触t3code这个词，是在一个用create-t3-app初始化的全栈项目里。当时屏幕上连续勾选了Next.js、Prisma、tRPC、Tailwind，我心里其实有点不以为然：这不就是又一个技术全家桶吗。直到自己完整跑通两三个T3 Stack项目之后，我才发现这个组合最有价值的地方，不是某个框架多能打，而是它把类型安全从数据库一路贯穿到了前端按钮，整个数据链路几乎没有"手工拼接口"的环节。这篇内容就围绕t3code展开，适合三群人看：一是听说过T3 Stack但不知道怎么上手的，二是已经在用但遇到各种类型报错和认证问题的，三是想对比一下"这套全栈方案到底值不值得在团队里推广"的人。我会把自己真实跑项目时的选型逻辑、搭建步骤、踩坑记录都摆出来，不绕弯子。

1. t3code不是一个模板：T3 Stack想解决的真实问题

很多人第一次看到"T3 Stack"这个命名，会以为它是什么新框架。其实它更像一套"技术选型公约"。T3来自三个以T开头的核心成员：TypeScript、Tailwind CSS、tRPC。而围绕这三个核心，通常还会搭配Next.js、Prisma、NextAuth.js一起使用。t3code在这里可以理解为"按T3 Stack规范编写全栈代码"的实践过程，它不是一个可下载的成品模板，而是一套能复用的组合逻辑。

1.1 T3到底是哪三个T

• TypeScript：全项目使用强类型语言，从后端到前端统一类型系统。
• Tailwind CSS：原子化CSS框架，直接在JSX里组合样式类，解决样式隔离和命名纠结。
• tRPC：一个远程过程调用库，允许前端像调用本地函数一样调用后端函数，并且类型自动推导。

另外还有两个"编外成员"几乎每次都会出现：Next.js负责应用框架和路由，Prisma负责数据库访问。为什么要把它们算进来？因为T3 Stack的哲学是"不重复发明轮子"。Next.js和Prisma是各自领域里当下生态最成熟的方案，直接拿来用就行，T3只负责把这一切粘合得特别顺。

1.2 "类型安全"为什么值得当作默认配置

T3 Stack最核心的口号是typesafety as the default，类型安全是默认配置，而不是后补选项。传统的前后端分离开发里，最折磨人的一件事就是接口契约不统一：后端改了返回结构，前端要重新看文档改类型定义，漏改一个字段页面就静默报错。t3code的思路是把这件事从根上杜绝——数据库表结构由Prisma定义一次，类型往下游自动生成；后端函数的入参和返回值直接由tRPC暴露给前端，前端调用时连函数名带参数类型都是全的。

你可以这么理解：传统REST API像是两家餐馆之间传菜，需要你手写菜单、手抄菜名，哪个字抄错了后厨就不知道你想吃什么。而tRPC像是你把厨师请到餐桌上，你直接告诉他要什么菜，他做完直接端到你面前，中间省掉了"菜单文书"这个环节。这个类比不完全准确，但能解释为什么这套组合在实际开发里效率提升这么明显。

2. 五个核心成员逐个拆解：为什么偏偏是它们

谈技术选型，不能只罗列"我用什么"，必须说清楚"为什么不用别的"。这个部分我把T3 Stack的每个核心成员单独拎出来，讲它在整个链路里解决什么痛点。

2.1 TypeScript与Next.js：全栈地基

TypeScript在这个组合里的角色不是"给JS加类型装饰"这么简单。在t3code项目里，类型是贯穿数据库、服务端、客户端三层的唯一"通用语言"。我见过不少团队只在前端用TS、后端写JS，结果前后端接口全靠人肉同步，这个问题在T3 Stack里不存在，因为后端Router的类型可以被前端直接import。

Next.js提供的是全栈的"壳子"：页面路由、SSR/SSG、API Route都不是额外搭的，而是框架自带的。早期有人问"为什么不用Vite+Express自己拼一个"，答案是没必要——Next.js已经覆盖了99%的常规场景，而且它对tRPC的支持很友好，不管是Server Component还是Client Component都有对应的调用方式。

2.2 Tailwind CSS：样式体系的自控与克制

Tailwind在T3 Stack里可能看起来"最不像核心"，但它的作用被很多人低估。t3code项目里，页面组件和后端逻辑放在同一个仓库，如果样式系统还要另外维护一堆CSS类名和变量命名规范，心智负担就太大了。Tailwind把样式拆成原子类，直接在组件内联写，新成员接手时不需要猜测类名的含义，设计变更也基本只动JSX。

另外Tailwind的定制能力是够用的：你在tailwind.config.ts里定义theme扩展，颜色、间距、字体全部走变量，不需要引入额外的CSS-in-JS方案。这一点对一个强调"少工具、高效率"的栈来说很重要。

2.3 tRPC：把"接口文档"从工作流里删掉

这是T3 Stack里最值得展开的工具。tRPC的核心理念是：服务端定义一个router对象，前端通过tRPC客户端直接调用router里的procedure（可以理解为一个后端函数），不需要编写URL路径、HTTP方法、请求体结构，类型会在编译期自动从后端流向前端。

举个例子。REST风格下你要获取文章列表，一般要写：

GET /api/posts

然后在前端手动构造类型：

interface PostDTO { id: string; title: string; published: boolean; }

而在t3code里，后端定义好procedure之后，前端调用：

const { data } = trpc.post.getAll.useQuery();

data的类型完全由后端返回类型推导出来，不存在"两边不同步"的问题。这个感受在你增加一个字段或者改一个返回结构时尤为明显，编译器的报错会精确告诉你哪里需要跟着改，而不是等到运行时才发现接口挂掉。

2.4 Prisma与NextAuth：数据层和会话层的助攻

Prisma在这里提供两层价值。第一层是schema即契约：你写一遍Prisma Schema，它会自动生成对应的TypeScript类型和数据库迁移脚本。第二层是查询API的类型安全：prisma.post.findMany({ where: { published: true } })的返回结果类型是自动推导的，查询条件写错字段会直接编译报错。

NextAuth.js则是当前Next.js生态里最成熟的认证方案。T3 Stack把它集成进来以后，登录、会话、token检查都变得模块化，而且可以配合tRPC的中间件做"只有登录用户能访问的procedure"。这一块我后面会讲到具体的配置方法。

3. 从零初始化一个t3code项目：我习惯的"脚手架"流程

接下来进入实操。我会按自己真实的操作顺序走一遍，读者可以照着敲。

3.1 初始化命令与模块取舍

创建项目的命令是：

npm create t3-app@latest

运行后会有交互式选项，你可以给目录命名，比如my-t3-app。接着会问你要装哪些模块，我的习惯是全选：

• Next.js
• TypeScript
• Tailwind CSS
• tRPC
• Prisma
• NextAuth.js

为什么全选？因为T3 Stack这些模块在设计上就是互相配合的，你初始不装，后面要手动集成反而更麻烦。比如你做一个小工具项目，暂时不需要登录，很多人会想跳过NextAuth，但后面加认证时，只加一个NextAuth包还不行，还要改Context、改中间件、改环境变量，来回折腾的时间比一开始就装上多得多。所以除非项目极其简单，我建议全选。

初始化完成后，直接进入目录：

cd my-t3-app npm run dev

这时打开http://localhost:3000，已经能看到一个可运行的基础页面。

3.2 环境变量与Prisma数据模型先行

不要急着写业务代码，先处理两件事：环境变量和数据模型。

项目根目录有.env文件，你需要先填入关键配置：

DATABASE_URL="你的数据库连接串" NEXTAUTH_SECRET="一个随机字符串" NEXTAUTH_URL="http://localhost:3000"

生成随机secret可以执行：

openssl rand -base64 32

数据库我用的是PostgreSQL，连接串类似：

postgresql://user:password@localhost:5432/mydb

接下来修改prisma/schema.prisma。以博客场景为例，先建User和Post两个模型：

model User { id String @id @default(cuid()) name String? email String @unique emailVerified DateTime? image String? accounts Account[] posts Post[] } 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 }

然后执行迁移：

npx prisma migrate dev --name init

这一步会在数据库里建出真实表结构，并且自动生成TypeScript类型到node_modules/.prisma，后面你的所有查询代码都有类型提示。

3.3 第一个tRPC Router与页面接入

在src/server/api/routers/post.ts里，定义一个最基础的查询router：

import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; export const postRouter = createTRPCRouter({ getAll: publicProcedure.query(async ({ ctx }) => { const posts = await ctx.db.post.findMany({ where: { published: true }, orderBy: { createdAt: "desc" }, }); return posts; }), });

然后在根router里挂载：

import { postRouter } from "~/server/api/routers/post"; export const appRouter = createTRPCRouter({ post: postRouter, });

前端页面里，创建一个Client Component来调用：

"use client"; import { api } from "~/trpc/react"; export function PostList() { const { data: posts, isLoading } = api.post.getAll.useQuery(); if (isLoading) return <div>加载中...</div>; return ( <ul> {posts?.map((post) => ( <li key={post.id}>{post.title}</li> ))} </ul> ); }

这里api.post.getAll的类型和返回值都是自动推导的，不需要在任何地方手写PostDTO接口。我第一次跑通这个流程时最直观的感受是：前后端的边界变得特别薄，脑子里的对象模型就是代码里的对象模型，不用再翻译一遍。

4. 从数据库到按钮：一笔tRPC查询的完整旅程

很多新手对tRPC的最大疑问是：它到底是怎么把"调用一个函数"变成"一次网络请求"的？这个环节我拆开讲。

4.1 链路全景：前后端代码到底怎么串起来的

当你执行api.post.getAll.useQuery()时，实际发生的请求路径是这样的：

1. tRPC客户端把procedure路径（比如post.getAll）和入参序列化成JSON，通过HTTP POST发送到/api/trpc这个统一入口。
2. Next.js的API Route接收请求，交给tRPC服务端处理。
3. tRPC在服务端创建Context，把数据库连接等依赖注入进去。
4. 找到对应的postRouter和getAllprocedure，执行函数体。
5. 返回值序列化成JSON，沿原路返回前端。
6. useQuery拿到数据后按类型推导更新组件状态。

关键是第1步和第6步之间，类型的全链路一致性由tRPC的infer机制保证。只要后端procedure返回类型变化，前端data的类型立刻跟着变。

这里有一个容易忽略的细节：t3code项目默认使用httpBatchLink，它会把多个并发tRPC请求合并成一个HTTP请求返回。对性能是友好的，但在某些缓存场景下要留个心眼，我后面第6章会提到。

4.2 与传统REST方式的对比

我把同样的"获取文章列表"功能用REST和tRPC分别写一遍，直观对比工作量。

REST方案需要做的事情：

1. 后端写一个Controller，定义GET/api/posts。
2. 在后端定义DTO类型并手动组装返回结构。
3. 在另一个文件里写对应的类型定义，专门给前端用，同步靠自觉。
4. 前端写一个fetcher请求函数，设置URL、headers、query参数。
5. 拿到数据后手动断言类型，任何一步错了都得到运行时才发现。

tRPC方案需要做的事情：

1. 后端写一个procedure。
2. 前端直接调用，类型自动同步。

这里不是要贬低REST，REST在跨团队、跨服务边界场景下依然有不可替代的地位。但在同一个全栈仓库里，为了一个CRUD功能维护两套契约，纯属内耗。t3code这套组合，适合那种"团队既写前端也写后端"的紧凑型全栈项目。

4.3 一个真实的CRUD示例：博客文章模块

我以博客的"创建文章"功能为例，把完整代码走一遍。

后端router里加入create：

create: publicProcedure .input( z.object({ title: z.string().min(1), content: z.string().optional(), published: z.boolean().default(false), }) ) .mutation(async ({ ctx, input }) => { const author = await ctx.db.user.findFirst(); if (!author) { throw new Error("没有找到用户"); } return ctx.db.post.create({ data: { title: input.title, content: input.content, published: input.published, authorId: author.id, }, }); }),

前端创建文章的表单组件：

"use client"; import { useState } from "react"; import { api } from "~/trpc/react"; export function CreatePost() { const utils = api.useUtils(); const [title, setTitle] = useState(""); const [content, setContent] = useState(""); const createPost = api.post.create.useMutation({ onSuccess: () => { utils.post.getAll.invalidate(); setTitle(""); setContent(""); }, }); return ( <form onSubmit={(e) => { e.preventDefault(); createPost.mutate({ title, content }); }} > <input value={title} onChange={(e) => setTitle(e.target.value)} placeholder="文章标题" /> <textarea value={content} onChange={(e) => setContent(e.target.value)} placeholder="文章内容" /> <button type="submit">发布</button> </form> ); }

这里注意utils.post.getAll.invalidate()这一行，它的作用是让tRPC立刻失效并重新拉取post.getAll的缓存，这样文章列表会马上刷新。很多t3code新手容易漏掉这一步，导致数据明明创建成功了，界面却不更新。

5. 认证与权限：让protectedProcedure真正扛起门禁

T3 Stack默认集成NextAuth，但NextAuth单独装不等于你的接口是安全的。要让tRPC的procedure只在登录后可见，必须做一层中间件，这就是protectedProcedure。

5.1 NextAuth与tRPC Context的接合方式

在src/server/api/trpc.ts里，初始化tRPC时会创建一个Context，里面包含NextAuth的session信息。核心代码大致是：

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, }; };

这样每个procedure里都能通过ctx.session拿到当前登录用户。接着定义protectedProcedure：

export const protectedProcedure = t.procedure.use(({ ctx, next }) => { if (!ctx.session?.user) { throw new Error("未登录"); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }); });

使用方式很简单：最初定义的getAll是publicProcedure，任何访问者都能看；想把它变成登录可见，就把publicProcedure换成protectedProcedure。

5.2 用中间件做细粒度权限控制

认证只是"是不是登录用户"，权限则是"登录用户能不能操作这条数据"。

比如博客系统里，用户只能改自己的文章。做法是在button层做软控制，更稳妥的是在服务端procedure里二次校验：

update: protectedProcedure .input( z.object({ id: z.string(), title: z.string().optional(), }) ) .mutation(async ({ ctx, input }) => { const post = await ctx.db.post.findUnique({ where: { id: input.id } }); if (!post || post.authorId !== ctx.session.user.id) { throw new Error("无权修改这篇文章"); } return ctx.db.post.update({ where: { id: input.id }, data: { title: input.title }, }); }),

这种"先查再对比再操作"的模式，比单纯在前端隐藏按钮可靠得多。因为别人完全可以绕过你的UI，直接伪造tRPC请求。

5.3 部署阶段最容易翻车的认证配置

本地运行一切正常，一部署就报500错误的情况，我见过太多次。多数根因出在环境变量上：

• NEXTAUTH_URL必须改成生产环境的完整域名，比如https://myblog.example.com。
• NEXTAUTH_SECRET必须显式设置，且不能和本地开发用同一个随机值生成的持续变换。
• OAuth Provider的Callback URL要同步更新到授权列表里，比如你接Google登录，就要把生产域名加进Google Cloud Console的重定向URI。

另外需要注意，Next.js App Router下，以前常用的getSession()在服务端已经废弃，请使用auth()或getServerSession。如果你搜索老教程照抄，很容易遇到类型报错或Session始终为null的坑。

6. 我在真实t3code项目里踩过的坑和绕坑方式

前五章是"正确路径"，这一章是我实际开发中反复踩过的坑，更值得看。

6.1 Zod输入校验缺失导致的类型裂缝

一开始偷懒，写procedure时不写.input()，直接publicProcedure.mutation(async ({ ctx, input }) => {...})，并手动把input强转为某个类型。表面上看功能能跑，但前端调用时入参类型是unknown，等于把类型安全的大门打开了一条缝。更危险的是，缺了Zod校验，攻击者可以往mutation里塞任意结构的数据，服务端稍不谨慎就会出现未定义行为。T3 Stack官方已经把Zod作为必选依赖，请务必每个输入都写.input()。

6.2 Prisma Client在热更新时的多实例问题

开发环境用next dev时，热更新会反复重新加载代码。如果没有做全局单例处理，Prisma Client会被创建多个实例，日志里会出现大量"Too many connections"报警。标准解法是在src/server/db.ts里加全局缓存：

import { PrismaClient } from "@prisma/client"; const globalForPrisma = globalThis as unknown as { prisma: PrismaClient | undefined; }; export const db = globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV !== "production") { globalForPrisma.prisma = db; }

网上很多教程会漏掉这一步，我建议直接按这个写法固定下来。

6.3 RSC与tRPC的边界：useQuery只能在客户端

Next.js App Router的Server Component是异步组件，不能使用React Hooks，因此api.post.getAll.useQuery()在Server Component里直接写会报错。如果你需要在服务端提前取数据——比如为了SEO在SSG时渲染文章列表——不要硬塞，应该分两层：外面用Server Component，里面拆出一个"use client"的子组件负责调用tRPC。或者改用服务端直接调底层service函数。这个边界一开始我也是碰了几次壁才摸清。

6.4 mutation之后缓存不刷新的怪现象

我前面在CRUD示例里写过utils.post.getAll.invalidate()。如果你忘了它，会发生什么？数据已经写入数据库，但页面列表还是旧的，你刷新浏览器才发现变化。这会让使用者误以为创建失败。另一个相关问题是，httpBatchLink默认有缓存策略，如果你在Mutation后没失效缓存，即使跳转页面再回来，缓存可能还是旧数据。建议把"每次mutation成功后，invalidate依赖的相关query"当作固定习惯。

6.5 环境变量与生产环境的签名配置

第5.3节提过认证环境的坑，这里再补一个更隐蔽的：如果你在.env里写的是DATABASE_URL="postgres://..."这种明文，本地没问题，但推到Vercel这类部署平台时，记得在平台的环境变量管理界面重新配置一遍。不要指望.env文件被自动带上去，现在的部署平台出于安全都会忽略仓库里的.env。漏配置的表现通常是：本地一切正常，线上所有数据库查询全部报错。

6.6 一些零散但重要的实操心得

• 开发时多用npx prisma studio，图形化查看数据表比直接写SQL方便得多。
• tRPC的serverApi和reactApi要分清，useQuery只能在React侧用，纯函数里想取数请走serverApi。
• 遇到"类型突然全红了"的情况，先检查是不是改了schema.prisma后忘了执行npx prisma generate。
• 如果团队里有人不熟悉tRPC，最快要上手的路径不是看文档，而是直接读create-t3-app脚手架生成的模板代码，它已经把Context、Router、认证中间件都串好了，照着改就行。

我现在跑项目时的习惯是：数据库变更先进Prisma Schema，接口变更先进tRPC Router，前端组件永远只是"类型的消费者"。这个顺序一旦固定下来，整个t3code项目的开发节奏会特别流畅。也希望这篇内容能帮你少走一段弯路，直接在第一个项目里就体验到类型安全全链路带来的踏实感。