企业官网建设流程全解析

去年年底我和几个朋友在做一个内部工具时，被前后端类型割裂的问题折腾得够呛。后端定义好的数据结构和校验规则，前端只能靠复制粘贴保持同步，接口一改，前端就莫名其妙挂掉，跑起来才发现错误。后来我们把项目推倒重来，采用了 t3code 这个基于 T3 Stack 的工程化方案，才算是把这一团乱麻理清楚。t3code 不是什么全新的框架，它是一个把 Next.js、TypeScript、tRPC、Tailwind CSS 组合在一起的全栈应用模板，核心思路就是“端到端类型安全”：从数据库表结构到 API 路由再到 React 组件的 props，全程类型打通，改一处，编译器立刻告诉你哪里会炸。这篇文章就是我对 t3code 这个项目从选型、搭建到踩坑的完整复盘，适合正在做全栈项目、受够了手工维护接口类型的同学参考。

1. 项目整体设计与技术选型思路拆解

1.1 为什么选择 T3 Stack，而不是 REST 或 GraphQL

做全栈项目，第一件事就是定前后端通信方式。最传统的做法是 REST API，后端写路由、前端封装 fetch，然后用 Swagger 或 OpenAPI 维护文档。这套方案的问题在于：文档和代码是两个独立的东西，只要有人忘记更新，类型就开始漂移。GraphQL 解决了“按需取字段”的问题，但配套的 schema 定义、解析器、缓存策略对一个小团队来说负担不小。

T3 Stack 给出的答案是 tRPC，它不走 HTTP 上的自定义协议，也不生成额外 schema 文件，而是直接利用 TypeScript 的类型系统做“过程调用”。你在服务端写一个查询过程，客户端引入对应的类型，调用时自动带上完整类型推断，不需要生成路由字符串，不需要手写请求封装。这听起来像魔术，但原理很朴素：tRPC 只是把函数调用的参数和返回值类型通过 TypeScript 泛型推到客户端，运行时仍然走普通 POST 请求。用一个生活化类比，REST 是你每次到柜台告诉服务员“我要编号 12 的套餐”，而 tRPC 是你直接进后厨，当着厨师的面说“帮我来一份那个”，对方递给你什么，类型就是什么。

我整理过三种方案的取舍，供参考：

t3code 选 tRPC 的本质原因很直接：自己团队的产品，前后端代码放在同一个仓库里，没有对外暴露 API 的需求，那为什么要承受 REST 的文档维护成本和 GraphQL 的解析器复杂度？让类型自己说话，比任何文档都可靠。

1.2 Next.js 与 Tailwind CSS 在 t3code 里的角色

T3 Stack 里的 N 和 T 分别是 Next.js 与 Tailwind CSS，这两个技术虽然在社区已经非常普及，但在 t3code 里的用法值得说清楚。

Next.js 在 t3code 里承担的是渲染层与路由层。App Router 推出后，服务端组件和客户端组件的边界变得更加明确：需要读取数据库或访问服务端上下文的数据展示逻辑，放在服务端组件里；需要交互状态、事件处理的界面，明确标注为客户端组件。t3code 的项目结构会天然引导你遵守这个边界，服务端组件的直接数据获取配合 tRPC 客户端调用，既保证了首屏性能，又让交互区域保持响应式体验。

Tailwind CSS 则解决了样式方案的“约定问题”。原子类的方式看起来很啰嗦，但好处是你不需要在 class 命名和 CSS 文件组织上花心思，组件和样式始终在同一个文件里，删改组件时不会留下死样式。t3code 默认带上了深色模式配置、主题变量和 Prettier 插件，类名会自动排序，省了一堆格式化争论。

另外，T3 Stack 的模版可以按需选择 Prisma、NextAuth.js 和 Zod，这三个可选项几乎覆盖了全栈应用最常见的三件事：数据库访问、身份认证、输入校验。后面我会逐一展开我实际接入这些组件时的改动经验和教训。

2. tRPC 核心细节解析与实操要点

2.1 tRPC 工作原理解析：Router、Procedure 与 Context

如果只看 tRPC 的官方文档，很容易被 Router、Procedure 这些术语绕晕。实际上拆开就三个概念。

Procedure 是最小的调用单元，对应一个后端函数，分 query（查）、mutation（改）、subscription（实时订阅）三种类型。Router 是把一组 Procedure 按照命名空间组织起来的集合，类似 REST 里的路由前缀。Context 则是每个请求共用的初始化逻辑，比如从请求头解析 session、连接数据库实例，它会在每次调用前执行，然后把结果传给所有 Procedure。

这里的重点在于 Context 的设计直接影响类型推断。在 t3code 的项目里，我用了下面的方式创建 tRPC 实例：

import { initTRPC, TRPCError } from "@trpc/server"; import superjson from "superjson"; import { ZodError } from "zod"; import { db } from "~/server/db"; import { getServerAuthSession } from "~/server/auth"; export const createTRPCContext = async (opts: { headers: Headers }) => { const session = await getServerAuthSession(); return { db, session, ...opts }; }; const t = initTRPC.context<typeof createTRPCContext>().create({ transformer: superjson, errorFormatter({ shape, error }) { return { ...shape, data: { ...error.data, zodError: error.cause instanceof ZodError ? error.cause.flatten() : null } }; }, }); export const createCallerFactory = t.createCallerFactory; export const createTRPCRouter = t.router;

细看这段代码，superjson 负责序列化 Date、Map 等复杂类型，没有它你会遇到“后端返回的 Date 到前端变成字符串”的经典问题。ZodError 的错误格式化则让校验失败的信息直接从前端字段名一一对应，这个设计在表单场景里极其好用。

2.2 一个完整的 tRPC 路由实战

纸上谈兵没意思，直接看一个实际路由示例。假设 t3code 里要做一个“获取帖子列表”的功能，输入分页参数，输出带作者信息的帖子数组。

import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; export const postRouter = createTRPCRouter({ list: publicProcedure .input( z.object({ cursor: z.number().optional(), limit: z.number().min(1).max(50).default(10), }) ) .query(async ({ ctx, input }) => { const posts = await ctx.db.post.findMany({ take: input.limit + 1, orderBy: { createdAt: "desc" }, include: { author: { select: { name: true } } }, cursor: input.cursor ? { id: input.cursor } : undefined, skip: input.cursor ? 1 : 0, }); let nextCursor: number | undefined; if (posts.length > input.limit) { const nextItem = posts.pop(); nextCursor = nextItem!.id; } return { posts, nextCursor }; }), });

客户端调用时的体验才是 t3code 最爽的地方，你不需要写任何请求路径字符串，直接引用服务端导出类型：

import { api } from "~/trpc/react"; function PostList() { const { data, isLoading } = api.post.list.useInfiniteQuery( { limit: 10 }, { getNextPageParam: (lastPage) => lastPage.nextCursor } ); }

这里有个关键点：useInfiniteQuery 是 tRPC 对接 TanStack Query 之后自动生成的 hook，分页参数类型和服务端 Zod 的 input 完全双向校验。如果你把 limit 改成 100，服务端 Zod 会拒绝，而这一切发生在编译期，根本轮不到运行时报错。

我踩过的坑是，模块联邦或微前端场景下，跨项目引用 API 类型会变得很麻烦，需要单独把服务端类型抽成一个私有 npm 包。但 t3code 本身定位就是“单仓全栈”，这个前提不要破坏，否则复杂度会成倍增加。

2.3 中间件与鉴权的正确姿势

鉴权是几乎所有全栈应用都躲不开的需求。T3 Stack 默认集成 NextAuth.js，配合 tRPC 中间件可以做到 API 级别的访问控制。

我在 t3code 里加了一个 requireAuth 中间件，逻辑很直白：session 不存在就抛 UNAUTHORIZED 错误，存在则把 user 信息注入到下一步的 ctx 中。

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

之后需要登录才能调用的过程就直接用 protectedProcedure 定义。这里有一个容易忽略的细节：中间件里的 next 调用会合并 context，创建出的新 context 类型自然包含 user 字段，不需要你再做类型断言。中间件可以叠多层，但不要在同一层里塞太多逻辑，比如“既鉴权又做权限校验还顺带记日志”，分层拆开更利于排查问题。

提示：tRPC 的鉴权是“调用级”的，不是“路由级”的。不要指望它在 HTTP 层拦截请求，真正需要对外隐藏的页面，还得在 Next.js 的页面服务端去做 redirect 判断，双保险才行。

3. 从零搭建 t3code 全栈项目的实操记录

3.1 使用 create-t3-app 初始化项目

搭建 t3code 最快捷的方式是官方脚手架 create-t3-app，它会帮你把 T3 Stack 全家桶都配好，同时允许按需勾选功能。

npm create t3-app@latest t3code

交互式界面会让你选择是否启用 NextAuth.js、Prisma、Tailwind CSS 以及 ESLint 等。我的建议是：一开始可以全部选上，因为脚手架生成的文件结构比官方文档里零散示例更完整，后面用不到再删也不会太痛。生成后的目录结构关键部分如下：

src/ ├── app/ │ ├── api/ │ │ ├── auth/ # NextAuth 路由 │ │ └── trpc/ # tRPC HTTP 入口 ├── server/ │ ├── api/ │ │ ├── routers/ # 各业务模块的 tRPC 路由 │ │ ├── root.ts # 根 router 聚合 │ │ └── trpc.ts # tRPC 实例上下文定义 │ ├── db.ts # Prisma 客户端 │ └── auth.ts # NextAuth 配置 ├── trpc/ │ ├── server.ts # 服务端类型导出 │ └── react.tsx # 客户端 hooks 封装 └── env.js # 环境变量安全校验

首次进入项目后，第一件事是创建 .env 文件，把 DATABASE_URL、NEXTAUTH_SECRET、DISCORD_CLIENT_ID 这类变量填好。脚手架自带 env.js 会在启动时校验环境变量是否齐全，缺失时会直接给出明确报错，这一点对团队新人非常友好，不会出现“启动成功但登录就挂”的半吊子状态。

3.2 Prisma 数据模型设计与实际接线

数据建模是真刀真枪的地方。我在 t3code 里设计了一个简单但完整的例子：用户和帖子，用户能点赞帖子。

model User { id String @id @default(cuid()) name String? email String? @unique emailVerified DateTime? image String? accounts Account[] sessions Session[] posts Post[] likes Like[] } model Post { id String @id @default(cuid()) title String content String authorId String author User @relation(fields: [authorId], references: [id], onDelete: Cascade) likes Like[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Like { userId String postId String user User @relation(fields: [userId], references: [id], onDelete: Cascade) post Post @relation(fields: [postId], references: [id], onDelete: Cascade) @@id([userId, postId]) }

写完 schema 后运行 npx prisma db push 同步到开发数据库，再运行 npx prisma generate 生成类型。注意，db push 适合开发阶段快速改表，生产环境建议改用 prisma migrate dev 生成迁移文件，否则将来多人协作时，数据库结构变更没有审计记录，非常被动。

在服务端接入 Prisma 时，一个容易被忽视的问题是全局实例。开发模式下 Next.js 热重载会反复执行模块加载，如果不做缓存，每个请求可能创建多个数据库连接。t3code 脚手架已经在 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;

这个 globalThis 缓存技巧直接在 Node 全局对象上挂一个引用，确保开发环境只有一个 Prisma 实例。我自己曾经因为忽略这一点，在改 schema 后频繁重启 dev server，卡到怀疑人生。

3.3 部署细节：环境变量与构建顺序

t3code 本身是一个 Next.js 应用，部署方式取决于你的基础设施。用 Docker 部署时，构建阶段需要提前完成两个操作：prisma generate 和 prisma migrate deploy。如果只在运行时生成 Prisma 客户端，很容易碰到“容器里没有网络下载引擎”的幺蛾子。

Dockerfile 里一个可行的顺序是：

FROM node:20-alpine AS builder WORKDIR /app COPY . . RUN npm ci RUN npx prisma generate RUN npm run build FROM node:20-alpine AS runner WORKDIR /app COPY --from=builder /app/.next ./.next COPY --from=builder /app/node_modules ./node_modules COPY --from=builder /app/package.json ./package.json ENV NODE_ENV=production CMD ["npm", "run", "start"]

另外一个容易踩的点是 Next.js 的 standalone 输出。如果项目开启 output: 'standalone'，node_modules 不需要全部复制，但 Prisma 引擎文件的位置必须显式处理，否则生产环境会报找不到 query engine。我最终选择不折腾 standalone，直接复制 node_modules，虽然镜像体积大了点，但稳定性换来的是安心。

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

4.1 高频报错速查表

我在做 t3code 时把遇到的典型问题整理成了一张表，每一条都是实际报错现场：

其中 tRPC body 限制是最隐蔽的一个。默认情况下，Next.js 的 API Route 会限制 JSON 请求体大小，tRPC 官方设置为 10MB。如果你在 mutation 里传 base64 图片，很容易触发 413 错误。临时方案是调整路由配置，但长期来讲应该把二进制文件交给对象存储，数据库只存文件 key。

4.2 热重载下 Prisma 卡死与 type 报错的排查思路

开发环境下最让人抓狂的问题是 dev server 跑着跑着突然变慢，终端刷出一堆连接错误。前面提过，这是 Prisma 实例重复创建导致的，用 globalThis 缓存可以解决，但如果你在某个路由文件里直接new PrismaClient()而没走 server/db.ts，缓存就失效了。排查技巧很简单：在所有服务端文件里 grepnew PrismaClient，确保唯一入口。

另一个高频问题是 tRPC 类型报错。这类问题往往不是 tRPC 本身，而是使用了any或泛型推断失败。我的排查标准流程是：

1. 先确认 tRPC 根路由里是否导入了新定义的 router。
2. 再用tsc --noEmit检查全项目类型错误，而不是只看编辑器红波浪线。
3. 最后检查客户端api对象是否从~/trpc/react导入，而不是从服务端~/server/api/trpc导入。
4. 如果改了 Zod schema，确认没有残留旧类型缓存在 node_modules/.cache 里，必要时删掉.next目录重启。

注意：不要把 tRPC 的类型断言当万能药。我见过有人为了省事，直接用as any绕过类型校验，结果运行时炸得毫无预兆。类型安全是这个项目的立身之本，绕过它等于自废武功。

5. 扩展思考：t3code 还能怎么玩

实际开发中我发现 t3code 的固定组合只解决了 80% 的问题，剩下 20% 需要自己在架构上做取舍。比如实时通知需求，tRPC 的 subscription 基于 WebSocket，在 Next.js 的 serverless 部署环境下支持并不完整，遇到实时功能时，我的建议是单独拆一个 Node 服务来处理 WebSocket 长连接，把业务数据写入数据库后，t3code 这边通过 Prisma 订阅或轮询感知变化。

这种“主应用 + 辅助服务”的架构思路，比强行把实时逻辑塞进 tRPC 更稳。另外，如果未来需要开放 API 给第三方，也不要在 t3code 里硬开 REST 接口，比较干净的做法是另起一个 BFF 层，对内仍然走 tRPC，对外走 OpenAPI 文档。

还有一点关于项目命名和代码组织：t3code 这类全栈模板很容易演变成“巨无霸仓库”，所有代码堆在一起。我的实践经验是，在 server/api/routers 下按业务域拆模块，在 app 目录按路由组织页面，中间层只允许通过 tRPC 暴露的接口调用数据，绝不允许页面组件直接操作 Prisma。这个约定坚持下来，项目规模翻倍时仍然不会乱。

如果你正打算用 t3code 起一个新项目，我建议先从最小可运行版本开始，不要一开始就把认证、上传、权限全部加上。先用一个 tRPC procedure 打通前后端类型链路，再逐步叠加功能。等你对类型安全的体感上了瘾，自然也就理解了为什么这个组合会被这么多人推崇。