企业官网建设流程全解析

假如你关注过 TypeScript 全栈开发，T3 Stack 这个名字大概率刷到过不止一次。今年我拿这套组合从头到尾做了一个叫 t3code 的完整项目，从create-t3-app初始化开始，到 tRPC 接口、Prisma 数据模型、再到部署上线，一路实测下来，很多感受和网上"装完就能起飞"的说法并不一致。这篇文章不是教程复读机，更像一次个人项目的全链路复盘：选型理由、代码写法、部署遇到的坑和排查思路，我都尽量摊开讲清楚。

文章适合三类读者：第一，只听说过 T3 Stack、还没完整做过一个项目的人；第二，已经照着官方 demo 跑通过、想把它升级成真实业务的人；第三，想真正理解"端到端类型安全"到底帮开发者省了哪些事的人。我的结论先放这儿：T3 这套组合非常适合中小型全栈应用和内部工具，但它不是万能药，也不适合所有场景。下面开始说人话讲细节。

1. t3code 的起点：T3 Stack 到底解决了什么问题

1.1 端到端类型安全不是玄学

T3 Stack 经常被简化成一句话：Next.js + TypeScript + Tailwind CSS + tRPC。严格来说这个表述缺了点东西，因为社区讨论 T3 时通常会连带提到 Prisma 和 NextAuth，很多脚手架模板也是默认集成这两个。它的核心价值，我用一句话概括：让真正的类型安全从数据库一路贯穿到浏览器组件。

传统前后端分离项目中，最容易失控的环节就是 API 契约。后端写了一个接口返回{ id, title, status }，前端复制一段 TypeScript interface 过去，两个月后接口改了字段名，后端文档没同步，前端编译也不报错，直到用户点开页面发现数据空白才知道出了问题。T3 的思路完全不同：数据结构先定义在 Prisma Schema 里，Prisma 根据 Schema 生成数据库客户端类型；tRPC 的 Router 引用这些类型，并把它暴露给前端；前端在调用api.todo.list.useQuery()时，返回值类型会直接从服务端推导过来。整条链路里你只需要定义一次数据模型，其余类型由编译器帮你推导。

用生活类比来说：传统模式像你手动抄一遍快递单，寄件方改了单子格式，收件方还在按旧格式核对；T3 模式是寄件方和收件方共用同一套电子底单，格式一改，双方立刻同步。这就是"端到端类型安全"最直白的理解。

1.2 tRPC 和 REST、GraphQL 的取舍

很多人在选型时会纠结：为什么不用 REST？为什么不上 GraphQL？我把三者按实际开发体验做了个对比：

tRPC 的定位从来不是取代 REST。它解决的是后端跟前端之间的类型重复定义问题，而不是变成一套新的网络协议标准。对于 t3code 这样一个典型全栈应用来说，服务端和前端的代码在同一个仓库里维护，tRPC 的优势能完全发挥出来。

1.3 这套组合不适合什么场景

T3 不是银弹，有几种情况我不会推荐硬塞 T3：

• 要做开放 API 平台。tRPC 的调用方式跟 HTTP 语义绑定得不深，外部开发者学习成本高，不如老老实实做 REST 或 GraphQL。
• 团队全是前端新手且没有 TypeScript 基础。类型安全要在你理解类型的前提下才有效率，否则错误信息对新人来说更抽象。
• 有大量第三方客户端接入。移动端和外部服务并不想依赖你的 tRPC 客户端代码库。
• 部署环境十分受限的私有化项目。你可能会被 serverless 平台的生产数据库问题反复折磨，这一点我在后面部署章节会专门展开。

2. 初始化一个叫 t3code 的工程：从命令到目录解读

2.1 创建命令与交互选项怎么选

在 t3code 项目里，我用的是官方脚手架最稳妥的初始化路径：

npm create t3-app@latest t3code

命令跑起来之后，终端会问一堆勾选项。我的选择经验是：

需要注意 Node.js 版本。官方模板对 Node 版本有要求，不同时期要求略有差异，但通常需要 Node 18.17 以上。我踩过的第一个坑就是本机 Node 16 直接报Unsupported engine错误，最后用 nvm 切到 Node 20 才顺利。如果你也遇到类似报错，先检查 Node 版本，不要贸然去改依赖版本。

2.2 初始化完之后的目录结构要看懂什么

初始化完成后，t3code 的 src 目录会自动生成如下核心结构：

src/ ├── app/ # Next.js 页面和 API 路由 ├── server/ │ ├── api/ │ │ ├── routers/ # 按业务拆分的 tRPC router │ │ ├── root.ts # 汇总所有子 router │ │ └── trpc.ts # tRPC 单例与 procedure 定义 │ ├── db.ts # PrismaClient 全局实例 │ └── auth.ts # NextAuth 配置（如果勾选） └── utils/ └── api.ts # 前端调用 tRPC 的统一入口

其中src/server/api/trpc.ts是全项目类型安全的"根"，它用initTRPC创建了 tRPC 实例，再从这个实例上产出publicProcedure、protectedProcedure。src/server/db.ts里默认导出一个 PrismaClient 单例，后续所有 router 里访问数据库都是通过ctx.db拿到的。

这个目录结构的好处是，业务边界一开始就被脚手架规划好了。routers 目录下每个文件对应一类业务模块，root.ts 负责聚合，新增一个模块只需要复制一个 router 文件再注册一次。

2.3 第一次启动前先处理环境变量和 Prisma

初始化完成后，第一件事不是立刻npm run dev，而是处理环境变量。脚手架会生成一个.env.example文件，你需要复制成.env：

cp .env.example .env

因为要使用 Prisma，数据库连接串是必须的。开发阶段我直接用 SQLite 顶住，先把模式跑通再说。默认的DATABASE_URL长这样：

DATABASE_URL="file:./dev.db"

这个相对路径是相对于prisma/schema.prisma所在目录来解析的，不是相对于项目根目录，理解这一点能帮你少踩一个坑。如果你跟我一样勾选了 NextAuth，还需要设置NEXTAUTH_SECRET，可以用下面的命令生成一个随机值：

openssl rand -base64 32

2.4 首次运行最容易翻车的三个地方

• Prisma 客户端没生成。npm run dev有时不会自动执行prisma generate，你会看到Cannot find module '@prisma/client'之类的报错。解决方式很直接：手动跑一遍npx prisma generate。
• schema 文件缩进错误。Prisma 对模型的缩进非常敏感，从文档里复制代码时经常把@relation的对齐搞坏，报错会告诉你schema.prisma某一行解析失败。养成写完立即npx prisma format的习惯。
• 端口被占用。Next.js 默认跑 3000 端口，如果本机已经被其他服务占了，起不来时不要纠结，直接改端口或停掉冲突进程。

3. 接口层怎么设计：tRPC Router、权限中间件与调用链

3.1 类型如何从数据库一路推到组件

t3code 的接口层之所以省心，是因为类型推导是自动完成的。链路大致如下：

1. Prisma Schema 定义Todo模型，prisma generate后生成Todo的完整 TypeScript 类型。
2. tRPC Router 里写一个list查询，返回ctx.db.todo.findMany(...)，返回值类型自动来自 Prisma。
3. 前端通过脚手架生成的api对象调用api.todo.list.useQuery()，React Query 的 data 直接拥有服务端返回的完整类型。

这条链路里你不需要手写一个TodoDTO，也不需要维护两套 interface。改字段名时，编译器会逼着你把所有引用点一起改掉，这比任何文档都有效。

3.2 写一个真实的 Todo Router 实例

拿 t3code 里的 Todo 模块举例，src/server/api/routers/todo.ts的完整实现大概是这样的：

import { z } from "zod"; import { createTRPCRouter, protectedProcedure } from "~/server/api/trpc"; export const todoRouter = createTRPCRouter({ list: protectedProcedure .input( z.object({ status: z.enum(["all", "open", "done"]).optional(), keyword: z.string().default(""), }) ) .query(async ({ ctx, input }) => { return ctx.db.todo.findMany({ where: { userId: ctx.session.user.id, ...(input.status === "open" ? { done: false } : input.status === "done" ? { done: true } : {}), ...(input.keyword ? { title: { contains: input.keyword } } : {}), }, orderBy: { createdAt: "desc" }, take: 50, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1).max(100) })) .mutation(async ({ ctx, input }) => { return ctx.db.todo.create({ data: { title: input.title, userId: ctx.session.user.id, }, }); }), });

前端调用时，长这样：

import { api } from "~/utils/api"; const { data, refetch } = api.todo.list.useQuery({ status: "open" }); const createMutation = api.todo.create.useMutation({ onSuccess: () => refetch(), });

你注意api.todo.list这个写法：如果 router 里没有注册list，前端代码直接编译报错；如果一个字段叫status但 input 类型是z.enum(["all", "open", "done"])，传一个"closed"进来同样编译报错。错误在开发环境就被拦住了，而不是留给用户去发现。

3.3 protectedProcedure：认证和授权放在同一层做

create-t3-app 生成的trpc.ts里通常有两个 procedure：

• publicProcedure：任何人都能调用。
• protectedProcedure：依赖ctx.session判断是否登录，未登录直接抛 UNAUTHORIZED。

实现上，你在createTRPCContext里通过getServerSession拿到会话对象，然后塞进 context：

export const createTRPCContext = async (opts: CreateNextContextOptions) => { const session = await getServerSession(); return { session, db: prisma, ...opts, }; };

protectedProcedure则用 middleware 拦截：

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

这里的价值在于：业务 router 一旦声明protectedProcedure，整个链路从入口到出口都不会再需要手写"if 未登录 return 401"逻辑。权限判断收敛到一层，代码干净得多。

3.4 Server Component 与客户端的两种调用姿势

我在 t3code 前期踩过一个大坑：在 Next.js App Router 的 Server Component 里直接调用useQuery，结果报了一堆 hooks 相关错误。后来才意识到，Server Component 里不能用客户端 hooks，调用 tRPC 有两种姿势：

• 客户端组件：用api.xxx.useQuery()，它内部是 React Query 管理缓存。
• 服务端组件：通过router.createCaller(context)直接调用某个 procedure，例如：

import { todoRouter } from "~/server/api/routers/todo"; import { createTRPCContext } from "~/server/api/trpc"; const ctx = await createTRPCContext({ headers: headers() }); const caller = todoRouter.createCaller(ctx); const todos = await caller.list({ status: "open" });

服务端调用时类型依然有效，但不会有 React Query 的缓存特性。实践中我的经验是：首屏需要直出数据的页面用 Server Component 直接调 caller，交互型页面用客户端 hooks。两者兼用没问题，但不要在一个组件里混着写。

4. 数据建模与实践：Prisma Schema、迁移、种子数据与优化

4.1 我的 t3code 数据模型与选择理由

t3code 不只是一个 Todo Demo，我把它扩展成了用户、Todo、标签三个核心模型，用来验证多对多关系。Schema 核心部分如下：

model User { id String @id @default(cuid()) name String? email String? @unique emailVerified DateTime? image String? todos Todo[] accounts Account[] sessions Session[] } model Todo { id String @id @default(cuid()) title String done Boolean @default(false) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt userId String user User @relation(fields: [userId], references: [id], onDelete: Cascade) tags TagOnTodo[] } model Tag { id String @id @default(cuid()) name String @unique todos TagOnTodo[] } model TagOnTodo { todoId String tagId String todo Todo @relation(fields: [todoId], references: [id], onDelete: Cascade) tag Tag @relation(fields: [tagId], references: [id], onDelete: Cascade) @@id([todoId, tagId]) }

主键用cuid()字符串而不用自增整数，理由有两个：一是在多端写入、数据合并且不依赖数据库序列的场景下更安全；二是非自增主键不容易被枚举探测。多对多关系我选择显式建中间表TagOnTodo而不是走 Prisma 的隐式多对多，原因是显式中间表将来可以扩展createdAt等附加字段，迁移成本可控。

4.2 迁移三件套：migrate、generate、studio

开发阶段数据库相关的命令可以记住三兄弟：

# 根据 schema 生成迁移文件并执行 npx prisma migrate dev --name init # 重新生成 Prisma Client npx prisma generate # 可视化查看数据库内容 npx prisma studio

大多数情况下，migrate dev会自动触发generate，不需要额外手工执行。但如果遇到 IDE 一直爆"模型不存在"的红线，手动跑一遍prisma generate往往能解决。

实际开发中改模型的频率很高，比如给 Todo 加一个priority字段：

npx prisma migrate dev --name add_todo_priority

Prisma 会自动生成ALTER TABLE迁移文件并执行。严禁绕过 Prisma 直接改数据库结构，否则你的迁移历史会和实际库结构脱节，后面联手环境部署时麻烦无穷。

4.3 种子数据怎么准备

没有种子数据，前端联调时会非常痛苦。t3code 的prisma/seed.ts思路很简单：

import { PrismaClient } from "@prisma/client"; const prisma = new PrismaClient(); async function main() { const user = await prisma.user.upsert({ where: { email: "demo@example.com" }, update: {}, create: { email: "demo@example.com", name: "Demo User" }, }); const tag = await prisma.tag.upsert({ where: { name: "工作" }, update: {}, create: { name: "工作" }, }); await prisma.todo.upsert({ where: { id: "seed-todo-1" }, update: {}, create: { id: "seed-todo-1", title: "用 T3 做第一个全栈项目", userId: user.id, tags: { create: [{ tagId: tag.id }] }, }, }); } main() .catch((e) => { console.error(e); process.exit(1); }) .finally(() => prisma.$disconnect());

在package.json里配置种子命令：

{ "prisma": { "seed": "tsx prisma/seed.ts" } }

之后执行npx prisma db seed就能一键重建演示数据。种子脚本建议幂等，重复执行不会生成重复数据，这能省掉很多联调时的烦躁。

4.4 查询优化和 PrismaClient 全局单例

T3 全栈项目最常见的性能问题是 N+1 查询。比如 Todo 列表要显示每个 Todo 的标签，如果你在循环里逐个查标签，数据量稍大页面就会明显变慢。正确做法是查询时用include或分两次查询后前端拼接：

const todosWithTags = await prisma.todo.findMany({ where: { userId: ..., }, include: { tags: { include: { tag: true }, }, }, });

不过include嵌套层级过深会显著增加查询时间，我后来在线上的做法是：列表页只查 Todo 主数据，标签信息用一个单独的tag.listByTodoIds查询拉回来，在前端按 todoId 分组。需要根据实际数据量权衡，不是所有场景都适合无脑include。

另一个长期易忽视的点是 PrismaClient 实例管理。src/server/db.ts里必须使用全局单例，否则 Next.js 在开发模式的热更新会不断创建新的数据库连接，把连接池打满。脚手架默认已经做了globalThis缓存，这个模式建议保持不变。

4.5 SQLite 与 PostgreSQL 之间的开发环境切换教训

我在 t3code 开发初期用 SQLite 图省事，后面部署时换成 PostgreSQL，结果中间吃了不少苦头。最典型的问题：

• SQLite 不区分类型，String和Int约束非常宽松，开发时测不出类型问题。
• SQLite 的contains查询在中文场景下行为跟 PostgreSQL 不完全一致。
• 迁移 SQL 在两个数据库方言下不一样，开发环境和生产环境的 schema 状态容易出现偏差。

我的建议是：如果目标部署环境明确是 PostgreSQL，就从第一天开始用 PostgreSQL 做开发。本地可以用 Docker 快速起一个 Postgres 实例：

docker run --name t3code-db -e POSTGRES_PASSWORD=secret -p 5432:5432 -d postgres:16

虽然初始配置多花十分钟，但后面省下的是反复排查"本地好好的生产上挂了"的时间。

5. 部署上线整个排查过程：Vercel、Neon 与 Docker 的实测

5.1 为什么本地跑得好好的，一部署就崩

"本地没问题"是所有全栈项目的经典台词，T3 应用尤其容易触发这个问题，因为它同时耦合了 Next.js、Prisma、认证三套体系。部署前必须想明白一个核心问题：你的数据库到底部署在哪里。

• 如果用默认 SQLite，文件存在服务器本地。Vercel 的 serverless 函数是临时文件系统，实例随时回收，SQLite 数据写入后会在下一次冷启动时消失。
• 如果数据库只存在本地 Docker 容器里，云端实例根本没有办法访问。
• 如果某个环境变量在生产环境缺失，运行时才会报错，而本地.env里刚好有。

所以第一步是选定云端数据库。我在 t3code 上选了 Neon 的 PostgreSQL 托管方案，原因是它的 serverless 连接模式很适合 Vercel 这种每次请求独立冷启动的场景。连接池地址的配置要注意加上sslmode=require和适当的connection_limit：

DATABASE_URL="postgresql://user:password@ep-xxx-pooler.region.aws.neon.tech/neondb?sslmode=require"

5.2 Vercel 上三个真实故障的完整排查链路

故障 A：构建失败，日志里出现环境变量缺失

现象是 Vercel 日志报Environment variable not found: DATABASE_URL。我当时的排查链路是：

1. 先检查 Vercel 项目的 Environment Variables 面板，确认生产环境里确实填了DATABASE_URL。
2. 再检查vercel env pull拉到本地的.env文件是否正常。
3. 确认构建命令与postinstall脚本。create-t3-app 生成的项目通常会在package.json里配置"postinstall": "prisma generate"，但如果被删除，Next.js 构建阶段用不到 Prisma Client。
4. 最终发现是 Vercel 旧缓存导致构建脚本没执行，清理构建缓存后重新部署解决。

故障 B：运行时 500，P1001 can't reach database server

现象是页面能打开，但任何需要查库的接口都报错。排查链路：

1. 确认本地是否能连上 Neon 数据库，psql直连试试。
2. 检查连接串是否用了 pooler 地址，Neon 有两种地址：直连和 pooler。serverless 场景必须用 pooler，否则并发一高连接数就爆。
3. 检查连接串查询参数是否包含sslmode=require，Neon 默认要求 SSL。
4. 在 Vercel 函数日志里加一段临时console.log(process.env.DATABASE_URL)，确认运行时环境变量真的生效。

故障 C：登录后可访问，但 Todo 接口全部 401

现象是登录页面能过，但protectedProcedure一直拒绝。排查链路：

1. 先看 NextAuth 的 Session 是否真存在，检查数据库里的 Session 记录。
2. 确认NEXTAUTH_URL和NEXTAUTH_SECRET在 Vercel 上是否配置。生产环境缺NEXTAUTH_SECRET时，JWT 加密签名会失败，Session 解析不了。
3. 检查 Cookie 的 secure 属性。Vercel 的生产环境强制 HTTPS，本地 HTTP 下测试时 Session Cookie 规则不同，不要拿本地行为直接套生产。

这套排查过程最大的经验是：不要一次猜一个变量，先确认环境变量全部到位，再确认数据库连接串有效，最后再查业务层面的鉴权逻辑。排查链路拉直了，问题一般就藏在这三层里。

5.3 Docker 多阶段构建与启动脚本

如果不用 Vercel，想把 t3code 部署到自己的服务器或容器平台，多阶段构建是一个稳妥套路。我的 Dockerfile 思路大致如下：

FROM node:20-alpine AS base WORKDIR /app ENV NEXT_TELEMETRY_DISABLED=1 FROM base AS deps COPY package.json package-lock.json ./ RUN npm ci FROM base AS builder COPY --from=deps /app/node_modules ./node_modules COPY . . RUN npx prisma generate && npm run build FROM base AS runner ENV NODE_ENV=production COPY --from=builder /app/.next .next COPY --from=builder /app/node_modules node_modules COPY --from=builder /app/package.json ./ COPY --from=builder /app/public ./public EXPOSE 3000 CMD ["sh", "-c", "npx prisma migrate deploy && npm run start"]

生产容器里不要用prisma migrate dev，那会交互式要求确认；用prisma migrate deploy只看迁移目录自动执行未应用的迁移文件。如果你的部署平台不支持多实例同时启动，防止多个实例同时跑迁移导致锁冲突，也可以把迁移单独抽成一个初始化 job，业务容器启动时不再重复执行迁移。

5.4 部署后必须做的验证清单

分享一份我自己整理的部署后检查清单：

• [ ] 打开健康检查接口或首页，确认 HTTP 200。
• [ ] 在浏览器里走一遍完整业务链路：登录 → 创建数据 → 刷新页面 → 数据仍在。
• [ ] 查看生产环境的函数日志，确认没有 Prisma 连接错误和 NextAuth 告警。
• [ ] 用数据库托管平台查看连接数和慢查询，确认没有连接池被打爆。
• [ ] 配置数据库备份策略，Postgres 托管服务一般都有自动备份，确认回调邮箱能收到备份成功通知。
• [ ] 回滚方案确认：如果最新一次发布出问题，旧版本能否一键切回。

6. 收尾复盘：T3 栈适合做什么，以及我给自己的下一步调整

6.1 类型安全这件事极其上头但也有边角问题

t3code 做到中期，我明显感受到类型安全带来的爽感：改一个 Prisma 字段名，编译器和 IDE 会像一个尽职的质检员，把所有相关引用全部标红，你只需要跟着修完。项目里几乎不需要手写any，跨端联调的成本低到可以忽略。但也有一些边角问题需要正视：

• IDE 偶尔不会立刻识别刚注册的新 router，我遇到最多的是api.todo.xxx一直报错，但终端tsc --noEmit却通过。这种情况通常重启 TS Server 或 IDE 窗口就能恢复。
• React Query 缓存对实时性要求极高的场景需要额外处理，比如多人在线协作，后端状态变了前端不会自动感知，得靠轮询或 WebSocket。tRPC 不负责这件事，别指望它。
• 嵌套过深的类型推导会让编辑器变卡，特别是 Prisma 模型字段很多时，建议在 router 返回值里做一层select精简数据，同时也能提升编辑器性能。

6.2 什么时候应该突破 T3 纯栈的边界

从 t3code 这个项目里我悟到一件事：T3 是一个很好的单体全栈起点，但业务一复杂，你需要主动给它加东西，而不是被"纯栈"绑定。

对外提供 API 时，我建议包一层标准 REST 路由。tRPC 的调用协议本质是 HTTP POST body 里放指令，第三方不了解你的框架内部就不可能接入。可以写一个 Next.js Route Handler，内部调用 tRPC 的 caller，对外暴露传统 Restful 接口，这比把 tRPC 暴露给外部安全得多。

文件上传也别走 tRPC。上传场景应该直接向对象存储申请一个带签名的上传链接，让客户端直传文件，不要用 JSON body 塞 Base64。我在后续迭代里就是给 t3code 加了一个upload的 Route Handler，对接 S3 兼容存储，既绕开了函数执行时长限制，也避免了带宽浪费。

6.3 新手做类似 t3code 项目的三条实用建议

如果让我给准备上手 T3 的人重新划一遍重点，我会浓缩成下面三条：

第一，先把数据模型想清楚再写页面。脚手架生成的 Demo 代码删掉不可惜，从你自己的一个小实体（比如"一张卡片"、"一个订单"）开始建模，模型稳定了后面所有页面都顺。

第二，把 zod schema 当成协议文档来维护。tRPC 的输入校验、表单的校验规则、数据库字段的合法值约束，都从同一个 zod 对象派生，不要各写各的。T3 类型安全的根基，一半在 Prisma，另一半在 zod。

第三，开发环境和生产环境的数据库一定要早统一。宁可最开始多花半小时搭一个本地 Postgres 容器，也不要用 SQLite 拖到部署前再切换。这个教训我在第 4 章已经详细交代过了，遇到的人会懂。

最后再说句实在话：我把 t3code 看到现在，最值钱的收获不是"用上了新框架"，而是养成了"先定类型、再写业务"的习惯。类型安全不是万能药，它不能帮你解决业务逻辑错误，但确实能把一大批低级问题挡在编译期门外。如果你正打算用 T3 做第一个全栈项目，希望这篇复盘能帮你把起步阶段的坑提前填平。