企业官网建设流程全解析

“t3code”这个名字我第一次看到的时候，其实有点懵。T3？第三代？还是某种缩写？翻了翻手头的资料、又结合这几年折腾全栈项目的经验，我才慢慢意识到，这大概率不是一个具体的框架，而是一套关于“TypeScript 全栈技术组合”的项目代号，甚至可以说是某种技术主张。无论它是你手里的一个开源模板、一个内部脚手架，还是一个个人作品的代称，围绕“t3code”能聊的东西非常多，从技术选型到工程化落地，每一层都有值得掰开揉碎讲清楚的地方。

这篇文章，我打算拿“t3code”当主线，用一个真实的项目视角去拆解它背后的技术栈、架构思路和完整落地过程。我会把端到端类型安全、全栈框架搭配、数据层建模、认证集成、部署上线这些核心环节从头到尾捋一遍，也会把我在实操中踩过的坑、试出来的经验一并写出来。如果你正准备从一个零散想法搭建一个全栈应用，或者想理解当前主流 TypeScript 技术栈之间如何协作，这篇文章应该能给你一份可以直接参考的作业。

1. 项目定位与整体设计思路

1.1 先从“t3code”这个名字说起

很多开发者喜欢给项目起个有辨识度的名字，“t3code”看起来就像是 T3 Stack 的某种衍生表达。T3 Stack 是国外开发者圈子里流行的一套全栈组合，核心是Next.js + TypeScript + Tailwind CSS + tRPC，主打的就是“端到端类型安全”。t3code 这个名字，完全可以理解为这套技术理念下的一个具体实践项目——不管你最终用它来做什么，它的骨架基本就是围绕这套技术栈组织的。

如果你还没接触过这套组合，这里先用大白话解释一下每个成员的角色。Next.js负责应用框架层面的事情，包括页面渲染、路由、API 接口，它给你一个统一的“全栈容器”。TypeScript是类型系统，负责在编译期间帮你发现大部分低级错误，让前后端代码像签订了契约一样互相约束。Tailwind CSS解决样式问题，它不像传统写法那样维护一堆 CSS 文件，而是直接在标签上组合原子类名，改样式不用跨文件找来找去。tRPC是这里面最值得一提的成员，它让你在前端代码里直接调用后端函数，类型定义从数据库一路通到页面组件，中间不需要手写任何接口文档和类型声明。

对“t3code”这种项目来说，选择这套组合不是跟风，而是实实在在解决了一个痛点：一个人开发全栈应用时，最大时间损耗往往不是写逻辑，而是在前后端接口对齐上反复拉扯。用了这套组合之后，后端函数签名变了，前端立刻报红，这种即时反馈能省掉大量联调时间。所以如果让我一句话概括 t3code 的定位，那就是：用最少的胶水代码，构建一个全程类型安全的全栈应用。

1.2 为什么选这套技术组合，而不是传统方案

聊技术选型，不能只看别人说“好”就跟着用，得弄清楚它到底解决了什么问题。过去我们做前后端分离，通常是后端用 NestJS 或 Express 写 REST 接口，前端用 Axios 发请求，中间靠 OpenAPI（Swagger）文档同步契约。听起来很正规，但在单人开发或小团队场景下，这套流程有很明显的隐性成本：

• 每加一个接口，你得先改后端代码、再改前端请求代码、还得更新文档；
• 后端返回的数据结构和前端期望的类型不一致时，往往是运行时才发现；
• 重构字段名时，前后端要分别改，漏一处就是线上故障。

tRPC 的思路完全不同。它没有 RESTful 那一套资源路径和动词约束，也不依赖 OpenAPI 文档，而是把后端函数直接暴露给前端调用。前端引用一个api.post.list.useQuery()，后端修改了PostRouter里的返回类型，前端这个调用点立刻就能在编辑器里看到类型报错。这种感觉就像你跟后端同事坐在同一个屏幕前写代码，所有契约都由编译器实时校验。

拿 REST 和 tRPC 做个对比，差异就很直观了：

我不是说 REST 不好——如果项目要做开放平台，供第三方开发者调用，REST 依然是标准答案。但 t3code 这种“一个人管前后端”的项目形态，tRPC 的收益明显大于成本。Next.js 负责提供运行时环境，tRPC 负责打通类型与调用，Prisma 负责把数据库表结构变成类型安全的查询客户端，这一条链路下来，你写每一个业务功能时都像在“带着安全绳走路”，心里踏实很多。

2. 核心架构与关键依赖拆解

2.1 目录结构与模块划分

一个成熟的全栈项目，目录结构基本决定了后续维护体验。t3code 这类基于 T3 Stack 的项目，目录通常长这样：

t3code/ ├── prisma/ │ ├── schema.prisma # 数据模型定义 │ └── seed.ts # 种子数据脚本 ├── src/ │ ├── pages/ # 页面路由（Next.js 文件路由） │ │ ├── index.tsx │ │ ├── posts/ │ │ │ ├── [id].tsx # 动态路由 │ │ │ └── create.tsx │ ├── server/ │ │ ├── api/ │ │ │ └── trpc/ │ │ │ └── [trpc].ts # tRPC HTTP 入口 │ │ ├── auth.ts # 认证配置 │ │ ├── db.ts # Prisma 客户端实例 │ │ └── trpc/ │ │ ├── context.ts # 每次请求的上下文（用户、session） │ │ ├── router.ts # 根路由聚合 │ │ └── caller.ts # 服务端调用入口 │ ├── modules/ # 按业务域拆分的模块 │ │ ├── post/ │ │ │ ├── post.router.ts # 帖子相关接口 │ │ │ ├── post.service.ts # 业务逻辑 │ │ │ └── post.schema.ts # 入参校验 schema │ │ └── user/ │ ├── styles/ # 全局样式 │ └── utils/ │ └── api.ts # 前端 tRPC 客户端封装 ├── .env # 环境变量 ├── package.json ├── tailwind.config.ts └── tsconfig.json

这种结构最大的好处是依赖方向清晰。pages层只负责 UI 和调用utils/api，server层负责持有 tRPC 路由和数据库实例，modules层按业务域组织内聚的接口和逻辑。改一个帖子相关的功能，你只需要在modules/post目录里活动，不需要在整个项目里四处打补丁。

2.2 端到端类型安全是怎么打通的

理解 t3code 的技术核心，其实就一句话：类型安全不是某个工具单独给的，而是一条链路的设计结果。链路起点是数据库表结构，终点是 React 组件里的数据渲染。中间每一环都通过 TypeScript 的自动推断传递类型，不经过任何手写的中间类型定义。

拿 Prisma 举例。你在schema.prisma里定义了一个Post模型：

model Post { id String @id @default(cuid()) title String content String published Boolean @default(false) authorId String author User @relation(fields: [authorId], references: [id], onDelete: Cascade) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

跑完prisma generate之后，Prisma 客户端会自动生成完整的Post类型。这个类型会被引入到 tRPC 的 Router 里作为返回值，tRPC 在编译期就会根据这个返回值推断出前端调用时的数据类型。你在页面里写：

const { data } = trpc.post.list.useQuery(); {/* data 里的每一项都自动带 title、content、published 等字段类型 */}

如果哪天数据库里把title改成了name，重新生成 Prisma 客户端之后，从 Router、Service 到页面组件的所有相关类型会全部报错。这种“改一处，全局亮红灯”的体验，比任何测试用例都更直观地保证结构一致性。

有人可能担心这种做法会不会带来性能问题。tRPC 调用本质上还是 HTTP 请求，序列化用的是superjson（或 JSON），数据量小的时候性能跟 REST 没什么区别。真正的关键点在于，tRPC 可以精准控制返回字段，你可以在 Router 里只 select 所需字段，避免把整张大表塞给前端。这是使用时的一个好习惯，后面讲实操时我再展开。

3. 实操过程：从初始化到核心功能落地

3.1 环境准备与脚手架初始化

动手之前先把环境理清。t3code 这类项目推荐 Node.js 18+ 或者 20 LTS，包管理器我建议直接用pnpm——它在依赖安装速度和磁盘占用上明显优于 npm，而且对 monorepo 和严格依赖声明更友好。如果你机器上还没装，可以先跑一下：

corepack enable

然后使用官方脚手架初始化项目：

npx create-t3-app@latest t3code

脚手架会问你选择哪些模块。我的建议是勾选Next.js、Tailwind CSS、tRPC、Prisma、NextAuth.js。如果项目暂时不需要数据库引用关系或复杂权限，别的功能模块可以先不选，保持项目干净。初始化完成后，进入项目并安装依赖：

cd t3code pnpm install

接下来配置环境变量。项目根目录里有个.env.example，把它复制成.env：

cp .env.example .env

至少需要补以下几项：

DATABASE_URL="postgresql://user:password@localhost:5432/t3code" NEXTAUTH_SECRET="直接复制一串随机字符串，后面可以改" NEXTAUTH_URL="http://localhost:3000"

跑起来之前，先确认数据库存在。如果你是本地开发，可以用 Docker 起一个 PostgreSQL，省去手动安装：

docker run --name t3code-pg -e POSTGRES_PASSWORD=password -e POSTGRES_DB=t3code -p 5432:5432 -d postgres:16

然后同步数据库并启动开发服务：

npx prisma db push pnpm dev

看到终端出现 “Ready in xxx ms”，访问http://localhost:3000，一个全栈类型安全的应用就站起来了。脚手架自带一个示例页面，你可以改一改上面的内容，试试热更新是否正常。

3.2 数据模型设计：从需求到 Prisma Schema

一个项目总是从“要存什么数据”开始的。以 t3code 做一个简单的博客社区为例，我们需要用户、文章和评论三张表，它们之间的关系是：用户拥有文章，文章拥有评论，评论属于某个用户。

我把schema.prisma设计成下面这样：

generator client { provider = "prisma-client-js" } datasource db { provider = "postgresql" url = env("DATABASE_URL") } model User { id String @id @default(cuid()) name String? email String? @unique emailVerified DateTime? image String? accounts Account[] sessions Session[] posts Post[] comments Comment[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Post { id String @id @default(cuid()) title String slug String @unique content String published Boolean @default(false) authorId String author User @relation(fields: [authorId], references: [id], onDelete: Cascade) comments Comment[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Comment { id String @id @default(cuid()) body String postId String post Post @relation(fields: [postId], references: [id], onDelete: Cascade) authorId String author User @relation(fields: [authorId], references: [id], onDelete: Cascade) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

这里有几个细节值得注意：

• 主键用cuid()而不是自增整数。对全栈项目来说，cuid 天然适合分布式环境，不会出现自增主键在数据合并或迁移时的冲突。
• slug加唯一索引。博客文章用语义化链接比用数字 ID 更友好，也给后续做 SEO 留了空间。
• 外键关系都加onDelete: Cascade。删除用户时文章和评论会被级联清理，避免孤儿数据。

模型建好后，同步到数据库并生成客户端：

npx prisma db push npx prisma generate

严格来说，正式项目应该用prisma migrate dev来管理迁移记录，但开发初期用db push快速迭代模型更顺手。等模型稳定了，再切到 migrate 工作流。

3.3 用 tRPC 实现核心业务接口

模型有了，接下来写接口。t3code 的业务逻辑集中在modules层，先建一个 post 模块。约定三件事：入参校验用 zod、业务逻辑写在 service、Router 只做转发和鉴权。

先定义入参校验 schema：

// src/modules/post/post.schema.ts import { z } from "zod"; export const createPostSchema = z.object({ title: z.string().min(1).max(120), slug: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/), content: z.string().min(1), published: z.boolean().default(false), }); export const getPostSchema = z.object({ id: z.string().cuid(), });

接着写 service。这里只写两个核心方法：创建文章、按 slug 查询文章。

// src/modules/post/post.service.ts import { db } from "~/server/db"; import type { createPostSchema, getPostSchema } from "./post.schema"; import type { z } from "zod"; export async function createPost(input: z.infer<typeof createPostSchema>, authorId: string) { return db.post.create({ data: { ...input, authorId, }, }); } export async function getPostBySlug(input: z.infer<typeof getPostSchema>) { return db.post.findUnique({ where: { slug: input.slug }, include: { author: { select: { name: true, image: true } }, comments: { include: { author: { select: { name: true, image: true } } }, orderBy: { createdAt: "desc" }, }, }, }); }

这里注意一个细节：查询评论列表时，我用include嵌套了 author 信息并只 select 了展示需要的字段，避免把完整 User 记录发给前端。这种“按需取数”的习惯在 tRPC 项目里非常重要，因为它直接决定了接口响应体大小。

最后定义 Router：

// src/modules/post/post.router.ts import { router, protectedProcedure, publicProcedure } from "~/server/trpc"; import { createPostSchema, getPostSchema } from "./post.schema"; import * as postService from "./post.service"; export const postRouter = router({ create: protectedProcedure .input(createPostSchema) .mutation(({ input, ctx }) => { return postService.createPost(input, ctx.session.user.id); }), bySlug: publicProcedure .input(getPostSchema) .query(({ input }) => { return postService.getPostBySlug(input); }), });

看到protectedProcedure和publicProcedure是不是有点眼熟？这正是 tRPC 好用的地方：你可以在过程中间件里定义“哪些接口需要登录”，然后在 Router 定义时直接选用对应的 procedure。没有登录态时调用create，tRPC 会直接返回 401 错误，根本进不了业务函数。

根路由别忘了聚合：

// src/server/trpc/router.ts import { router } from "../trpc"; import { postRouter } from "~/modules/post/post.router"; export const appRouter = router({ post: postRouter, }); export type AppRouter = typeof appRouter;

3.4 前端怎么调用：页面接入 tRPC

后端接口定义完，前端调用代码少得让人有点不适应。以文章创建页为例：

// src/pages/posts/create.tsx import { useRouter } from "next/router"; import { api } from "~/utils/api"; import type { SubmitHandler } from "react-hook-form"; import { useForm } from "react-hook-form"; type FormValues = { title: string; slug: string; content: string; published: boolean; }; export default function CreatePostPage() { const router = useRouter(); const utils = api.useUtils(); const { register, handleSubmit } = useForm<FormValues>(); const createPost = api.post.create.useMutation({ onSuccess: async () => { await utils.post.invalidate(); await router.push("/"); }, }); const onSubmit: SubmitHandler<FormValues> = (values) => { createPost.mutate(values); }; return ( <form onSubmit={handleSubmit(onSubmit)} className="mx-auto max-w-2xl space-y-4"> <input {...register("title")} placeholder="标题" className="w-full border p-2" /> <input {...register("slug")} placeholder="slug" className="w-full border p-2" /> <textarea {...register("content")} placeholder="正文" className="h-48 w-full border p-2" /> <label className="flex items-center gap-2"> <input type="checkbox" {...register("published")} /> 立即发布 </label> <button type="submit" className="rounded bg-blue-600 px-4 py-2 text-white"> 创建文章 </button> </form> ); }

这里有个细节：createPost.mutate(values)传给后端的values会自动经过 zod 校验，如果 title 为空或 slug 格式不对，tRPC 会返回校验错误。前端虽然没写任何校验逻辑，但也算有了基础兜底。当然正式产品里，前端最好也加一层 useForm 的校验规则来提升交互体验，后端 zod 校验是保底线，两者不冲突。

文章详情页的查询就更加简单了：

const { data, isLoading } = api.post.bySlug.useQuery({ slug: router.query.slug as string }); if (isLoading) return <div>加载中...</div>; return <article>{data?.content}</article>;

一屏代码里既没有 axios 封装，也没有 useEffect 手动触发请求，所有状态管理都由 tRPC 和 React Query 在底层处理。这个组合拳打下来，写业务功能的速度确实快得离谱。

3.5 认证接入与权限控制

认证方案直接用 NextAuth.js，这是 T3 生态里最顺滑的选择。配置在src/server/auth.ts里，以 GitHub 登录为例：

import NextAuth from "next-auth"; import GitHub from "next-auth/providers/github"; import { PrismaAdapter } from "@next-auth/prisma-adapter"; import { db } from "~/server/db"; export const { handlers, auth, signIn, signOut } = NextAuth({ adapter: PrismaAdapter(db), providers: [ GitHub({ clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, }), ], callbacks: { session: ({ session, user }) => ({ ...session, user: { ...session.user, id: user.id }, }), }, });

要把session.user.id传给 tRPC 的 context，还需要在src/server/trpc/context.ts里做一次桥接：

import { auth } from "~/server/auth"; import { db } from "~/server/db"; export async function createTRPCContext() { const session = await auth(); return { db, session, }; }

这样之后，Router 的ctx.session.user.id就能拿到真实用户 ID。权限控制不用为每个接口单独写判断逻辑——能登录就 protected，能管理后台就再包一层 adminProcedure。

3.6 部署准备：本地跑通到线上上线

t3code 部署首选 Vercel，因为 Next.js 就是 Vercel 亲儿子，部署体验很顺滑。但准备工作一点不能省。

先保证数据库可公网访问。我用的是 Neon 或 Supabase 这种 Postgres 托管服务，省去自己维护数据节点的负担。把连接字符串填到 Vercel 的 Environment Variables 里，字段跟本地.env保持一致。

构建命令里需要先跑 Prisma 生成和迁移。Vercel 项目配置里设置：

pnpm postinstall && npx prisma migrate deploy

“migrate deploy”会用prisma/migrations目录下的迁移文件更新线上数据库，注意不要在构建时用db push——那会直接覆盖模型而丢失迁移历史。

然后是 tRPC 的适配问题。Next.js 的pages/api/trpc/[trpc].ts入口本身兼容 Vercel Serverless，不需要额外配置。但要注意Vercel 的函数超时和包体积限制，Node.js 函数最大执行时长为 60 秒（个人版），超长任务应该异步化处理，比如用数据库任务队列。如果项目依赖很重，建议开启 Output File Tracing，把不必要的打包排除掉。

部署时我自己习惯先在 Vercel CLI 里做一次 preview 部署看日志：

vercel --prod

如果构建失败，八成是环境变量缺失或 Prisma 产物没生成。这时候回到 Vercel 项目的 Build Log 里逐行看，大部分问题都能定位。

4. 常见问题与排查实录

4.1 tRPC 类型不匹配，前后端接口报红

症状：前端调用api.post.create.useMutation()时，TypeScript 提示参数类型不符合后端入参定义，明明本地代码没改，却突然红了一片。

排查思路：这种情况一般发生在 Prisma 模型或 schema.ts 调整之后，没有重新生成客户端。tRPC 的类型是从后端函数返回值推断的，Prisma 客户端旧类型没更新就会造成“前端预期”和“后端实际”脱节。

解决：

npx prisma generate pnpm dev

如果还报红，看看 tRPC 服务端的router.ts是否引用了旧模块路径，或者tsconfig.json的路径别名~/*是否配置失误。这块修复之后重启编辑器，等 TypeScript 服务重新加载。

4.2 Prisma 客户端与 Next.js 边缘运行时冲突

症状：用了 Next.js Middleware（中间件）做路由守卫，结果运行时提示 Prisma 无法在 Edge Runtime 工作，进程直接崩。

原因：Prisma 依赖 Node.js 原生驱动，而 Middleware 默认运行在 Edge 环境，该环境并不支持所有 Node API。这不是 t3code 特有的坑，但很容易踩。

解决：不要在 Middleware 里调用 Prisma 或任何数据库操作。Middlewar 适合做简单的鉴权重定向（字段校验、cookie 检查），数据查询放在getServerSideProps或 tRPC 里做。确实需要在请求早期判断登录态的，可以读取 NextAuth 的 session cookie 做无状态校验，不要去查数据库。把 t3code 的 Middleware 功能“瘦身”成薄薄一层，很多诡异问题都会消失。

4.3 部署后接口 404 或 500

症状：本地开发一切正常，到了线上环境刷新页面，接口请求 404 或者 500。

排查思路：404 优先看pages/api/trpc/[trpc].ts文件名是否准确。漏掉了[trpc]的中括号，整个 tRPC 路由没法匹配。500 则要在vercel --prod的日志里看具体堆栈，常见原因是环境变量没同步到线上。DATABASE_URL尤其要注意，本地是内网地址、线上必须换成外部可访问的地址，否则数据库连接直接被拒绝。

我把这类问题整理成一个速查表，方便遇到时逐一对照：

4.4 构建体积过大，部署超时

症状：Vercel 构建时间从 1 分钟涨到 5 分钟，日志显示某个依赖包很大，甚至触发函数包体积上限。

原因：t3code 若把大量服务端依赖塞进了同一个 bundle，尤其是不小心在pages里引用了服务端专属库，构建体积会被拖起来。

解决：思路是按需加载。tRPC 里的大依赖（如 Prisma）本身是在 Node 端运行的，如果页面里只用了api客户端，不要把它 import 成全局对象。Next.js 支持从next/dynamic动态加载页面级别的组件，代码分割会自动进行。另外确认是否开启了serverComponentsExternalPackages（如果用到 App Router），把@prisma/client、prisma等假外部化，避免二次打包。

如果你用 Docker 自托管部署，记得在next.config.js里开启output: "standalone"，这样产出一个精简的独立服务本体，镜像体积能小一个量级。

5. 项目扩展与阶段性经验沉淀

5.1 从“能跑”到“好用”：中间件与日志体系

项目跑通前后端主流程之后，下一步往往是可观测性。t3code 如果只停留在“能访问、能登录、能增删改查”，离“好用”还有距离。我会优先做几件事：

第一件是增加所有 tRPC 查询的日志输出。不用上重型日志平台，中间件里直接console.log请求路径、耗时、用户 ID，然后统一收集到日志服务就行。这样线上出问题时，你能快速定位是哪个接口耗时异常。

第二件是给错误加语义化信息。tRPC 的错误码只有NOT_FOUND、UNAUTHORIZED这些，但业务错误需要更细的提示。在 service 里抛出new TRPCError({ code: "BAD_REQUEST", message: "标题不能为空" })，前端捕获后直接渲染给用户，体验会好很多。

第三件是监控。加一层 Sentry 到 Next.js 项目，把前后端未捕获异常自动上报。对个人项目来说，这比手动看日志高效太多。

5.2 功能扩展：文件上传如何优雅地融入 t3code

t3code 的架构里，文件上传是一个容易绕弯的地方。如果直接走 tRPC，请求体必须经过 JSON 序列化，传大文件极其低效。我试过 base64 文件流塞进 mutation 参数，小文件没问题，超过 10MB 体验直线下降。

正确的姿势是混搭：大文件走独立的上传服务，比如 S3、Cloudflare R2，上传成功后把返回的文件 URL 作为字符串存到数据库；小文件也可以考虑直接 base64 编码后走 tRPC，但只适合头像这类小体积场景。这样做既保留了类型安全的 CRUD 主链路，又不牺牲上传效率。

5.3 阶段性总结：t3code 项目沉淀了什么

每次写完一个项目，我会边回想边把心得沉淀到文档和代码注释里。t3code 走到一定程度，它给我留下的不只是可运行的代码，更是几个稳定的工程习惯：

• 类型优先。先定义 schema 和 Prisma 模型，再写业务函数和页面，让类型契约驱动开发顺序。
• 小步提交。每完成一个模块就提交一次 Git，方便回溯类型重构带来的连锁影响。
• 依赖最小化。不要为了省事把什么库都装进来，tRPC 生态帮你省了接口文档、请求库、状态管理库，也意味着你需要自己维护的代码面更小。

这一套做下来，t3code 已经从最初一个模糊的技术代号，变成了一套清晰可复用的全栈工程路径。如果你正打算启动自己的新项目——不管叫不叫 t3code——顺着这条路线走，你会发现自己可以把大头精力花在真正的业务逻辑上，而不是在前端与后端之间的沟通上反复折腾。