企业官网建设流程全解析

做全栈开发这几年，我越来越依赖一套固定搭配：Next.js做应用外壳，TypeScript兜底类型，Tailwind写样式，tRPC把前后端接口变成“本地函数调用”。这套组合有个名字，就叫T3 Stack，社区里经常用t3code这个标签来指代基于这套技术栈的实践项目和模板。我第一次接触它是在一个周五晚上，原本计划花两天搭一个带用户登录和数据库写入的小工具，结果用了四个小时就跑通了全链路，当时心里只有一个念头：原来全栈开发的体验可以这么顺畅。

很多朋友问我，T3 Stack到底牛在哪里？我的回答是一条算账逻辑：以前写一个全栈功能，我至少要在四个地方维护类型和接口定义——数据库字段、服务端路由、前端API封装、页面组件的DTO。任何一个字段改名，都是一场连锁修改事故。而t3code这套东西把这条链路压缩成了几乎一条线。它特别适合两类人：一类是独立开发者和小团队，想在最短时间内把一个带真实数据的Web应用跑起来；另一类是已经熟悉React、但每次写全栈项目都要在接口定义、状态管理、样式方案里反复纠结的人。如果你也受够了前后端联调时对着字段文档来回擦，这套技术栈值得花一个周末认真试一遍。

1. 从T3 Stack到t3code：为什么这套组合值得学

1.1 名字里的三个核心组件

t3code里的“T3”，指的是TypeScript、Tailwind CSS和tRPC，这是整套技术栈最核心的三块拼图。

TypeScript是JavaScript的静态类型超集。它让你的IDE能在敲代码的同时揪出拼错变量名、传错参数类型、给对象赋了不存在的字段这类低级问题。对一个多人协作或者生命周期较长的项目来说，这层类型保障带来的收益怎么强调都不为过。

Tailwind CSS是原子化CSS框架。它不提供现成的按钮、卡片这类组件，而是提供一批工具类，比如px-4 py-2 bg-blue-500 rounded-lg，你直接在HTML标签上组合这些类就能得到完整样式。它的核心优势是约束性强：所有间距、配色、圆角都来自设计令牌，不会出现随意写死一个十六进制色值的事。

tRPC则是这套组合里最有个性的一个。它允许你在前端直接调用后端函数，类型信息全程自动推导。比如服务端定义了一个post.list，前端立刻获得一个带完整返回类型的post.list.useQuery()，不需要手写接口文档，也不需要手动生成客户端SDK。

这三个组件并不是随便拼凑在一起的。它们的共同思路是把“运行时的错误”尽量变成“编译期的错误”。CSS类名拼错了，Tailwind的构建阶段会报出来；接口字段名写错了，tRPC的前端调用会直接报类型错误；数据模型字段改了，Prisma生成的类型会同步暴露所有受影响的地方。这种把错误前置到写代码阶段的开发模式，恰恰是全栈项目最需要的东西。前后端联调过程中最耗时的往往不是逻辑本身，而是两边对字段、对类型、对文档的琐碎沟通，t3code把这部分沟通成本直接消灭在编译器和IDE的提示里了。

1.2 加上Next.js、Prisma和NextAuth之后的全貌

严格来说，T3 Stack不止上面三个成员。create-t3-app默认还会把Next.js、Prisma和NextAuth.js一起装进来。Next.js负责路由、SSR、静态生成和API路由，是整个应用的外壳；Prisma是数据库访问层，能直接从你的schema定义里自动生成完整类型；NextAuth.js处理登录认证，支持GitHub、Google这类OAuth服务商，也支持邮箱和账号密码这类凭据登录。

把这几个工具组合起来后，一个典型项目的工作流变成这样：你用Next.js写页面，页面里直接调用tRPC暴露的函数；请求到达服务端Router后，Router里的函数通过Prisma读写数据库；用户登录状态由NextAuth的session统一管理。类型从数据库模型开始，一路贯穿到页面组件，中间没有一次手写any，也没有一份重复声明的接口类型。

我一开始对这种“全链路类型安全”持保留态度，觉得链条多了容易出乱子。真正跑完一个项目才发现，这套链路在中小型应用上非常稳固：各层各司其职，出了问题也能靠类型定义快速定位。所有依赖都在一个Next.js应用里，部署起来就是一个单体应用，运维负担也很低。

1.3 适用边界：它不是什么万能模板

我还是想把适用范围说清楚，免得大家觉得我在无脑吹。它最适合的项目是：带登录系统的内部工具、个人作品集、MVP原型、CMS后台、团队协作小应用。这类项目的共性是：需要快速开发、数据关系不复杂、业务模式相对固定。T3 Stack能极大压缩前后端联调的时间，这是它最亮眼的优势。

它不太适合的场景：第一，需要跟大量第三方服务深度集成、以接口兼容为核心矛盾的项目；第二，团队里没人写过TypeScript、短时间内学不进tRPC这种抽象的项目；第三，已经有一套成熟后端系统、并且短期内不能替换的项目。在这些情况下，强行把T3 Stack塞进去反而会增加迁移成本。技术选型的黄金法则是贴合团队现状，而不是追逐新东西。工具本身不会让项目厉害，让项目厉害的是团队对工具链的熟练度和对业务的理解。

2. 从零初始化一个t3code工程

2.1 脚手架命令与交互选项

初始化一个t3code项目非常直接，在终端执行：

npm create t3-app@latest my-app

如果你是pnpm或yarn用户，换成对应的命令即可。执行后它会问你：要不要TypeScript、Tailwind、tRPC、Prisma、NextAuth、ESLint和prettier。第一次体验时我的建议是全部选Yes，先把完整技术栈跑通，之后再按需求做减法。这几个选项之间是有关联的，比如你选了tRPC通常就得选TypeScript，选了NextAuth基本就要搭配Prisma，因为会话和用户数据需要落地到数据库。

命令跑完后，脚手架会创建目录、安装依赖、生成基础配置文件。这里有个会让新手困惑的点：为什么它没有立刻建好数据库？因为create-t3-app并不知道你用的是PostgreSQL还是MySQL还是SQLite，数据库连接串需要你自己填到.env文件里。它默认的Prisma schema通常是一个极简的Post模型，方便你直接体验。

2.2 关键目录与文件职责

创建完之后的目录大致长这样：

. ├── prisma/ │ ├── migrations/ │ │ └── migration_lock.toml │ └── schema.prisma ├── public/ ├── src/ │ ├── pages/ │ │ ├── api/ │ │ │ ├── auth/ │ │ │ │ └── [...nextauth].ts │ │ │ └── trpc/ │ │ │ └── [trpc].ts │ │ ├── _app.tsx │ │ └── index.tsx │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ │ └── post.ts │ │ │ ├── root.ts │ │ │ └── trpc.ts │ │ ├── auth.ts │ │ └── db.ts │ ├── styles/ │ │ └── globals.css │ └── utils/ │ └── api.ts ├── .env ├── next.config.mjs ├── package.json ├── tailwind.config.ts └── tsconfig.json

最重要的三个文件，我建议先看：src/server/api/trpc.ts是tRPC的初始化工厂，定义了公共Procedure和受保护Procedure，后面所有Router都基于它创建；src/server/api/root.ts是总装配车间，汇总所有子Router，导出统一的appRouter；src/server/db.ts是Prisma客户端实例，遵循全局单例模式，避免开发环境下连接池被反复创建。

如果你第一次接触tRPC，看到这堆文件难免有点晕。简单打个比方：trpc.ts是工厂流水线，root.ts是总装配车间，routers目录下每个文件是具体工序，最后appRouter会被挂到Next.js的API路由src/pages/api/trpc/[trpc].ts上。前端所有的trpc.xxx调用，最终都会走到这个API路由去执行。

我踩过的一个坑是直接复制别人的目录结构塞进自己的项目，结果tsconfig里的路径别名~/*没有配置好，导入全部报红。所以如果你手动调整文件位置，一定要同步改tsconfig.json和next.config.mjs里的路径映射。

2.3 数据库连接与第一次迁移

打开.env文件，你会看到类似这样的占位符：

DATABASE_URL="postgresql://postgres:password@localhost:5432/mydb?schema=public"

改成你本地PostgreSQL的真实用户名、密码、端口和库名。如果暂时不想装数据库，可以先切换到SQLite，把连接串改成：

DATABASE_URL="file:./dev.db"

同时把schema.prisma顶部的provider改成sqlite。然后运行：

npx prisma db push

这个命令会把schema.prisma中的模型同步到数据库，并生成Prisma Client。注意，如果跳过这一步，后面所有涉及数据库的类型都会是空的，启动项目会报模型或类型找不到。

我的习惯是先用SQLite做原型，把业务逻辑跑通后再切换到PostgreSQL。切换的时候改.env的DATABASE_URL，然后执行npx prisma migrate dev --name init。SQLite和PostgreSQL之间有一些数据类型差异，比如SQLite没有原生枚举，但大多数常见场景都不受影响。你只要记住，db push适合开发阶段快速迭代，migrate dev适合正式记录每一次schema变更，这个区别后面部署时还会再遇到。

3. 用tRPC把核心业务链路打通

3.1 从Prisma模型说起：让类型有源头

现在用一个具体的例子来讲。假设要实现一个团队周报系统：用户登录后能提交周报，所有已登录用户能看到周报列表。先打开prisma/schema.prisma，把默认的示例模型替换成：

model User { id String @id @default(cuid()) name String? email String? @unique posts Post[] } model Post { id String @id @default(cuid()) title String content String authorId String author User @relation(fields: [authorId], references: [id]) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

然后执行npx prisma db push。这里有个容易忽略的细节：User模型一般不要手动改动关键字段，尤其不要随意改id、email这些被NextAuth依赖的字段；你可以在上面补充业务字段，比如name、email这类个人资料字段，再添加与业务模型的关联关系。

Prisma这个ORM跟传统ORM有个明显差别：它把模型定义作为唯一事实来源。模型一改，生成的客户端类型立即更新。这意味着后续所有使用prisma.post.create的代码都会在编译期拿到最新的字段约束，不太可能出现数据库字段和代码逻辑悄悄脱节的情况。

3.2 定义Router：查询、变更与输入校验

在src/server/api/routers/post.ts里定义周报的查询和创建：

import { z } from "zod"; import { createTRPCRouter, publicProcedure, protectedProcedure } 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(120), 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表示必须登录后才能调用。创建周报天然应该用protectedProcedure，因为我们需要在服务端拿到ctx.session.user.id来记录作者。

输入校验直接交给zod。标题限制在120个字符以内，正文不能为空。如果输入不合法，tRPC会自动返回带明确错误码和错误信息的响应，不用你写一套冗长的if判断。服务端拿到的input，类型已经被精确推导成{ title: string; content: string }，不用再手动断言。

还有一个细节要提醒：query和mutation的区别不只是语义上的。query会被React Query当作GET请求缓存，适合读操作；mutation不会缓存，每次都执行副作用，适合写操作。在页面里写提交逻辑时，不要因为图省事把写操作用query去表达，缓存机制会给你带来额外的麻烦。

3.3 在页面组件里调用tRPC

页面组件里使用tRPC，体验非常接近调用本地hook。先确认src/utils/api.ts里已经导出了封装好的trpc对象，然后在组件中这样写：

import { useSession } from "next-auth/react"; import { trpc } from "~/utils/api"; export default function HomePage() { const { data: session } = useSession(); const { data: posts, isLoading } = trpc.post.list.useQuery(); const utils = trpc.useUtils(); const createPost = trpc.post.create.useMutation({ onSuccess: () => { utils.post.list.invalidate(); }, }); if (isLoading) return <div>加载中...</div>; return ( <div> {session ? ( <button onClick={() => createPost.mutate({ title: "周报", content: "本周工作内容..." })}> 提交周报 </button> ) : ( <button onClick={() => signIn()}>登录</button> )} <ul>{posts?.map((post) => <li key={post.id}>{post.title}</li>)}</ul> </div> ); }

这段代码里，trpc.post.list.useQuery()会自动发起请求、管理loading状态、缓存结果。提交后调utils.post.list.invalidate()，tRPC会重新请求列表，页面立刻更新，不需要手动刷新或写全局事件。

这种编程方式最大的变化是：前端代码对“后端接口”的感知消失了。当你需要一个新的数据读取能力，去服务端加一个procedure，前端立刻就能在类型提示里看到它。协作时甚至不需要单独维护一份API文档，类型定义本身就是活的文档。当然，这也意味着你的代码仓库最好具备比较完整的类型覆盖，不然“自动推导”的效果会打折扣。

3.4 挂载Root Router，别漏这一步

新写的Router不会自动生效，必须注册到src/server/api/root.ts里：

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

如果这一步漏掉，前端调用trpc.post.list时会直接报类型错误，类型定义里根本没有post这个命名空间。遇到这种错误时，第一反应应该是检查Root Router有没有注册，而不是去翻前端的调用代码。

我还建议在root.ts里用一个文件集中管理所有router的import，避免每个页面单独引入零散的router。项目变复杂以后，你会发现这种集中注册的方式让新增模块变得非常机械：写一个router文件，在root.ts里挂两行，跑到页面上刷新看结果。所有功能模块都沿着同一条路走，没有任何特例，团队协作时也不需要解释“这个功能为什么走的是另一条路径”。保持这种统一性，收益在后期的维护阶段会非常明显。

4. 认证接入与样式细节：从能跑通到像产品

4.1 NextAuth配置与第一个登录按钮

登录认证是大多数业务系统的刚需。T3项目里默认集成了NextAuth，适配器用的PrismaAdapter，所以用户表结构会由NextAuth在数据库里自动创建。打开src/server/auth.ts，配置Provider：

import { NextAuthOptions } from "next-auth"; import { PrismaAdapter } from "@next-auth/prisma-adapter"; import GitHub from "next-auth/providers/github"; import { db } from "~/server/db"; export const authOptions: NextAuthOptions = { adapter: PrismaAdapter(db), providers: [ GitHub({ clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, }), ], callbacks: { session: ({ session, user }) => { if (session.user) { session.user.id = user.id; } return session; }, }, };

.env里必须填三个值：

GITHUB_CLIENT_ID=xxxxx GITHUB_CLIENT_SECRET=xxxxx NEXTAUTH_SECRET=xxxxx

NEXTAUTH_SECRET可以用openssl rand -base64 32生成一个随机串。这个值是用来给session cookie做签名的，一旦设置，生产环境就不要随意更换，否则所有用户会被强制登出。

前端使用非常简单。useSession()会返回当前用户状态，signIn("github")发起登录，signOut()退出。页面里判断session.user存在就显示内容，否则显示登录按钮。注意一个细节：在开发环境，OAuth回调地址一般是http://localhost:3000/api/auth/callback/github；到了生产环境，你要保证回调地址的域名和实际访问域名一致，否则会看到redirect_uri_mismatch。

很多团队在配置这一步时把GitHub的Client Secret直接写进代码仓库的.env.example里，这是很低级的失误。生产环境的密钥应该只存在于部署平台的环境变量面板中，本地.env决不要提交到Git。

4.2 用Tailwind快速做出产品感界面

Tailwind在T3项目里是开箱即用的。我来演示一个常见的卡片列表样式：

<div className="mx-auto max-w-3xl px-4 py-8"> <div className="space-y-4"> {posts?.map((post) => ( <article key={post.id} className="rounded-xl border border-gray-200 p-5 shadow-sm transition hover:shadow-md" > <h2 className="text-lg font-semibold text-gray-900">{post.title}</h2> <p className="mt-2 text-sm text-gray-600">{post.content}</p> <p className="mt-3 text-xs text-gray-400">{post.author.name}</p> </article> ))} </div> </div>

如果你之前主要写CSS，第一次看到这类代码会觉得有点“乱”。但用一段时间后你会意识到，原子类的优势在于把样式和结构放在同一个视口里：想改圆角，把rounded-xl改成rounded-2xl；想改间距，调整p-5。它带来的心智负担远小于维护几十条语义化CSS类名。

要让界面风格保持一致，关键是在项目里约定好尺寸和颜色体系。比如卡片统一用rounded-xl、页面内容区统一用max-w-3xl px-4 py-8、主要操作按钮统一用bg-blue-600 text-white px-4 py-2 rounded-lg。这种设计约束比任何设计系统文档都管用，因为它直接写进了代码使用习惯里。

4.3 样式复用：别让代码里堆满重复的类名

页面一多，重复的卡片类名就让人受不了。我的做法是用Tailwind的@layer components注册一个组合类：

@layer components { .card-panel { @apply rounded-xl border border-gray-200 p-5 shadow-sm; } .btn-primary { @apply bg-blue-600 text-white px-4 py-2 rounded-lg hover:bg-blue-700; } }

然后页面里只需要写className="card-panel"或者className="btn-primary"。这套思路非常适合CRUD密集的中后台项目，组件本身不用封装得太重，模板线也能保持清晰。

要注意，@apply在Tailwind v4里使用方式有些变化，如果你用的版本较新，编译报错时可以查一下对应文档。总的原则是一样的：把复用频率高的样式组合沉淀下来，把一次性的样式留在页面里。这样后续维护时，改动一件小事不用翻十几个文件。我还会把这些组件类集中放在globals.css的一个固定区域里，加注释说明用途，其他同事接手时很容易形成共识。

5. 部署上线：把Demo变成生产环境

5.1 数据库迁移的正确姿势

本地开发时我用npx prisma db push直接同步schema，方便是方便，但生产环境千万不能这么干。生产环境的正确流程是：先在本地修改schema，用npx prisma migrate dev --name 本次变更描述生成一个正式迁移文件；把代码提交后，在部署平台执行npx prisma migrate deploy。

迁移文件本质上是一段带版本号的SQL变更记录。Prisma会记录哪些迁移已经应用过，哪些还没应用，然后按顺序把未执行的迁移跑完。db push在开发阶段会直接根据当前schema重建表结构，如果有旧数据，某些字段调整可能触发重建表，造成数据丢失。

我之前就踩过一次：开发阶段用了SQLite，准备切换生产PostgreSQL时偷懒直接db push，结果一张表的结构被重建，生产数据险些全没。后来我给自己立了一条规矩：凡是涉及生产环境的schema变更，一律走migrate流程，并且先在测试库执行一遍确认无误再上生产。

5.2 部署平台选择与构建流程

T3应用本质上是标准的Next.js应用，因此部署路径和普通Next项目类似。最简单的方案是Vercel：把代码推到Git仓库，在Vercel新建项目、关联仓库、填入环境变量，构建完就上线了。

生产数据库可以用托管PostgreSQL服务，比如Neon、Supabase、Railway，也可以直接用Vercel Storage中的数据库预设。如果数据库和Web应用部署在不同区域，连接延迟会高一些，这时候通常把DATABASE_URL里的连接池地址和直连地址分开填写，托管服务一般都会提供这两个地址。

如果你习惯用自己的云服务器，也可以用Docker跑构建产物。流程大约是：服务器装好Docker和Node 20+，拉代码后执行npm ci && npm run build && npm run start。线上用npm start之前，记得先执行一次npx prisma migrate deploy，然后启动应用。

很多问题都出在构建阶段：本地build通过，部署平台却失败。常见原因包括环境变量缺失、数据库权限不足、或者Node版本不一致。排查时把部署日志从头读到尾，重点看报错堆栈里第一个Error出现在哪一步。

5.3 环境变量最容易翻车的三个场景

部署上线的各种错误里，环境变量相关问题能占一半以上。归纳下来，最常见的三个场景是：

注意：生产环境的NEXTAUTH_SECRET一旦设置就不要更换，否则所有有效session都会失效，用户会集体掉线。

上面这张表我是在多次痛苦排障后总结出来的。每次上线前，发布清单里一定包含这三项核验：数据库可连通、密钥齐全、回调地址无误。这一步检查的时间通常不超过五分钟，却能省下半夜紧急回滚的狼狈。

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

6.1 改了代码，前端类型不更新怎么办

tRPC的类型是通过自动生成机制暴露给前端的。你修改了Router、加了输入参数，前端类型却没有立刻跟上，这种情况很常见。我的第一选择是重启dev server：停掉npm run dev再重新运行，类型生成脚本会被重新触发。

如果重启还不行，再检查是不是用了缓存。Next.js的.next目录偶尔会出现陈旧产物，rm -rf .next后重启几乎总能解决。这类问题很容易误导人，让你怀疑业务代码里是不是写错了，其实只是类型生成没跟上。所以保持一个干净的重启习惯，能少掉不少头发。

6.2 tRPC错误代码应该看哪里

tRPC调用出错时，前端控制台会打印TRPCClientError对象。重点关注两个字段：data.code和data.message。

• UNAUTHORIZED：没登录就调用了protectedProcedure。
• BAD_REQUEST：输入参数没有通过zod校验。
• INTERNAL_SERVER_ERROR：服务端抛出了异常，需要看后端日志。

比如说创建周报时如果没登录，你会看到UNAUTHORIZED；如果标题超过了120字符，你会看到BAD_REQUEST。这两个错误占了日常错误的大半。排查时先看错误码，再顺着堆栈找到具体地方，不用乱猜。

还有一个容易被忽略的点：tRPC的errorFormatter默认会把服务端错误信息返回给客户端。生产环境如果不想暴露内部细节，可以考虑自定义errorFormatter，把内部堆栈信息剥离掉。这是上线前的一个重要收尾动作。

6.3 Prisma连接数不够用

生产环境并发量上来后，Prisma可能会报P1001或Too many connections。原因通常是连接池参数没有调优。PostgreSQL连接串可以这样设置：

DATABASE_URL="postgresql://user:password@host:5432/db?connection_limit=10&pool_timeout=5"

connection_limit控制连接池大小，pool_timeout控制获取连接的超时时间。数据库托管服务通常对连接数有限制，把连接池参数调小往往比调大更有效。还有一点：如果你的应用同时部署了多个实例，每个实例都有自己独立连接池，连接数会成倍增长。解决方案是把连接池的参数在环境变量里统一管理，并根据实例数调整。

我在一个内部工具项目里遇到类似问题，一开始以为是代码死循环，后来发现是连接池默认值太大，数据库直接拒绝新连接。调整参数后立刻恢复，原本以为要排查很久的故障就在两分钟内解决了。

6.4 NextAuth OAuth回调失败的排查顺序

点击GitHub登录后跳转到一个报错页面，这是NextAuth接入时最常见的故障。我的排查顺序非常固定：

第一，确认生产环境的NEXTAUTH_URL跟实际访问域名完全一致。域名末尾不要有多余斜杠，也不要用localhost。

第二，确认OAuth应用管理后台填写的回调地址是https://你的域名/api/auth/callback/github，一个字母都不能差。

第三，检查Client Secret有没有被空格、换行或者错误复制污染。尤其当你在.env里手动粘贴时，很容易带上不可见字符。

第四，确认NEXTAUTH_SECRET已设置。开发模式下NextAuth会临时生成一个密钥，但生产环境如果没有设置，登录功能会直接报错。

按这个顺序排查，九成以上回调问题都能解决。每次遇到新问题，我也建议先把当天改动过的配置列出来，缩小范围后再动手。

我把这套t3code技术栈用了快两年，体验层面最大的感受是“链路摩擦”被降到了很低的水平。以前写接口、对文档、处理客户端SDK的时间，如今都省下来去真正的业务逻辑上。动手跑完一个项目后，你就会明白为什么它敢把“类型全链路内联”当成最大卖点——不是炫技，而是实打实地减少了日常开发中的琐碎操作。

当然它不是银弹。团队没有TypeScript基础、项目极度依赖第三方接口、后端系统又很庞大时，这套方案需要慎重评估。但如果你正在做一个数据模型不复杂、需要快速验证想法的Web应用，我真的建议你花一个周末跑一遍这个组合。第一次把完整链路从登录到写库再到页面展示打通的瞬间，你会发现全栈开发原来可以这么平稳顺滑。