企业官网建设流程全解析

直接开写。

这两年要论全栈技术圈里被反复提起的框架组合，T3 Stack 绝对是绕不开的一个名字。我最早关注到 t3code 这个项目代号，是因为团队里有个老哥一直在安利 tRPC，说用它写接口可以"把类型安全贯穿到每一层"，当时我半信半疑——毕竟前后端各写各的类型、再手工维护一份接口文档，才是大多数团队的真实日常。后来自己动手搭了一个小工具站，才真正体会到这套组合的爽点：从数据库表结构到前端调用函数，所有类型都是同一套来源，改一处自动同步，那种"编译器替你把关"的感觉，确实比传统的 REST 模式省心太多。

这篇内容不是官方文档的复述，而是我把 t3code 这套项目从初始化、写业务、到部署上线的完整过程拆开来讲。适合已经了解 React 和 Node 基础、但还没系统性用过 T3 Stack 的朋友，也适合那些正在纠结"要不要把团队项目迁到这套组合"的技术负责人。我会把每一步背后的取舍逻辑、实测踩过的坑、以及一些文档里不会写的小技巧，全部摊开来说。

1. 先搞清 t3code 到底解决什么问题

1.1 它本质上是一套"全栈类型安全"的解决方案

t3code 这个名字本身没有太复杂的含义，它更多是社区里对 T3 Stack 技术组合的一种实践代号。T3 Stack 的核心成员是Next.js + TypeScript + tRPC + Prisma + Tailwind CSS + NextAuth.js，这几样东西单独拎出来都是各自领域里的热门工具，但当它们组合在一起时，价值发生了一个质变：整条链路上的数据从数据库出发，经过 ORM 解析、服务端函数调用、网络传输，再到前端页面消费，全程类型自动推导，不需要手写任何接口定义文件。

传统开发模式下，我们拿到后端接口之后的第一步往往是"照着文档封装一个请求函数"，比如GET /api/user/:id返回一个UserInfo对象。前端为了更好地使用，还得定义一个 interface 来匹配响应结构。一旦后端修改了字段名，文档没更新，前端类型又没同步，线上跑挂了才被用户发现——这种问题在我见过的团队里几乎每天都会发生。t3code 的思路直接把这一整段做了压缩：tRPC 让前端像调用本地函数一样调用后端，函数签名天然带着类型信息，前端不用写 API 封装层，后端也不用维护文档。你用 IDE 写代码时的自动补全就是活的文档。

Prisma 负责数据库层，它的 schema 文件定义好模型之后，生成出来的客户端类型是全局唯一的数据库类型来源。也就是说，数据库表长什么样，API 返回什么类型，前端拿到什么数据，全都由一份 schema 驱动出来。改字段名不再需要全项目地毯式搜索替换，重新跑一次prisma generate，所有依赖方在编译阶段就会暴露问题。

1.2 这套组合适合哪些项目、不适合哪些项目

我在实际使用中感受到，t3code 的舒适区是中小型到中型规模的业务系统，尤其是那种数据模型清晰、CRUD 为主、实时性要求不高的应用。比如内容发布后台、内部工具平台、个人项目、SaaS 产品的前中期版本。它的优势在于开发速度快、类型安全兜底，团队里不需要专门的 API 工程师，一两个全栈开发者就能快速把产品跑通。

但如果你遇到了这些情况，我会建议你谨慎选择。第一，你的产品有非常复杂的权限策略和跨服务调用，比如微服务架构、多团队各自维护独立的 API 网关，tRPC 的端到端类型安全反而会成为耦合的负担。第二，你的业务需要大量供第三方调用的公共 API，REST 或 GraphQL 的生态更成熟，OpenAPI 规范、sdk 生成器这些基础设施更完善。第三，你还没有接受 TypeScript——这是硬门槛，t3code 建立在 TS 之上，如果团队对泛型和类型推导的接受度不高，学习成本和日常摩擦会抵掉它带来的收益。

一句话总结我的判断：t3code 不是万能模板，但在"一个团队搞定整个产品"的语境下，它是目前我体验过的最顺滑的组合之一。

2. 从 create-t3-app 初始化开始，每个选项背后都有讲究

2.1 初始化命令与交互选项的实际体验

搭建项目并不复杂，官方提供了脚手架命令：

npm create t3-app@latest my-t3-app

执行之后会进入交互式选择界面，你需要确认启用哪些模块。以下是我实际使用到的一组选择及其理由：

这里补充一个容易忽略的点：脚手架默认的 Prisma 配置用的是 SQLite，方便本地快速跑起来，但这并不代表生产环境也用 SQLite。我在一个项目里因为初期偷懒没有改配置，后面要换到 PostgreSQL 时，发现有个别字段类型在不同数据库之间的行为差异需要重新测试。建议你在初始化之后立刻确认生产环境的数据库类型，把DATABASE_URL和 schema 里的provider同步改好，免得后期返工。

另一个值得注意的地方是 Tailwind CSS 在 App Router 下的配置。新版 create-t3-app 已经把tailwind.config.ts和app/globals.css初始化得比较干净，但如果你对 v4 的 CSS-first 配置不熟悉，在加第三方组件库时容易出现类名冲突。我踩过一次——引入某个 UI 组件库后，发现它的基础样式被 Tailwind 的 preflight 重置了，按钮看起来扁扁的。解决方式是给组件库加important配置或者调整 CSS 引入顺序，这类问题排查起来很磨人，但都属于见一次就会处理的类型。

2.2 目录结构里值得留意的几个文件

初始化完成之后，你会看到一套相对规整的目录结构。对我这种喜欢自己动手搭架子的人来说，有几个文件是值得花几分钟读一遍的：

• src/server/api/root.ts：这是一个聚合出口，把你的所有 router 汇总到一个根 router 上。业务代码增加时，你需要在这里注册新 router，否则接口对前端不可见。
• src/server/api/trpc.ts：这是 tRPC 服务端的核心实例文件，里面定义了createCallerFactory、createTRPCContext等基础工具。如果你的项目要加鉴权中间件、全局错误处理、日志记录，大概率要从这里入手。
• src/trpc/server.ts和src/trpc/react.tsx：这两个文件把 tRPC 客户端和服务端连接起来，一个是服务端调用方式，一个是 React 客户端集成方式。它们之间的协作机制值得你真正理解后再动。
• prisma/schema.prisma：整个数据模型的源头，也是 t3code 类型安全的根。后文会重点讲。

我的习惯是：初始化之后不急着写业务，先挨个点开这几个文件读一遍，搞清楚它们之间的引用关系，再往里面填代码。相信我，这半小时的投资，能帮你省掉后面不少"为什么这里报类型错误"的排查时间。

3. 核心链路实战：一份 Prisma 模型如何贯通到前端

3.1 定义数据模型

我在 t3code 项目中做的是一个简单的用户反馈收集系统，核心数据就是用户和反馈消息。先定义一个清晰的模型：

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

定义完之后执行npx prisma migrate dev --name init来创建数据库表结构，然后npx prisma generate生成客户端。每次重新 generate 后，@prisma/client导出的类型都会根据这个 schema 重新生成，这就是整条链路里类型来源的第一步。

这里有一个新手常犯的错误：在 schema 里直接改字段类型或删除字段后，忘记跑 migrate 或 generate，导致 IDE 里的类型还是旧的，代码却报错；又或者数据库实际结构和代码类型不一致，运行时的查询报错在本地复现不了，到线上才炸。我的建议是：把prisma migrate dev和prisma generate当作一个固定组合命令，只要动了 schema.prisma，就完整执行一遍。

3.2 写一个 tRPC router

接下来在src/server/api/routers/post.ts里定义接口逻辑：

import { z } from "zod"; import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; export const postRouter = createTRPCRouter({ list: publicProcedure.query(async ({ ctx }) => { return ctx.db.post.findMany({ orderBy: { createdAt: "desc" }, include: { author: { select: { name: true } } }, }); }), create: publicProcedure .input(z.object({ content: z.string().min(1).max(500), authorId: z.string().cuid(), })) .mutation(async ({ ctx, input }) => { return ctx.db.post.create({ data: { content: input.content, authorId: input.authorId, }, }); }), });

这里的关键点是：输入校验用的是 zod，tRPC 在运行时用这个 schema 做数据验证，在编译时又把 schema 推导成 TypeScript 类型。所以你不光拿到了服务端校验，还拿到了content和authorId的自动补全。写到这里可能有人会问：那我前端调用时还需要再手动校验一遍吗？

我的答案是：视场景而定。如果这份数据最终会在前端表单里被二次使用，你可以用一个共享的 zod schema 做前后端双重校验，但底层逻辑上，tRPC 的运行时校验本身已经替你做完了服务端必须做的强制校验。前端多做一层只是为了更好的交互体验（比如即时提示"内容不能为空"），而不是为了安全。

3.3 将 router 注册到根文件并暴露给客户端

写完 router 后，去src/server/api/root.ts里注册：

import { postRouter } from "~/server/api/routers/post"; export const appRouter = createTRPC({ router: { post: postRouter, }, }); export type AppRouter = typeof appRouter;

这一步是必须的，因为 tRPC 的前端调用方式是通过AppRouter类型来推断所有可用的接口调用。如果你在这里漏了注册，前端无论怎么调用都拿不到方法名的自动补全和类型推导，排查起来也不是一下子能想到"原来是漏了注册"的。

在前端初始化时，src/trpc/react.tsx里的api对象就是连接 tRPC 客户端的入口。App Router 模式下，脚手架已经帮你配好了 React Server Component 的调用方式，你不需要额外写 fetch 逻辑、不需要设 base URL、不需要处理序列化问题。直接这样用：

import { api } from "~/trpc/react"; function PostList() { const { data, isLoading } = api.post.list.useQuery(); if (isLoading) return <div>加载中...</div>; return ( <ul> {data?.map((post) => ( <li key={post.id}>{post.content} — {post.author?.name}</li> ))} </ul> ); }

如果这段代码让你觉得"这跟直接调用本地函数有什么区别"，那就对了——这就是 t3code 想实现的效果。前端组件里不需要记住接口路径，不需要理解 HTTP 状态码，更不需要在 useEffect 里手动处理 loading/error 的重复逻辑，tRPC 用 React Query 封装好了这一切。

同样的逻辑，useMutation来处理提交动作，还自动带了缓存失效和乐观更新的能力。我做的反馈系统里，"提交新反馈后自动刷新列表"这个功能，代码量几乎只有三行：

const utils = api.useUtils(); const createPost = api.post.create.useMutation({ onSuccess: () => utils.post.list.invalidate(), });

4. 部署到生产环境时的踩坑记录

4.1 环境变量的坑

开发时一切正常，一到生产环境就出一个奇怪问题：前端页面能访问，后端接口 500。查了一圈日志，发现是DATABASE_URL在生产环境没有被正确加载。这个问题的根源在于环境变量的加载顺序和打包时机。

t3code 项目使用dotenv来加载.env，但 Next.js 在 build 阶段会把部分环境变量内联到打包产物里。如果你把DATABASE_URL放在了只在服务器端读取的文件里，却在构建机器上引用了SERVER_xxx这种变量，构建产物里就不会有对应的字符串，运行时自然找不到。解决方式很简单：

• 构建时需要的变量，比如DATABASE_URL，在 CI 或构建平台的环境变量面板里配好；
• 运行时才需要的变量，比如 OAuth 的Secret，在部署平台（比如 Vercel）的 Environment Variables 里配好；
• 本地开发时统一从.env读取，记得把.env加入.gitignore，不要提交到仓库。

还有一个看似无关但很常见的错误：在服务端组件里引用了只存在于浏览器环境的变量NEXT_PUBLIC_*。这种变量在构建时会内联到浏览器 bundle 里，如果你把数据库密钥拿来给它赋值，等于把密钥发给了所有访问者。我在早期项目里就干过这事，当时还在想"为什么构建出来的 console 能看到密钥"，现在回头看真是后怕。

4.2 部署平台选择和 Server 端运行时长

t3code 如果采用 App Router + Server Component，很多页面是服务端渲染的，这意味着你的 Node.js 进程需要有长时间的运行能力。如果只是部署在 Vercel 的免费计划上，函数运行时长有限，复杂的服务端渲染请求（比如同时查询多个数据库表）容易超时。一个非常直观的例子：某个后台报表页面上，我在 Server Component 里连续查询了六个 Prisma 模型，本地开发一秒钟出结果，到了 Vercel 上偶尔会报 504。

出现这种情况时，我的处理策略是拆分页面或改用 Client Component 配合 tRPC 查询——把服务端渲染的压力降下来，查询放到客户端完成，效率反而更高，因为 React Query 的缓存可以减轻重复请求的负担。另一个思路是：如果是内网系统或对访问延迟不敏感的 B 端工具，可以考虑自托管 Node.js 服务，部署在华云、腾讯云、阿里云等国内云主机上，稳定性和可控性都比 Serverless 更好。这里不具体推荐哪一家，重点是想说：部署平台的选择会直接影响 t3code 项目的架构取向，你不能只按"最好部署"去选，要按"哪些页面需要服务端渲染、哪些可以客户端渲染"来综合考虑。

4.3 日志和错误追踪的缺失感

开发模式下，tRPC 服务端的报错会直接打印在终端里，配合 pretty-error 很舒服。但到了生产环境，这种便利就消失了。如果应用在某个角落静默失败，你只能靠部署平台的日志去猜。我的建议是：

• 在trpc.ts里加一个全局中间件，把请求信息（procedure 路径、入参、耗时）打印出来；
• 使用 Sentry 或类似平台接入错误监控，前端把页面错误和后端 tRPC 错误都上报起来；
• 重要的 mutation 操作（比如创建、更新、删除）要打业务日志，方便出问题后做数据重建。

这些事看起来是"额外工作量"，但对真实项目来说，它们是"上线后的救命稻草"。我在自托管部署期间就被线下问题折腾过：数据库的一个外键删不掉，导致用户反馈列表涨出大量脏数据，如果当初没有打业务日志，我根本看不出来是哪个操作引发的。

5. 一些真正提升体验的进阶习惯

5.1 用 zod 的共享 schema 做表单校验

t3code 在服务端已经帮你集成好了 zod，但这套能力远不止于"输入校验"。如果你的表单也需要校验，直接在项目里建一个shared/schemas.ts，把每个 mutation 的 input schema 导出出来，前端表单也用同一个 schema 做验证，这样前后端校验规则就永远不会不同步。我代码里经常会看到：

export const createPostSchema = z.object({ content: z.string().min(1).max(500), });

然后在 tRPC router 的 mutation 里引用它，前端表单也用同一个 schema 做校验。改规则时只改一处，这样的体验会让"改需求"变成一件非常轻量的事情。但也有边界：当某个字段只在前端需要展示（比如拖拽排序），或者只在后端需要处理（比如权限判断），就不适合放进共享 schema。学会划分"哪些字段需要共享""哪些字段必须分层"，是 t3code 进阶的一道分水岭。

5.2 理解 procedure 的权限控制

默认生成的publicProcedure是不带鉴权的，任何请求都能调用。真实项目里，很多数据只能让登录用户看，这就要用到protectedProcedure。脚手架里其实已经给出了示例：

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

用上之后，你的 router 可以写成protectedProcedure.query(...)，未登录请求会直接被拦截，连代码都不会进入业务逻辑层。这种写法的好处是把鉴权从业务代码里剥离出来，让开发者在写具体逻辑时不用操心"谁能调用"这件事。我在做反馈收集功能时，用户提交自己的反馈内容、查看自己的历史记录，只要在对应的 procedure 上加一个 protected，就天然有了数据隔离的基础。

说实话，T3 Stack 这套组合的上手门槛并不高，真正花时间的是理解它的设计哲学——类型优先、约定优于配置、少写胶水代码。只要在这些点上想通了，后面写业务代码就是纯粹的享受。

5.3 别忘了阅读源码生成的产物

如果你在某天突然发现"IEDE 里的自动补全为何不工作了"，或者"tRPC 调用的类型推导突然失效了"，第一反应不要去找配置问题，先重新执行一次npx prisma generate，再重启一下 TypeScript 服务。我遇到过的绝大多数类型异常，都源于@prisma/client的生成产物和实际 schema 不同步。把这件事变成肌肉记忆之后，你和 t3code 之间的磨合期基本就算结束了。

6. 把 t3code 当作一种思维方式，而不只是脚手架

写了这么多,最后依然要回归到问题的本质：t3code 最打动我的，不是"某个框架多好用",而是它逼着你在写代码之前先想清楚数据从哪来、到哪去、由谁校验、由谁消费。这套思维方式适用于任何技术栈。哪怕你的项目明天就换成了 GraphQL 或者 OpenAPI，这种"类型驱动设计"的习惯依然会让代码更安全、更可维护。

如果你打算尝试 t3code，我的实际建议是：找一个非核心的小工具或模块先行试点，别把一个刚起步的团队主力项目直接梭哈进来。先用一周时间把一个小功能跑通，感受一下前后端类型联动带来的体验变化，再决定取舍。我自己就是从一个小模块开始，逐渐把这套组合应用到了三个项目上，目前为止，没有后悔过。