企业官网建设流程全解析

最近我把一个内部工具项目完整地用 T3 Stack 重写了一遍，整个过程中把 t3code 这条技术路线从选型、建库、tRPC 接口到部署上线全部走了一遍。如果你也在纠结“Next.js + TypeScript 这一套到底怎么组合才最顺畅”，那这篇文章应该能给你一些可以直接抄作业的参考。我会尽量少讲空泛的概念，多讲实际操作里怎么选、怎么配、怎么避坑，以及我踩完之后回头看的真实体会。

这套技术组合适合谁？适合那些想用 TypeScript 贯穿前后端、希望数据层和 API 层都带完整类型约束、又不想在样板代码上浪费太多精力的小团队和个人开发者。它不是什么银弹，但它确实能让一个全栈项目从零到上线的时间压缩得很明显，尤其是当你需要快速验证想法或交付内部工具的时候。

1. T3 技术栈到底在解决什么问题

1.1 这套组合的来历与定位

T3 Stack 是 Theo 在社区里推动的一套全栈 TypeScript 技术选型，核心成员是 Next.js、TypeScript、tRPC、Prisma、Tailwind CSS，再按需加入 NextAuth.js。它不是一个框架，而是一种“把类型安全做到极致”的工程实践组合。t3code 这个词在社区里慢慢被用来指代“照着 T3 Stack 思路去写代码”的实战过程，核心就是让服务端、数据库和客户端之间的数据契约不再靠文档维护，而是靠类型系统自动约束。

我第一次接触这套组合的时候，其实对它是有怀疑的。tRPC 和传统的 REST API 相比，看起来只是省掉了手写接口文档和客户端请求类型，但真的值得把项目结构绑在这么一套约定上吗？用完之后我的答案是：值得，但要看场景。如果是对外提供开放 API、需要被第三方大量调用，REST 或者 GraphQL 仍然更合适。如果是内部项目、后台管理、全栈同构的 Web 应用，tRPC 带来的效率提升非常明显，因为它让“调用后端方法”像“调用本地函数”一样自然，却又保留了网络请求的边界。

1.2 为什么不是别的方案

有人会问，既然都用 Next.js 了，为什么不直接写 REST API 路由？或者用 GraphQL？我的实际感受是，REST API 在类型安全上需要大量手工维护。你可以用 OpenAPI 生成客户端类型，但生成出来的代码往往很臃肿，而且一旦服务端接口改了，客户端编译报错的时机和位置都不可控。GraphQL 能做类型化查询，但它的 schema 设计、resolver 分层和缓存策略本身就够复杂了，对一个小项目来说成本偏高。

tRPC 的聪明之处在于它并不要求你改变数据获取方式，而是完全复用 TypeScript 的类型推断能力。你写一个服务端查询函数，客户端 import 进来的是一个类型安全的代理对象，参数和返回值的类型错误在编译阶段就会被发现。再加上 Prisma 生成的数据库 Client 类型，整个链路从数据库表到 UI 组件，数据形状都是一致的，改表结构时编译器能帮你圈出所有受影响的代码。

2. 环境准备与项目初始化实操

2.1 本地开发环境清单

在开始之前，我把本地环境整理了一遍。Node.js 版本建议直接上 18 以上，最好用 20 LTS，避免某些依赖对版本敏感。我用的包管理器是 pnpm，它比 npm 的依赖解析更快，磁盘占用也小很多，后续装 tRPC、Prisma 这类依赖时体验会好不少。数据库部分，本地开发我用的是 PostgreSQL，如果你在 Windows 上不想装原生服务，可以用 Docker 起一个容器，命令非常简单：

docker run --name t3code-db -e POSTGRES_USER=t3code -e POSTGRES_PASSWORD=t3code -e POSTGRES_DB=t3code -p 5432:5432 -d postgres:16-alpine

这里我把数据库名、用户名和密码都设为 t3code，方便全局统一命名，后面连接串只需要改一个变量。如果你不熟悉 Docker，也可以直接装一个本地 PostgreSQL 客户端工具，比如 Postico 或者 pgAdmin，只要能创建数据库并拿到连接串就行。

2.2 使用脚手架初始化项目

Create T3 App 提供了非常顺滑的初始化体验，命令如下：

npx create-t3-app@latest t3code-demo

运行之后它会让你选择使用 App Router 还是 Pages Router，这一步我强烈建议选 App Router。虽然 Pages Router 更成熟，但 Next.js 官方已经把重心全面转移到 App Router，新项目没必要再从旧模式起步。在功能模块选择中，我会勾选 NextAuth.js、Prisma、Tailwind CSS 和 tRPC。如果你暂时不需要登录，NextAuth 可以先不勾，但需要说明的一点是，tRPC 模式中很多权限控制例子会基于 NextAuth，如果你明确知道项目最终要有用户体系，不要犹豫，直接勾上。

脚手架跑完后，你会得到一个已经集成好所有依赖的完整项目结构。我最欣赏这一点的是，它不像很多脚手架那样只给你一堆 Hello World 页面，而是会生成一套可运行的示例功能，包含身份验证、数据库查询、API 调用，直接把“技术骨架怎么串联”演示给你看。这份示例代码就是最好的 t3code 入门教材，我建议你保留一段时间，等真正理解后再删。

2.3 目录结构逐层拆解

初始化后的目录结构看起来复杂，但复盘下来其实脉络很清晰：

src/ server/ api/ routers/ root.ts auth.ts db.ts trpc/ server.ts client.ts app/ page.tsx api/auth/[...nextauth]/route.ts

src/server/db.ts是 Prisma Client 单例，所有数据库访问都从这走。src/server/api/routers放的是业务路由，每个文件对应一组领域能力。src/trpc/server.ts在服务端组装 tRPC 实例，src/trpc/client.ts则给客户端调用提供类型入口。我一开始看这些文件觉得多此一举，等我真去改业务代码时才发现，正是这一层薄薄的包裹让类型安全成为可能。每一层各司其职，不像传统 MVC 那样容易让逻辑堆在 controller 里。

3. 数据库建模与数据访问层实现

3.1 Prisma Schema 设计

数据库是整个应用的底层契约，Prisma 的 schema 文件就是这份契约的源代码。我的做法是，先不急着写业务代码，而是认真设计数据模型。一个典型的内容发布功能，我会这样定义：

enum PostStatus { DRAFT PUBLISHED ARCHIVED } model User { id String @id @default(cuid()) name String? email String? @unique emailVerified DateTime? image String? posts Post[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Post { id String @id @default(cuid()) title String content String status PostStatus @default(DRAFT) authorId String author User @relation(fields: [authorId], references: [id], onDelete: Cascade) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

这里有个细节值得注意：主键我统一用cuid()而不是自增整数。自增主键虽然简单，但在分布式部署、数据合并、或者对外开放 ID 时会泄露数据量信息。cuid 生成的是无序字符串，对数据库索引也友好，作为一个通用型默认值是合理的。如果你完全确定是单机小应用，用自增也行，但我不推荐。

3.2 迁移与种子数据

定义好 schema 之后，运行迁移命令：

npx prisma migrate dev --name init

这个命令会做两件事：创建一张_prisma_migrations表来记录迁移历史，同时生成全新的 Prisma Client。生成的 Client 会按最新的 schema 更新类型，这意味着你的 TypeScript 代码立刻能感知到字段变化。

种子数据对开发体验的影响很大。我的项目需要一个默认管理员账号和几篇测试文章，在prisma/seed.ts里写脚本，用upsert防止重复执行。生成密码时不要自己拼接字符串，直接用bcrypt或者@node-rs/bcrypt来做哈希。我踩过一次坑，种子脚本用了普通的 sha256，测试的时候没感觉，后面接 NextAuth 登录时才想起来密码哈希格式不对，又倒回去改，很折腾。

3.3 常见数据查询要点

Prisma 的查询 API 非常直观，但有几个性能细节不能忽略。比如查询文章列表时要关联作者信息，直接用include是最简单的方式，但如果列表页根本不需要作者的全部字段，只显示姓名，可以改用select来裁剪字段，减少网络传输和内存占用。另一个容易忽略的点是分页，Prisma 的skip和take在数据量超过几万条时性能会下降，更稳妥的做法是用游标分页：

const posts = await db.post.findMany({ take: 20, skip: 1, cursor: { id: cursorId }, orderBy: { createdAt: 'desc' }, })

游标分页的核心是利用主键或者唯一索引直接定位起始点，避免数据库扫过前面所有行。对于后台管理系统，通常一个列表页显示 20 条就够了，所以这种方案在绝大多数场景下都够用。

4. tRPC API 层与类型安全通信

4.1 路由划分原则

tRPC 的 router 设计直接影响代码的可维护性。我倾向于尽量遵循“一个业务域对应一个子路由”的原则，而不是把所有查询都堆在一个 router 里。比如文章相关的能力放到postRouter，用户相关的能力放到userRouter，然后在根路由root.ts中合并：

export const appRouter = router({ post: postRouter, user: userRouter, })

这样客户端调用时路径是trpc.post.getAll或者trpc.user.getById，语义清晰，也方便后续和前端页面组件对应。还有一个我习惯遵守的原则是：一个 router 文件尽量控制在 200 行以内，一旦超过这个阈值，就该思考是不是可以拆出更细的子域。因为 tRPC 本身没有任何性能损耗，拆得细一点对维护性帮助更大。

4.2 输入校验与错误处理

tRPC 可以无缝配合 zod 做输入校验，这也是它被选中的一大原因。所有入参都在 router 层用 zod schema 声明，无效请求会被自动拦截，根本进不到业务函数里。比如创建文章：

import { z } from 'zod' const createPostSchema = z.object({ title: z.string().min(3).max(200), content: z.string().min(10), status: z.enum(['DRAFT', 'PUBLISHED']).optional(), }) export const postRouter = router({ create: protectedProcedure .input(createPostSchema) .mutation(async ({ ctx, input }) => { const post = await db.post.create({ data: { ...input, authorId: ctx.session.user.id, }, }) return post }), })

这里protectedProcedure是自定义的，核心是让没有登录的请求直接抛错。错误处理方面，tRPC 默认会把服务端错误对象序列化给客户端，但要注意不要随意把内部错误细节直接抛给用户。我的做法是，在开发环境下抛详细错误，在生产环境统一映射成INTERNAL_SERVER_ERROR，避免暴露数据库结构或者内部路径。

4.3 鉴权逻辑接入

把 NextAuth 和 tRPC 串起来，最关键的是 tRPC 的 context 创建部分。在src/trpc/server.ts里，每次请求都会读取 session：

export const createTRPCContext = async ({ session }) => { return { session, db, } }

然后创建protectedProcedure时，在中间件阶段判断 session 是否存在：

const enforceUserIsAuthed = t.middleware(({ ctx, next }) => { if (!ctx.session?.user) { throw new TRPCError({ code: 'UNAUTHORIZED' }) } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }) }) export const protectedProcedure = t.procedure.use(enforceUserIsAuthed)

这个过程很像快递站取件，你得先出示身份凭证，系统确认是本人之后才把包裹给你。注意中间件的next调用可以携带新的 ctx，后续业务函数里面就能直接拿到可靠的用户信息，不需要再次查询数据库。

5. 前端页面与交互开发

5.1 页面路由与布局

前端部分，我用 App Router 的模式组织页面，目录即路由。首页展示文章列表，动态路由[id]展示文章详情，后台管理区域放在dashboard下面并挂上布局。这种组织方式的优势在于，布局文件可以统一管理侧边栏和顶部导航，页面文件只关心内容区域，代码结构比 Pages Router 阶段的分散式布局清晰很多。

提到 tRPC 在前端的用法，最核心的是一个封装好的 React Hook：api.post.getAll.useQuery()。它来自脚手架自动生成的src/trpc/react.ts，内部已经接好了 React Query 的缓存、重试、失效机制。你不需要手动管理 loading 和 error，只需要拿返回值渲染。这个小细节大大减少了重复代码量。

5.2 客户端组件与服务端组件

App Router 出来之后，大家最大的困惑就是到底哪些组件应该标记"use client"。我的经验是：只有需要交互状态、生命周期副作用、或者事件监听的组件才必须标记为客户端组件，比如表单、弹窗、无限滚动列表。纯展示型的组件，比如文章卡片、日期格式化，完全可以留在服务端组件里，减少客户端 JavaScript 体积。

但有一个坑必须提醒你：React Query 的 provider 必须包在客户端组件里，且该组件会包裹整个应用。这意味着如果你在服务端组件里直接调用api.post.getAll，可能拿不到 query 缓存。更合理的做法是，在服务端组件里直接用createCaller去调用 tRPC 的查询函数，绕过网络请求完成数据预取；在客户端组件里再用api.post.getAll.useQuery取缓存数据，配合Hydrate完成数据传递。这套流程一开始有点绕，但理解后性能收益是非常明显的。

5.3 样式体系与暗色模式

Tailwind CSS 在这套组合里几乎是标配。它的原子类写法让样式和组件结构天然耦合在一起，你不用在不同 css 文件之间跳来跳去。暗色模式方面，我推荐next-themes，它能在页面加载时避免闪烁，因为它在首个 script 里就根据 localStorage 或系统偏好设置好了主题。

主题切换按钮的实现大概是这样：图标组件放在一个带"use client"的组件里，点击后调用setTheme，通过检测当前主题做切换。视觉效果比手写@media暗色模式要顺滑得多。还有一点，Tailwind 的暗色模式不能只改颜色，还要注意边框、阴影、背景透明度这些细节。我做过一个项目，暗色模式下所有文字颜色都反色了，但表格边框还是浅灰色，看起来非常粗糙，后来统一用dark:border-gray-700才解决。

6. 构建、部署与上线检查单

6.1 部署前检查清单

本地开发一切正常后，部署上去经常出现各种意想不到的问题。我现在把部署前的检查项固定成了一张清单，每次上线前逐个确认：

• next build能否零错误通过，这是最基本的要求。
• prisma generate是否在构建流程中执行，服务端能不能正确加载 Prisma Client。
• 环境变量是否在生产环境中完整配置，包括DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL。
• 数据库迁移是否已经执行，或者迁移文件是否会被自动应用。
• 检查 tRPC 的请求路径是否被 Next.js 的 rewrites 干扰。

我发现很多人上线时都会忽略NEXTAUTH_URL这个变量。本地它可能是http://localhost:3000，但部署到正式环境后如果还保持这个值，登录跳转就会指向错误地址，而且 Docker 构建时 NextAuth 还会因为 URL 不匹配直接报错。最好的做法是把这个变量留到部署平台里设置，本地用.env，生产用平台的环境变量面板。

6.2 生产环境配置要点

数据库连接在生产环境不要用本地连接串。如果你部署到 Vercel 或者类似的 Serverless 平台，数据库必须支持多实例并发连接。我通常用云数据库服务，连接串里开启 SSL 模式，比如在DATABASE_URL中追加?sslmode=require。PostgreSQL 默认在某些连接方式下不会启用 SSL，这个看似微小的参数设置，能够避免很多不必要的安全风险。

环境变量管理方面，我建议使用部署平台自带的环境变量面板，而不是把.env文件提交到代码仓库。.env文件里可能会有数据库密码和第三方密钥，一旦推送上去就再也无法真正删除。如果你用的是 Git 仓库，强烈建议第一时间把.env加入.gitignore，并且检查历史提交中有没有已经泄露的敏感信息。

7. 常见问题与排查实录

7.1 类型不同步问题

这是 t3code 开发里最常遇到的一类问题。你修改了 Prisma schema 或者 tRPC router，但客户端代码依然报出旧类型错误。这通常是因为 TypeScript 的增量编译缓存没有失效。解决方法是重启开发服务器，或者删除node_modules/.cache和.next目录后重新构建。

如果重启依然报错，那就要检查你是不是修改了 schema 但没有重新生成 Prisma Client。加字段、改枚举、删表，都必须执行npx prisma generate让类型重新生成。我建议把postinstall脚本设置为自动执行prisma generate，比如在package.json里添加：

{ "scripts": { "postinstall": "prisma generate" } }

这样每次安装依赖后类型都会自动更新，省掉很多莫名其妙的问题。

7.2 数据库连接与迁移问题

生产环境最容易遇到连接超时。我当时在 Vercel 上部署后，日志里频繁出现Can't reach database server。排查下来发现是连接串里的 host 填成了localhost，而云数据库的地址应该是一长串包含集群标识的主机名。另外，某些云数据库平台默认使用 5432 端口之外的自定义端口，连接串里必须显式标注。

迁移方面，不要在生产环境直接跑prisma migrate dev，这个命令可能会清掉开发数据甚至执行重置。生产环境应该用prisma migrate deploy，它只会应用还没有执行过的迁移文件。更稳妥的方案是在 CI/CD 管线的发布阶段执行该命令，并且在执行前备份数据库。

7.3 缓存导致的页面不更新

Next.js App Router 的缓存策略让很多人头疼。页面改了数据，重新发布后用户还是看到旧内容。这可能是两个原因：一是静态渲染缓存没失效，二是客户端 React Query 缓存没有失效。前者可以通过在页面或路由段配置export const dynamic = 'force-dynamic'来解决，或者使用revalidate设置按秒重新验证。后者需要在 mutation 成功之后调用utils.post.getAll.invalidate()来主动刷新相关 query。

我遇到过最诡异的场景是：tRPC 的 mutation 返回了新数据，但页面列表没有更新，因为我在组件里用了多个不同参数的 query，invalidate 的时候只刷掉了其中一个。正确做法是把同域查询的 key 都纳入失效范围，或者用一个统一的查询前缀来管理。

7.4 环境变量缺失问题

环境变量缺失一般在运行时才暴露，比如NEXTAUTH_SECRET未配置会导致登录接口直接 500。为了尽早暴露问题，我会在src/env.mjs里定义运行时校验规则，脚手架已经提供了类似机制，使用 zod 校验环境变量类型，不满足条件时构建或者启动阶段就会报错：

const envSchema = z.object({ DATABASE_URL: z.string().url(), NEXTAUTH_SECRET: z.string(), })

这层校验在本地工作得很好，但要小心生产环境的NODE_ENV必须显式设置为production，否则某些框架行为会不一致。另外，有些平台会自动注入DATABASE_URL但没有注入NEXTAUTH_SECRET，需要留意是否有默认值逻辑，否则会出现本地正常、线上挂掉的情况。

根据我个人的实操感受，t3code 这条路线最核心的价值不是某个单一工具，而是整套体系下前后端之间自动建立的数据契约。它让你把原本花在协调类型、编写文档、排查接口出错上的时间省下来，投入到真正的业务逻辑中。当然，它也不是没有学习曲线，尤其是 App Router 的缓存模型和 tRPC 服务端调用方式需要一些时间去适应。但一旦跨过那个门槛，你会发现改数据结构、调接口参数、重构页面都变成了一件非常踏实的事——因为编译器随时在帮你兜底。最后再分享一个小技巧：在一开始构建项目时，不要急于删掉脚手架的示例代码，先跑通一次“注册登录–创建数据–展示数据”的完整链路，再在它的基础上改造，这条路会比你从空白项目开始顺畅得多。