企业官网建设流程全解析

不算夸张地说，拿到t3code这个项目名的第一反应，是我终于可以把那一套“TypeScript 全家桶”的心得彻底沉淀下来了。它不是一个框架，也不是某个现成工具，而是我在实际业务里反复验证过的一套全栈项目骨架：以 TypeScript 为主线，把前端 UI、后端接口、数据库模型、类型约束全部串在一条链路上，最终落成一个能直接复制、能快速起步、也能跑完部署的代码体系。

如果你正处在“会写 React 组件但一涉及全栈工程就发怵”的阶段，或者你已经被各种前后端分离项目里的类型混乱折磨过，那t3code这套思路值得花一下午认真过一遍。这里头没有玄学，只有类型安全带给你的踏实感，以及真正跑通一个全栈项目时那种“原来就这么回事”的顿悟。我尽量把选型逻辑、目录结构、实操步骤、踩坑记录全部摊开讲，能帮你省掉不少反复试错的成本。

1. t3code 的本质：先把类型安全这件事想清楚

1.1 项目定位：它到底解决什么问题

先别急着写代码，把问题想透往往比动手更重要。t3code这个名字看起来像某个库的代号，其实它代表的是一整套“以强类型为核心”的全栈工程实践。我在做这个项目时最直接的目标只有一个：让前端调用后端接口时，像调用本地函数一样有提示、有校验、有类型反馈。

传统的前后端协作模式里，前端拿到后端返回的数据结构，通常靠文档或者抓包猜。接口字段改一个名字，后端改起来很快，前端却要花半小时找哪里调用了这个字段，而且漏掉一处，运行时就给你一个undefined。t3code用了一套更聪明的组合拳：前端写业务代码时，直接 import 后端定义的 router，TypeScript 编译器会帮我们把所有接口参数和返回类型都检查一遍。参数写错了、返回结构对不上，编辑器里立刻爆红，根本不用等运行时报错。

这个项目适合的人群，我简单划分一下：

• 对 TypeScript 有兴趣、但日常只写组件的前端开发者，可以通过它理解类型如何贯通前后端。
• 被接口联调折磨过、想改善协作流程的小团队，可以参考这套模式减少“低级 bug”。
• 自己练手做全栈项目、但又不想维护两套类型定义的独立开发者，它尤其合适。

一句话总结：t3code不是什么黑科技，它只是把“类型”这件事在全栈开发的每一个环节都认真对待，仅此而已，但效果立竿见影。

1.2 技术选型逻辑：为什么选择这条链路

技术选型没有标准答案，但一定有最合理的路径。t3code这条链路上最核心的三个角色是 Next.js、tRPC 和 Prisma。Next.js 负责页面与路由，tRPC 负责前后端接口的类型安全通信，Prisma 负责数据库模型和查询的类型安全。三者叠加的效果，是整个项目从数据库到 UI 层的所有数据结构，都被 TypeScript 的静态类型完整覆盖。

先说 tRPC，它是这条链路里最容易被低估的一环。很多前端同学第一次见到 tRPC 会疑惑：这不就是个 RPC 框架吗，跟 REST 有什么本质区别？区别非常关键：REST 接口是“字符串路径 + 约定文档”，tRPC 是“函数调用 + 类型推导”。后者让接口调用变成了一种编译期行为，出错的可能性被大幅压缩。比如你在前端写trpc.post.byId.useQuery({ id: 1 })，编辑器立刻能提示id必须是 number 类型，返回的数据结构也能自动补全为Post | null。这种事情在 REST 世界里，八成要靠 Postman 手动验证，或者在运行时打 log 去看。

再说 Prisma。选它不是因为“网红”，而是因为它的 schema 文件天然就是一份类型声明。表结构长什么样，TypeScript 类型就长什么样，二者不会出现偏差。配合prisma migrate做数据库迁移，整个数据库演进过程都能被版本管理工具追踪，团队协作时不会有“谁的本地库跟线上不一致”这种经典闹剧。

这套组合还有一个隐藏优势：开发体验的统一。前端、后端、数据库三条线用的都是 TypeScript 语法，一个开发者的心智负担明显降低，不用来回切换“JS 思维”和“SQL 思维”。我用这套结构做过几个中小型项目，体感就是：从需求到落地，阻力最小的一条路。

2. 结构与设计：把代码分层这件事做到肉眼可见

2.1 目录结构：先搭骨架再谈业务

一个项目能不能长期健康地演进，目录结构是底线工程。t3code的目录设计遵循了一个原则：按职责分层，而不是按文件类型堆砌。

实际落地时，我采用的结构大致是这样：

t3code/ ├── prisma/ │ └── schema.prisma # 数据模型定义 ├── src/ │ ├── pages/ # Next.js 页面与路由 │ ├── server/ │ │ ├── api/ │ │ │ └── routers/ # tRPC 业务路由 │ │ ├── db.ts # Prisma Client 实例 │ │ └── trpc.ts # tRPC 初始化与中间件 │ ├── styles/ # 全局样式 │ ├── types/ # 少量共享类型（如需 UI 层专用类型） │ └── utils/ │ ├── trpc.ts # 前端调用的 tRPC hooks（类型化） │ └── api.ts # 其他工具封装 ├── .env # 环境变量（不提交仓库） └── package.json

这个结构的核心思路是：把数据模型（prisma）、业务逻辑（server/routers）、表现层（pages）和类型实用工具（utils/trpc.ts）彻底分开。新手最常犯的错误是把所有逻辑都塞进页面组件里，比如直接在useEffect里 fetch 并处理数据。那样写 demo 很爽，项目一大必然混沌。t3code的做法是把数据访问逻辑收敛到 tRPC router 里，页面只负责调用和渲染，这是一个值得坚持的纪律。

这里要特别提一下utils/trpc.ts。这个文件是前端使用 tRPC 的入口，它把createTRPCNext的泛型参数和后端 router 类型绑定在一起。因为这个文件的存在，前端所有组件里才能import { trpc } from "../utils/trpc"，并获得完整的类型提示。这个文件算得上前后端类型打通的关键枢纽，配置一次，全项目受益。

2.2 类型安全设计：让数据在全链路里自带“说明书”

类型安全是t3code项目的灵魂，具体落地时有几个关键设计。

第一个是数据库模型作为类型源头。在prisma/schema.prisma里定义好模型后，Prisma 会自动生成对应的 TypeScript 类型。这意味着你不必手写任何interface User，数据库里User表有什么字段，TypeScript 里就有什么字段，彻底消灭手写类型与数据库结构不对齐的问题。比如我定义用户模型，会考虑 ID、邮箱、昵称、创建时间等字段，之后任何地方用到用户数据，编辑器都会给出精确到字段的补全提示。

第二个是tRPC 的输入输出校验。tRPC 原生支持 zod（一个校验库），每个 procedure 的输入都会被 zod schema 严格校验。比如创建文章时，前端传title和content，zod schema 里规定title最小长度为 1、最大长度为 200，内容不为空。那么任何不满足条件的请求，在后端入口处就会被拦截，返回清晰的错误信息。这个设计把接口防御从“相信前端”提升为“规则前置”，边界清晰。

第三个是共享类型不滥用。很多团队喜欢建一个types.ts到处 import，但t3code的做法是：能由 Prisma 生成、能由 tRPC 推导的类型，一律不手写。手写类型只保留在确实需要 UI 特有结构的场景，比如某个表单的临时状态类型。这个原则能避免维护一套“副本类型”的沉重负担，让你的类型文件永远干净。

从体验上讲，这套类型链路最爽的瞬间是：你重命名数据库字段后，整个前端所有引用该字段的位置同步爆红报错，你一个个修过去，改完跑一遍，一次过。这比在测试环境里点半天按钮才发现接口挂了，要舒心太多了。

2.3 路由与数据获取：页面层的取舍

页面层我选择 Next.js 的路由作为统一入口，原因在于它天然支持两种渲染模式：静态生成（SSG）和服务端渲染（SSR）。t3code里用得比较多的是静态生成：对不常变化的数据，构建时直接生成 HTML，访问速度极快；对需要实时数据的页面，再用getServerSideProps在请求时拉取。这个灵活度是纯客户端渲染方案给不了的。

数据获取方面，t3code并没有在每个页面里手动写 fetch，而是依赖 tRPC 提供的 React hooks。比如文章列表页面，代码是这样：

const { data: posts, isLoading } = trpc.post.list.useQuery();

这一行代码背后，是完整的请求状态管理：加载中、成功、失败、缓存、重试。不需要自己维护 loading state，也不需要在组件卸载时手动取消请求（tRPC 的 hook 自己处理了）。这种体验对习惯手写 fetch 的开发者来说，一旦适应就很难回头。

一个值得注意的细节是：不要在客户端调用的 tRPC procedure 里处理敏感逻辑。比如删除用户这种操作，应该在服务端通过 middleware 校验权限，而不是依赖前端“不调用”来保证安全。这个我在第 4 节会展开讲。

3. 实操过程：从一行命令到完整可用

3.1 初始化与依赖安装：别小看脚手架

t3code的搭建，我推荐从官方脚手架create-t3-app开始。别觉得用脚手架是“不高级”的做法，它的价值在于把一堆容易出错的基础配置一次性搞定。命令很简单：

npm create t3-app@latest

执行后按提示选择需要的模块。create-t3-app会问你启用 Next.js、tRPC、Prisma、Tailwind、NextAuth 等，按需勾选即可。我平时一般全选，反正模块之间已经做过了集成验证，比自己从零拼装省心太多。

安装完成后，第一件事是检查.env文件。脚手架会生成一个示例，但数据库连接串需要你自己填。如果是本地开发，我建议直接用 SQLite 起步，零配置最省事：

DATABASE_URL="file:./db.sqlite"

然后执行数据库迁移：

npx prisma migrate dev --name init

执行完成后，SQLite 数据库文件会自动生成，Prisma Client 也会同步生成。这一步跑通，就说明数据库层的链路是通的。一个小提示：prisma migrate dev是开发环境专用命令，它会触发数据库结构同步和客户端生成，生产环境部署时更推荐用prisma migrate deploy，避免意外结构变更。

3.2 核心功能实现：写一个用户鉴权和文章模块

理论说再多，不如一个实实在在的功能落地。我以t3code中最典型的“用户鉴权 + 文章发布”模块为例，从零演示一遍核心代码的写法。

先定义数据模型。打开prisma/schema.prisma，定义一个精简的 User 和 Post：

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

然后初始化 tRPC 路由。在src/server/trpc.ts里，初始化一个带中间件的 tRPC 实例。比如我常用一个protectedProcedure，它会在调用业务逻辑前检查用户是否登录：

import { initTRPC, TRPCError } from "@trpc/server"; import { getServerSession } from "next-auth"; import { authOptions } from "./auth"; const t = initTRPC.context<Context>().create(); const isAuthed = t.middleware(async ({ ctx, next }) => { const session = await getServerSession(ctx.req, ctx.res, authOptions); if (!session?.user) { throw new TRPCError({ code: "UNAUTHORIZED" }); } return next({ ctx: { user: session.user } }); }); export const publicProcedure = t.procedure; export const protectedProcedure = t.procedure.use(isAuthed); export const router = t.router;

这里的关键点是 middlewware：它把权限校验从每个业务函数中抽离出来，统一收敛在路由层。后续新增受保护的接口，只需要把publicProcedure换成protectedProcedure，权限逻辑不用重复写。

最后写业务路由。在src/server/api/routers/post.ts里：

import { z } from "zod"; import { router, protectedProcedure, publicProcedure } from "../trpc"; export const postRouter = router({ list: publicProcedure.query(async ({ ctx }) => { return ctx.prisma.post.findMany({ include: { author: { select: { name: true, email: true } } }, orderBy: { createdAt: "desc" }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1).max(200), content: z.string().min(1) })) .mutation(async ({ ctx, input }) => { return ctx.prisma.post.create({ data: { ...input, authorId: ctx.user.id }, }); }), });

前端页面里调用就非常顺畅了。文章列表页面：

import { trpc } from "../utils/trpc"; export default function PostsPage() { const { data, isLoading } = trpc.post.list.useQuery(); if (isLoading) return <div>加载中...</div>; return <div>{/* 渲染 data */}</div>; }

发布文章的表单、登录状态判断，都是类似模式。整套代码写下来，你会发现：几乎所有数据流都在 TypeScript 的掌控之内，没有一份游离在类型之外的接口定义。

3.3 部署与生产环境配置：别在最后一步掉链子

开发环境跑通了，部署阶段却是很多人翻车的高发区。我在t3code的生产部署上踩过一些坑，这里把关键经验总结出来。

第一，生产环境构建前必须执行prisma generate。很多项目在部署平台（比如 Vercel）上构建失败，原因就是 Prisma Client 没有及时生成。脚手架通常会在postinstall里加上这个命令，但如果你自己改过脚本，请务必确认构建流程里包含它。

第二，环境变量的作用域要提前规划。DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL这些变量，在本地和服务端都必须设置，而且生产环境的NEXTAUTH_URL必须是线上域名。曾经有同学本地一切正常，一上生产就跳转错误，排查了半天，最后发现是NEXTAUTH_URL还指向localhost。

第三，数据库连接串在云服务上要选对区域。如果用托管数据库（比如 Planetscale、Supabase），尽量选择与业务服务器地域一致的区域，可以减少跨区域延迟。同时生产环境的数据库连接建议开启连接池模式，避免高并发时连接数被打满。

一段典型的部署配置体验是：先本地跑npm run build确认无类型错误，再推送 GitHub 仓库，然后让 Vercel 自动拉取并部署。整个过程如果前面类型的底子打得好，基本是一次过的体验。

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

4.1 tRPC 类型不生效的常见原因

这是t3code项目里最容易遇到、也最容易让新手抓狂的问题：明明按照文档写了代码，前端却拿不到类型提示。

排查思路通常是按顺序检查三件事：

• 检查src/utils/trpc.ts里的createTRPCNext是否传入了正确的 router 类型。如果你未将AppRouter传入泛型，那么前端所有调用都会退化成any或者没有补全。
• 检查项目是否处于增量编译状态。Next.js 开发服务器的增量缓存偶尔会“执拗”，改了后端 router 类型后，前端不刷新不生效。此时重启开发服务器基本能解决。
• 检查是否有类型覆盖。有些公司项目会存在declarations.d.ts之类的全局类型声明，把某部分类型遮蔽了。确认一下没有对 tRPC 导入路径做全局 mock。

如果你遇到类型时好时坏的情况，果断重启 dev server，这大概率能解决 80% 的“灵异事件”。

4.2 Prisma 连接数打满与慢查询

Prisma 默认的连接池行为很容易被忽略。开发环境下用 SQLite 你几乎感觉不到，但切换到生产数据库时，连接数可能成为瓶颈。我的经验是：给 Prisma Client 配置合理的连接池上限，避免每次请求都新建连接。

以src/server/db.ts为例：

import { PrismaClient } from "@prisma/client"; const globalForPrisma = globalThis as unknown as { prisma: PrismaClient }; export const prisma = globalForPrisma.prisma ?? new PrismaClient({ log: ["query", "error", "warn"], }); if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

这段代码解决了两个问题：开发环境热重载时不会创建一堆重复的 PrismaClient 实例；生产环境则通过globalThis挂载复用，避免连接资源浪费。对于高并发的查询，可以考虑开启 Prisma 的连接池扩展，但那是进阶优化，初期不着急。

慢查询的排查也很直观，把log: ["query"]打开后，控制台会打印每一条 SQL 语句和耗时。如果发现某条查询特别慢，就去数据库表上检查索引。比如文章列表按createdAt排序时，如果文章量上来，建议在createdAt字段上建索引，效果立竿见影。

4.3 构建时的环境变量与平台差异

部署阶段最磨人的问题，往往出在环境变量和平台差异上。

在我实际部署t3code时，遇到过这样一个问题：本地构建一切正常，推到 Vercel 上之后，页面能访问，但所有依赖数据库的功能都返回错误。日志里写着DATABASE_URL is not defined。一看配置，才发现生产环境的 Environment Variables 里漏填了变量。

更隐蔽的是密钥类变量的格式。NextAuth 要求NEXTAUTH_SECRET是固定长度的字符串，如果你随便写一个太短的，他可能不报错，但登录状态会异常。建议用openssl rand -base64 32生成一个标准的密钥，省得后期排查。

另外，不同平台的构建缓存也会影响 tRPC 类型的生成。如果你修改了 router，但部署平台还在用旧的缓存构建，就会出现“本地有类型提示、线上接口 404”的情况。解决方法是构建时清掉.next缓存目录，或者把平台构建缓存关掉。这个坑很隐蔽，我犯过两次，后来一律在部署脚本里加上rm -rf .next再构建。

4.4 一些容易忽略的开发细节

除了上面这些问题，t3code开发里还有一些小细节，虽然不是致命错误，但会影响体验：

• 名称一致性：REST 时代习惯用小写下划线命名 URL（如get_user_posts），但 tRPC 是函数调用，更推荐用驼峰命名，比如post.getAll、user.getById。保持命名风格统一，类型提示才显得自然。
• 错误处理别吞掉的异常：tRPC 里如果 procedure 抛出异常，前端会收到一个统一的TRPCClientError，但如果你在后端代码里自己try/catch后又忘记抛出，前端就会看到莫名的undefined data。我建议后端尽量少 catch，让错误往上抛，前端根据错误码统一提示。
• 不要在前端直接操作数据库模型：听起来是废话，但总有开发者图方便，直接 import 了@prisma/client的某个类型用在前端。注意，prisma实例绝不能直接进前端 bundle，那会把数据库连接信息暴露到浏览器里。类型可以 import，但实例不行，这是安全红线。

这些经验，都是拿实际部署的教训换来的。写下来不是为了显得自己多厉害，而是希望你看到时少走一段弯路。

5. 把t3code用起来的最后建议

如果你准备在自己的项目里尝试这套体系，我的建议是：先别急着加功能，按我前面说的结构搭一个最小骨架，把文章列表做出来、跑通部署，再逐步往上堆业务。这套模式的前期收益可能只是“编辑器不报错”，但维护一个月之后，你才会真正体会类型全链路带来的省心。

我自己实际用下来的体会是，t3code最值钱的不是某个具体框架，而是一种“把数据契约前置”的思维。它逼着你在写代码前先想清楚数据长什么样、谁能访问、怎么校验。这些思考成本初看是多了，但它换来的是一次又一次“改完类型全局爆红，修完即绿”的确定性。

最后再分享一个小技巧：如果你在团队里推广这套模式，别上来就教育别人“你们 REST 不行”。更好的做法是你自己先做一个小模块跑通，把前后端类型贯通之后，让同事亲手在一个页面里加一个字段，体验一次“改完数据库字段，前端所有引用自动报错”的感觉，行动比说服有效得多。