企业官网建设流程全解析

1. 从t3code说起：这套全栈方案到底是什么

如果你最近在逛技术社区或者刷前端相关的推，大概率会频繁看到一个组合——t3code，也就是大家口口相传的T3 Stack。我第一次看到这个标签时也愣了一下，以为是个什么新框架的名字，后来翻了一圈才发现，它其实是TypeScript + Tailwind CSS + tRPC这三个“T”打头技术组成的全栈开发方案，再配合Next.js、Prisma和NextAuth.js，形成一套完整的、全程类型安全的应用脚手架。

这套方案能解决的问题非常直接：全栈开发最烦的就是前后端联调时接口类型对不上、改个字段就要两边同步改、部署时环境变量漏配、认证逻辑自己从零搓半天。T3 Stack把从数据库到页面渲染这一整条链路上的类型全部串起来，让你在写代码的时候就能发现大部分错误，而不是等运行时报错再回头抓头发。更关键的是，它背后有一套“约定优于配置”的哲学——少做选择，把精力花在业务上，而不是花在“用哪个状态管理库”“要不要自己写ORM”这些纠结里。

这篇博文不是给你念官方文档，而是把我实际从零搭项目、写接口、调认证、踩坑、部署的过程和思考完整记录下来。适合刚接触全栈开发想找一条靠谱路线的同学，也适合已经在用这套技术但对其中某些细节还不太透的开发者。里面所有代码和步骤都是我在真实项目里验证过的，你能直接照抄着用。

2. 核心组件拆解：每个轮子到底在扛什么活

T3 Stack不是一个新框架，它是一组技术的最佳实践组合。想真正用好它，你得先搞清楚每个组件在整个链路里的位置和职责。我按数据流方向，从数据库到页面逐个拆。

2.1 TypeScript：全栈类型安全的基石

整个T3方案的灵魂就是TypeScript。很多人把TS单纯理解成“给JS加类型”，但在T3的语境里，TS承担的任务重得多——它要贯穿数据库、API层和UI层，让同一份类型定义在前后端之间流动。

举个例子，我在PostgreSQL里定义一个Post表，Prisma会自动生成对应的TS类型。这个类型可以被tRPC的接口直接引用，再传到React组件的props里，你会发现从数据库查询结果到页面渲染，类型完全是同一套。改数据库的字段结构，重新生成Prisma Client后，前端使用这个字段的地方会立刻标红报错。这比任何文档都管用，等于强制让你的代码跟数据库保持同步。

实操体会：别为了“省事”把某个接口的返回值定义成any。我有一段时间为了赶进度在几个接口上偷懒用了any，结果队友改数据库字段时，那几处悄悄返了undefined，线上跑了好久才被用户反馈炸出来。类型安全这东西，偷一分懒就还十分债。

2.2 Next.js：应用骨架与全栈容器

Next.js在T3里扮演的是“宿主”角色。它是React框架，也是服务端渲染和API路由的容器。在T3架构里，你的tRPC路由挂在Next.js的API路由下，页面组件可以是服务端组件也可以是客户端组件，数据的获取、认证的校验都可以在服务端完成，再输出给浏览器。

我最看重Next.js的一点是它的文件路由约定。pages/或者app/目录下新建一个文件就等于新建一个页面，目录结构就是URL结构，不需要额外配路由表。这种约定式设计跟T3哲学很搭——少做决策，按规范来。如果你之前用过Express配路由，可能会不习惯，但上手几天后就会觉得回不去了。随着App Router逐渐成熟，现在的T3脚手架默认也用app/目录，布局、加载状态、错误边界都可以用文件命名来定义，组织代码的思路非常清晰。

2.3 Tailwind CSS：不用再纠结样式架构

Tailwind CSS是T3里最“轻”的一环，但也是很多人刚开始最不适应的一个。它的思路不是预定义好组件库，而是提供一套原子类，让你在HTML里直接组合出样式。不用再建一堆CSS文件、想类名命名规范、处理样式冲突。

我的体验是，Tailwind真正解决的是“全局样式失控”的问题。以前写CSS，越写越多，改一个按钮样式得全局搜索影响范围。用Tailwind之后，样式跟着组件走，删组件就等于删样式，不会留垃圾代码。配合VS Code的Tailwind插件，写类名时会有补全和预览，效率确实高。

如果你担心页面风格会乱，我建议配合组件库使用，比如shadcn/ui。shadcn/ui的思路很有意思——它不发布npm包，而是把组件源码直接复制到你的项目里，你可以任意改样式，完全脱离黑盒。这个搭配在T3社区里几乎是标配。

2.4 tRPC：端到端类型安全的关键角色

终于说到T3名字里的核心——tRPC。它解决的问题是：在前后端之间调用函数时，类型能自动保持一致，不需要手写REST接口、不需要手写类型定义、不需要生成API文档。

tRPC的思路是用TS来写服务端函数，然后把这些函数暴露成可被前端直接“导入”的调用。前端调用时就像调用本地函数一样，写法是trpc.post.getAll.query()，但实际上它背后发的是HTTP请求。关键在于，返回值的类型通过TypeScript的类型推断，自动传递到了前端，不需要你手动写任何接口类型。

// 服务端定义（router/post.ts） import { z } from "zod"; import { router, publicProcedure } from "../trpc"; export const postRouter = router({ getAll: publicProcedure.query(async ({ ctx }) => { // ctx里可以拿到prisma实例 return ctx.prisma.post.findMany({ orderBy: { createdAt: "desc" }, }); }), getById: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) => { return ctx.prisma.post.findUnique({ where: { id: input.id }, }); }), });

// 前端调用（components/PostList.tsx） import { trpc } from "../utils/trpc"; export function PostList() { const { data, isLoading } = trpc.post.getAll.useQuery(); if (isLoading) return <div>加载中...</div>; return ( <ul> {data?.map((post) => ( <li key={post.id}>{post.title}</li> ))} </ul> ); }

你看，getAll返回的post数组类型，在data?.map那里已经被TS准确推断出来了。如果后端改了返回字段，前端立刻标红，根本不需要跑一遍接口联调才知道出问题。这也是tRPC相比传统REST/GraphQL的最大优势——前后端共享类型上下文。

2.5 Prisma：让数据库操作也变成类型安全的

Prisma是T3里的数据库ORM（对象关系映射）。它的特点是：用Schema文件描述表结构，自动生成类型完备的客户端代码。你操作数据库就像操作一个类型安全的API，不需要手写SQL，也基本不用关心SQL注入问题。

// prisma/schema.prisma generator client { provider = "prisma-client-js" } datasource db { provider = "postgresql" url = env("DATABASE_URL") } 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 }

定义好Schema之后执行npx prisma migrate dev，Prisma会生成迁移SQL并同步更新Client代码。之后你在业务代码里调用prisma.post.create()时，所有字段都会被TS检查，title不能传数字，authorId不能传成一个不存在的用户，写错了编译期直接报错。

这种“数据库表结构也纳入类型体系”的做法，是T3链路能全链路类型安全的关键一环。Prisma在这里承上启下——上对接tRPC的服务端，下对接数据库本身。

2.6 NextAuth.js：认证方案不用重复造轮子

认证是每个全栈应用几乎躲不开的模块。T3默认集成NextAuth.js（现在叫Auth.js），支持邮箱密码、GitHub、Google等多种登录方式，还提供JWT或数据库会话两种会话模式。

我最常用的是CredentialsProvider配合Prisma校验用户密码。过程中有几个容易踩的坑，我后面专门写一节。这里先说核心设计：NextAuth接受你传入的authorize回调，在里面查询数据库比对密码，成功后返回用户对象，会话里再挂上用户ID，tRPC的上下文里就能读到当前登录用户，实现“只有登录了才能调某些接口”的逻辑。

// pages/api/auth/[...nextauth].ts import NextAuth from "next-auth"; import CredentialsProvider from "next-auth/providers/credentials"; import { prisma } from "../../../server/db"; import bcrypt from "bcryptjs"; export default NextAuth({ providers: [ CredentialsProvider({ name: "账号密码", credentials: { email: { label: "邮箱", type: "email" }, password: { label: "密码", type: "password" }, }, async authorize(credentials) { const user = await prisma.user.findUnique({ where: { email: credentials?.email }, }); if (!user) return null; const ok = await bcrypt.compare(credentials?.password ?? "", user.passwordHash); if (!ok) return null; return { id: user.id, email: user.email, name: user.name }; }, }), ], session: { strategy: "jwt" }, callbacks: { session({ session, token }) { if (token.sub) session.user.id = token.sub; return session; }, }, });

3. 从零搭建T3项目：完整实操记录

理论说了这么多，下面直接上手。我用一个“文章发布系统”作为示例项目，把T3全流程走一遍，附带我实际踩过的坑和调整过程。

3.1 初始化项目与目录结构认知

创建T3项目非常简单，官方提供了脚手架命令。我在终端里执行：

npx create-t3-app@latest t3code-demo

运行后它会问你要启用哪些模块，我的选择是：Next.js（App Router模式）、TypeScript、Tailwind CSS、tRPC、Prisma、NextAuth.js，全部勾上。这里有个小建议：如果暂时用不到认证，可以不选NextAuth，免得被一堆初始代码干扰。但既然要体验完整链路，我建议你全选，看看它们之间的接线是怎么走的。

生成后的目录结构大致如下：

t3code-demo/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── pages/ │ │ └── api/ │ │ ├── auth/[...nextauth].ts │ │ └── trpc/[trpc].ts │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ ├── root.ts │ │ │ └── trpc.ts │ │ ├── auth.ts │ │ └── db.ts │ ├── styles/ │ │ └── globals.css │ ├── utils/ │ │ └── trpc.ts │ ├── app/ │ │ └── page.tsx │ └── trpc/ │ └── server.ts └── package.json

脚手架生成的文件虽然不少，但每个文件职责清晰：server/下管后端逻辑，utils/trpc.ts是前端的tRPC客户端入口，app/是页面代码。刚接触时别急着改代码，先把这些文件的引用关系走一遍，你会对整个数据流有直观感觉。

初次运行前一定要设置环境变量。复制.env.example为.env，把DATABASE_URL改成你数据库的连接串，NEXTAUTH_SECRET用openssl rand -base64 32生成一个随机值。不设置NEXTAUTH_SECRET，NextAuth运行时会直接崩。

3.2 定义数据模型并同步数据库

在prisma/schema.prisma里新建两个模型：用户和文章，并建立一对多关系。我在前面已经给了Post的示例，这里直接把它扩展完整。定义好后执行：

npx prisma migrate dev --name init

这个命令会做三件事：生成迁移SQL、执行迁移、重新生成Prisma Client。执行过程中如果报“环境变量缺失”之类的错，那多半是.env没放对位置，或者变量名不是DATABASE_URL。注意Prisma读取的是项目根目录的.env文件，不是src/里的。

调试数据库结构时，我习惯用npx prisma studio打开一个可视化面板，直接看表结构和数据。这比在终端里敲SQL直观得多。改完数据模型后，记得再跑一次npx prisma migrate dev，保持同步。

3.3 编写tRPC路由：从查询到受保护接口

模块生成后，我先在src/server/api/routers/post.ts里实现了getAll和getById两个查询接口，代码结构和第一节展示的一致。

接着我要加一个“仅登录用户可创建文章”的接口。这就用到了tRPC的protectedProcedure——它从请求上下文中读取会话信息，如果未登录就抛异常，登录了才继续执行。

// routers/post.ts 补充 import { protectedProcedure } from "../trpc"; export const postRouter = router({ // ...getAll, getById 略 create: protectedProcedure .input( z.object({ title: z.string().min(1), content: z.string().min(1), }) ) .mutation(async ({ ctx, input }) => { // ctx.session里的userId由NextAuth会话提供 return ctx.prisma.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });

这里有一个容易搞混的点：protectedProcedure的ctx.session类型依赖于src/server/auth.ts里的会话配置。如果你自定义了NextAuth的callbacks，一定要确保返回了session.user.id，否则写ctx.session.user.id时会编译报错。类型没对上其实是个好信号——说明你的会话配置和tRPC上下文类型不一致，运行起来必炸。

前端调用create时也直观：

const utils = trpc.useUtils(); const createPost = trpc.post.create.useMutation({ onSuccess: () => { utils.post.getAll.invalidate(); }, }); createPost.mutate({ title: "标题", content: "内容" });

invalidate()的作用是主动让getAll这个查询重新拉取，实现提交后列表自动刷新的效果。这比手动刷新页面或本地改状态都干净。

3.4 前端页面接入与数据流串通

页面部分我做了两件事：文章列表展示和提交表单。整体代码不长，核心在于从utils/trpc导入客户端实例，然后调用useQuery拿到数据。

// app/page.tsx import { trpc } from "../utils/trpc"; import { CreatePostForm } from "../components/CreatePostForm"; import { PostList } from "../components/PostList"; export default function HomePage() { return ( <main className="mx-auto max-w-3xl p-8"> <h1 className="text-3xl font-bold">t3code 文章系统</h1> <CreatePostForm /> <PostList /> </main> ); }

这里有个重要细节，必须提醒你。如果你把PostList写成服务端组件（默认行为），里面对trpc的调用会报错——因为tRPC客户端依赖浏览器端的状态管理。解决方案是在组件文件顶部加"use client"声明，让它变成客户端组件。从脚手架目录里可以看到components/下的组件默认都加了"use client"，原因就在这里。

同样地，表单提交流程里，我把useMutation的调用放在CreatePostForm组件内，提交时直接调用createPost.mutate()，提交后通过onSuccess里的invalidate刷新列表。整个流程没有手写任何fetch请求、没有手写任何接口地址，类型也从数据库一直传导到页面，跑通了整条链路。

3.5 部署时的环境变量与构建检查

本地跑通后，部署是老生常谈但最容易翻车的一环。我用的是Vercel加托管PostgreSQL的组合。

部署到Vercel前，需要在项目设置里配置环境变量：DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL。其中NEXTAUTH_URL在Vercel上要填你的正式域名，本地开发时它会自动读取，但部署环境必须手动配置。漏了这个，线上登录时会直接白屏或跳转异常。

有一个坑我印象很深：本地开发时NEXTAUTH_SECRET我随便填了一串字符，线上也想当然复制过去，结果部署上去登录接口一直报“Invalid secret”。检查半天发现是复制时少了一位，openssl rand生成的内容别手欠截断，直接整段用就行。这个问题排查起来不复杂，但没有任何报错能明确提示是secret位数不对，只能一个个排查环境变量，非常浪费时间。

4. 常见问题与排查技巧实录

这部分整理我在多个T3项目里遇到的真实问题，每个问题都附上排查思路。做了一张速查表，你可以直接收藏备用。

4.1 前端调用tRPC接口时类型不同步

症状：后端改了一个字段，但前端调用useQuery处没有提示类型变化，或者提示的还是旧类型。

原因：前端引用的类型是通过@tanstack/react-query和tRPC的类型推断链接保持的，如果类型没更新，绝大多数是前后端进程没有同时重启。尤其是服务端代码变动后，Next.js的增量编译有时候不会立刻更新所有类型引用。

排查顺序：

1. 确认两端都重启了开发服务器（Ctrl+C后重新npm run dev）。
2. 检查是否有重复的trpc客户端实例，比如你在组件里直接createTRPCNext而不是从utils/trpc统一导出，就会导致类型断链。
3. 如果是改了Prisma模型，记得重新跑npx prisma generate。
4. 实在不行就删掉.next缓存目录再重启，我遇到过一次这个问题，删缓存解决。

我在实际项目中，把“重启开发服务器”当成改完类型的固定动作，团队里也约定好：改了服务端类型必须重启，不是按保存就好。

4.2 NextAuth运行时出现“MissingSecret”或“Unable to decode token”

这个是T3项目里遇到率最高的认证问题。核心原因基本都在环境变量上。

排查清单：

• NEXTAUTH_SECRET有没有设置，长度够不够。用openssl rand -base64 32生成一个完整的字符串。
• 本地开发时NEXTAUTH_URL可以不设，但部署时必须等于你的对外域名（不要带尾斜杠）。
• 确认你是不是把.env文件提交到了Git仓库。如果提交了，浏览器端其实不会直接读到，但第三方CI构建日志里可能会泄露，安全风险很大，要在.gitignore里排除掉。

另外，如果有多个环境（预览分支和主分支共用同一个数据库和secret），NEXTAUTH_URL填的是单个地址，会导致另一个环境的会话重定向错乱。我的做法是每个环境一套独立的变量组，预览环境单独分配一个测试数据库，避免互踩。

4.3 tRPC的上下文没有返回session导致报错

自己在脚手架上扩展代码时，很容易在src/server/api/trpc.ts里调整createContext的逻辑。如果你发现protectedProcedure里拿不到ctx.session，先检查createContext是否已经正确调用了getServerSession。

// src/server/api/trpc.ts 关键片段 import { getServerSession } from "next-auth"; import { authOptions } from "../auth"; export const createTRPCContext = async (opts: { headers: Headers }) => { const session = await getServerSession(authOptions); return { session, db: prisma, ...opts, }; };

还有一个隐蔽问题：如果你在src/app目录下用App Router，getServerSession必须接收authOptions参数，不能直接无参调用。同时确认authOptions是从src/server/auth.ts导出，而不是在pages/api/auth/[...nextauth].ts里内联定义——虽然内联也行，但两头引用容易产生两套不同配置，类型和实际行为对不上。这种问题排查起来极其费神，原因就是“看似一样的代码走了两条路”。

4.4 Prisma迁移时卡住或锁表

多人协作时经常会遇到：同事改了Schema提交了迁移文件，你拉代码后直接npx prisma migrate dev发现冲突，或者提示database is locked。

我的处理方法是：

1. 先把本地数据库重置：npx prisma migrate reset，会清空数据重新应用所有迁移，开发环境无所谓。
2. 如果迁移文件冲突，手动把prisma/migrations目录下不冲突的执行顺序整理一下，或者删掉本地多余的迁移文件，重新生成一个干净的初始迁移。

注意：migrate reset会清空全部数据，生产库万万不能用。属于开发环境的“暴力但好用”的大招。

4.5 部署后页面正常但“提交表单一直转圈”

这个是网络请求层面的问题。表单提交按钮一直loading，说明请求发出去了但没回来。原因通常是：

• 服务端API路由没有在Vercel上正确构建，检查日志里有没有Failed to resolve ... trpc的记录。
• 数据库连接串填错了。PostgreSQL托管服务的外网地址和Vercel内部访问地址可能不同，去数据库服务商后台核对一下连接的host和端口。
• 认证会话在跨域请求情况下被拦截，确认前端域名和API域名是否一致，如果用了自定义域名但Vercel自动分配域名还在，会触发CSRF保护。

4.6 T3常见问题排查速查表

5. 我的T3项目实操体会与适用场景判断

写到这里，我发现T3 Stack最迷人的地方反而不是它某个具体技术有多牛，而是它把“端到端类型安全”这件事从理想变成了默认状态。

在实际项目里，我能感受到几个明确的好处。第一是重构成本大幅下降。以前改一个数据库字段，你翻遍前端页面找哪些地方用了这个字段，现在编译器直接告诉你哪里错了，挨个改就行。第二是新成员上手速度变快了，新同事看代码时，类型本身就成了活文档，从路由到数据库层层明确，遇到不熟悉的领域，看一眼类型定义就知道数据长什么样。第三是全栈联调几乎消失了，以前前后端分开开发，联调时至少花两三天对接口、追bug，T3模式下类型不对编译都过不了，联调时间压缩到基本可以忽略。

不过，T3也绝不是万能药，它有自己的适用边界。不适合T3的场景我给你捋一捋。

如果你的项目需要对外提供RESTful API或GraphQL接口，供第三方客户端调用，那tRPC基本帮不上忙，它自己的设计目标是“内部前后端调用”，面向外部暴露API时还是要用传统方案。如果你的团队里前端和后端分工明确、分别维护独立的代码仓库，那T3的类型共享优势就会大打折扣，因为跨仓库根本享受不到类型流动。如果你的应用非常依赖复杂的实时通信或微服务架构，T3的默认形态也帮不了太多。

反过来，强烈推荐T3的场景是：内部工具、管理后台、小型到中型的全栈Web应用，尤其是那种从零起步、团队规模不大但都愿意写TS的项目。这类场景下，少做选择就是最大的生产力。

经过这几个项目的磨炼，我自己形成了一套固定的选型标准：先用create-t3-app起项目，然后按需裁剪。用不到NextAuth就去掉，用不到Prisma就换别的数据访问方式。脚手架只是起点，不是终点。T3最大的价值，就是给你提供了一条默认路径，让你不用从一开始就陷入“这个框架配那个库合理吗”的选择焦虑里。

最后再分享一个在实际开发里让我省了很多事的小技巧：在zod里定义输入校验时，尽量把可复用的Schema提取到公共文件里，比如src/common/validation/post.ts。这样前端做表单校验时可以直接复用同一份Schema，和后端校验完全一致，不用前端一套规则、后端一套规则。我一开始图简单把校验逻辑写在路由文件内部，等前端要复用时就傻眼了，只能再复制一份，两边后来还出现了不一致的bug。统一Schema之后，这类问题彻底消失。

T3这套组合让我体会最深的，是“类型安全不是后端或前端某一侧的奢侈品，而是贯穿整个项目始终的基本盘”。如果你准备从零开始一个新项目，或者正被接口联调搞到怀疑人生，不妨按这篇文章的思路，用create-t3-app起一个最小应用跑通链路，感受一下从数据库到按钮全都对得上的体验，大概率你也会跟我一样，再也不想回到手工维护接口文档的日子。