朋友前两天问我，“你那个 t3code 一天到晚挂在嘴边，到底是个什么东西？名字起得跟开源库一样。”听他这么一说我才发现，确实从来没认真解释过这个代号。t3code 不是某个 npm 包，也不是哪个团队开源的轮子，而是我给自己最近做完的一个全栈实践项目起的代号：用 T3 技术栈——TypeScript、Tailwind CSS、tRPC 这三样打底，加上 Next.js 和 Prisma，搭一个专门用来写“代码与工程实践”的个人博客站。名字很直白：关于 T3 的代码，顺便也把我在这个技术体系下踩过的坑、验证过的思路都扔进去。

这个项目解决了什么问题？往大了说，是对“类型安全全链路”的一次试验——从数据库、接口到页面组件，让类型定义贯穿始终，把前后端联调时那堆“字段名写错了”“类型对不上”的低级问题按在萌芽期；往小了说，我就是想在自己的项目里试试 Server Components、tRPC、Prisma 这些近几年的热门工具能不能串得顺，最后得到一个既能写文章、又能给别人当参考的代码库。如果你正在学 TypeScript 和 Next.js，或者对 tRPC 这种“不写 REST 也不用 GraphQL”的方案好奇，这篇复盘应该能给你一些真实可复用的经验。

1. 先把 t3code 的定位想清楚：T3 是技术栈，也是一种取舍标准

很多朋友看到 T3 会问：这跟别的技术体系里的“T 字头”有没有关系？没有。T3 直接来自 TypeScript、Tailwind CSS、tRPC 三个单词的首字母，三个都是 T，组合起来就叫 T3。网上常玩笑说这是“三个 T 凑一桌”，但我更愿意把它理解成一套决策标准——哪个工具能减少复杂度和摩擦，就优先用哪个。

1.1 TypeScript、Tailwind、tRPC 各自解决什么问题

先说 TypeScript。今天的 Next.js 项目里用 TypeScript 已经不算超前，但 T3 里强调 TS 不是为了“有类型更高级”，而是为了把文档写进代码。我在 t3code 里定义所有接口的 schema、所有路由的入参出参，类型就是它们之间的契约。实际开发中，前端同事不用追着后端要接口文档，IDE 补全和类型推导已经告诉你能拿到什么、该传什么。这个收益在单个全栈项目里体现得最直接，因为我既是前端也是后端，类型不安全的温床往往就是“我记得这个字段叫 name，但数据库里它是 nickname”。

Tailwind 则是把 CSS 的开发成本压到了最低。有人觉得 Tailwind 适合原型、不适合精雕细琢，但 t3code 作为一个内容型站点，绝大多数样式都是“布局 + 排版 + 少量交互”，Tailwind 的原子类能让我在写 React 组件时顺手把样式写完，不需要切到 CSS 文件、起类名、查有没有命名冲突。加上@tailwindcss/typography插件，markdown 博客正文的排版质量基本开箱即用，不用自己写一套文章样式。

tRPC 是三者里最容易被误解的。它不是把 REST 干掉，而是让客户端直接调用服务端函数，类型推断自动贯穿。写api.post.list.useQuery()，返回的数据是什么类型，前端根本不用手动声明。这背后用到的不是魔法，而是 TypeScript 的typeof推导——服务端 router 的类型作为泛型传给客户端 React Hook。T3 选择 tRPC 而不是坚持 Fetch + 手写类型，看重的正是小团队、全栈项目里最大的摩擦力往往来自“接口对接”，能省则省。

1.2 为什么我没走 REST，也没选 GraphQL

做 t3code 之前我快速对比过三种方案。

REST 的思路简单清晰，但问题在类型维护：每个接口要写 Handler、写请求参数校验、写响应类型，一套博客系统的文章增删改查，写到后面接口路径一堆，类型文件也跟着膨胀。GraphQL 能严格约束查询和数据形状，但为一个小型博客站引入 Schema 定义、Resolver 组织、客户端缓存，明显超配。而且 GraphQL 经常暴露“所有字段可查”的权限边界，哪怕有工具辅助，心里也得多个弦。

tRPC 恰好落在这个平衡点上：没有接口路径设计负担，一个router就是你的后端能力清单；输入用 Zod 校验，一个z.object就完成“参数合法且类型正确”；输出端由 Prisma 返回值和t.procedure.query的推断结果自动决定。我用一个表格总结当时的选择逻辑：

我自己的结论是：tRPC 是为“同一套代码库内、一个人或小团队完成前后端”的场景而生的。t3code 恰好就是这个形态。

1.3 t3code 的边界：一个博客站到底有哪些能力范围

有了选型，还得把项目边界划清楚。t3code 不是一个普通博客 CMS，它有四个核心能力：

• 文章列表、详情、分类筛选，数据从 PostgreSQL 来；
• markdown 内容服务端渲染，代码高亮 + 排版舒适；
• 文章点赞、浏览计数这类交互，不刷新页面也能更新；
• 管理侧简单登录，发布或下线文章。

这个边界决定了我的技术清单长什么样：Next.js 14 的 App Router + React 18 + TypeScript 5.x + Tailwind CSS 3.4 + tRPC v11 + Prisma 5 + Zod。没有引入状态管理库，也没有接入组件库，尽量让每一层保持轻量。项目跑起来之后我发现，这个边界设定最大的好处是：每当我产生“再加一个功能”的冲动时，第一反应不是去装新库，而是先问自己这个功能是否值得破坏当前的最小闭环。

2. 搭建工程骨架：从 Prisma schema 到 tRPC router 的类型链路

技术选型敲定后，最花心思的是工程骨架。t3code 的骨架核心就一句话：让类型从数据库出发，一路走到页面组件，中间不打结。实现这件事靠的是三层结构：Prisma schema 定义数据模型，tRPC router 定义服务端能力，前端通过createTRPCReact<AppRouter>()获得类型安全的调用入口。

2.1 目录结构：把 server 和 app 的边界立起来

先看我最终采用的目录结构：

t3code/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── app/ │ │ ├── (main)/ │ │ │ ├── page.tsx │ │ │ └── posts/[slug]/page.tsx │ │ ├── api/trpc/[trpc]/route.ts │ │ └── _trpc/ │ │ ├── client.ts │ │ └── Provider.tsx │ ├── server/ │ │ ├── db.ts │ │ ├── api/ │ │ │ ├── root.ts │ │ │ ├── trpc.ts │ │ │ └── routers/ │ │ │ ├── post.ts │ │ │ └── user.ts │ ├── styles/ │ │ └── globals.css │ ├── tailwind.config.ts │ └── tsconfig.json

这个结构最关键的一点是把server/与app/隔离。app/里放页面、布局、客户端组件和 tRPC 的 API route；server/里放数据库实例、业务逻辑和 tRPC server 端定义。隔离的目的不是好看，而是为了守住类型安全：如果你在客户端组件里 import 了一个只在服务端使用的模块，Next.js 会报错或者想办法把你不想暴露的代码打包进浏览器。t3code 里的编译错误有相当一部分就是这种越界引用被 TypeScript 拦下来的。

2.2 Prisma schema 先行：数据模型是类型的源头

数据模型是所有类型推导的起点。我在prisma/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 posts Post[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Post { id String @id @default(cuid()) title String slug String @unique content String excerpt String? published Boolean @default(false) views Int @default(0) author User? @relation(fields: [authorId], references: [id]) authorId String? createdAt DateTime @default(now()) updatedAt DateTime @updatedAt }

写完 schema 后执行npx prisma migrate dev，Prisma 会根据表结构生成 client 类型。之后在服务端任何地方，我都通过统一的db实例操作数据：

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

这段代码里藏着一个实战细节：开发环境热更新容易反复创建 PrismaClient，导致数据库连接数被打爆，所以用一个全局变量缓存它。等部署上线后，连接数管理又会有新的坑，后面第五部分我再展开讲。

2.3 tRPC 初始化与上下文设计：让每个请求都能拿到 db 和用户信息

tRPC 的核心是 context。每次请求进来，tRPC 都会调用createTRPCContext，我会用它把数据库实例和请求头里可能携带的会话信息塞进上下文，这样后面所有 procedure 都能通过ctx.db访问数据：

// src/server/api/trpc.ts import { initTRPC, TRPCError } from "@trpc/server"; import { db } from "~/server/db"; import { type Session } from "next-auth"; interface CreateContextOptions { session: Session | null; } export const createTRPCContext = async (opts: CreateContextOptions) => { return { db, session: opts.session, }; }; const t = initTRPC.context<typeof createTRPCContext>().create(); export const publicProcedure = t.procedure;

很多人第一次看到context<typeof createTRPCContext>会不太适应，说这不是多此一举吗？不是。这个泛型让 tRPC 知道上下文里挂着什么，后续所有 procedure 的类型推导都会基于它。比如在 router 里写ctx.db.post.findMany()，如果代码提示找不到db属性，那一定是 context 定义出了问题，而不是业务代码的问题。

接着我会把所有路由挂到根 router 上，再导出AppRouter类型：

// src/server/api/root.ts import { postRouter } from "~/server/api/routers/post"; import { userRouter } from "~/server/api/routers/user"; import { createTRPCRouter } from "~/server/api/trpc"; export const appRouter = createTRPCRouter({ post: postRouter, user: userRouter, }); export type AppRouter = typeof appRouter;

客户端入口就是一行createTRPCReact，把AppRouter作为类型参数传入：

// src/app/_trpc/client.ts "use client"; import { createTRPCReact } from "@trpc/react-query"; import type { AppRouter } from "~/server/api/root"; export const api = createTRPCReact<AppRouter>();

到这里，“数据库 -> Prisma client -> tRPC context -> router -> 前端类型”这条链路就通了。你可能会问，这不是多绕了一层吗？其实正是这一层，让后端函数在浏览器里的调用像本地函数一样，自动携带完整类型信息。

3. 让 tRPC 在页面里真正好用：我自己踩过的几个坑

骨架搭完不等于能用。我在开发过程中至少踩了三类坑，每类都值得写出来，因为它们都不是“写错一个单词”这种低级错误，而是对 tRPC 设计意图理解不到位导致的。

3.1 第一个坑：客户端组件的类型不生效，server-only 代码被误打包

现象很典型：我在一个"use client"的组件里写api.post.list.useQuery()，编辑器里api是能点出来的，但.post、.list就是没有类型提示，甚至直接报错。更诡异的是，浏览器控制台看到一份警告，说某个 server-only 模块被打包进了客户端。

排查过程大概是这样的：t3code 的src/app/_trpc/client.ts里我一开始直接写了import { appRouter } from "~/server/api/root";，然后 node_modules 里提示@prisma/client不属于浏览器环境。问题就出在这里——客户端需要的是AppRouter的类型，而不是 router 的实现。TypeScript 里的import type会被擦除，但如果你用了普通import，哪怕没直接调用，打包工具也可能把实现带进去。

正确写法是：

// src/app/_trpc/client.ts "use client"; import { createTRPCReact } from "@trpc/react-query"; import type { AppRouter } from "~/server/api/root"; export const api = createTRPCReact<AppRouter>();

重点是import type。这是 tRPC 官方文档反复强调的细节，但实际开发里真的很容易顺手写错。写错的代价不只是类型失效，更严重的是把 Prisma Client 这种 Node 端依赖塞进浏览器 bundle，构建体积暴涨。

3.2 第二个坑：受保护路由的中间件漏了 return next()

博客站需要一个只有登录用户才能创建文章的接口，我写了一个protectedProcedure：

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

看起来没问题是吧？但第一次测试时，未登录用户调用protectedProcedure.mutation，不仅没被拦截，还在后续代码里因为拿不到user报了个奇怪的空指针。

排查到最后发现：中间件里漏了return。tRPC 的中间件必须把next()的返回值返回出去，因为这一步是为了把新的 context 传给后续链路。我那段next({ ctx: { ...ctx, user: ... } })执行了，但返回值被丢弃，外层拿到的还是不带user的 ctx。更严重的后果是，如果next()内部执行过程中抛了错，这个错误也可能被吞掉。

正确写法：

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

说真的，这种错误在函数式中间件里太容易犯了。它不像是类型不匹配那样会被编译器拦截，而是属于“写错了也编译得过去，运行时才炸”的类型。所以后来我在团队里养成了一个习惯：所有 tRPC 和 Express 中间件，第一眼看的就是有没有return next()。

3.3 第三个坑：SSR 请求报错但客户端看不到有效信息

t3code 一部分页面是服务端渲染的，比如文章列表页。某个晚上我部署完，用户访问首页直接 500，但我在浏览器控制台里看到的还是Error: Internal Server Error，一点堆栈都没有。

排查链路比较长，我说关键的三步：

第一，确认服务端有没有把 tRPC 的错误格式化。我最初直接用默认错误格式，导致客户端收到的错误信息非常薄。后面在trpc.ts里加了自己的errorFormatter，把 Zod 校验错误和业务错误转成更友好的结构：

export const t = initTRPC.context<typeof createTRPCContext>().create({ errorFormatter({ shape, error }) { return { ...shape, message: error.code === "BAD_USER_INPUT" ? "参数不合法，请检查输入" : error.message, }; }, });

第二，SSR 场景下要注意 tRPC 的httpBatchLink会不会把多个请求合并后，导致某个请求的错误吞掉另外一个。我遇到的 500 是数据库查询超时，但客户端看到的是合并后的 500，所以得把服务端日志和 query key 对应起来看。

第三，我在 Next.js 的error.tsx里做一个兜底，把错误边界做好，而不是让整个页面白屏。这一点在内容型站点里尤其重要，一个文章接口挂了，至少不该让整站导航都不可用。

这三步做完之后，错误信息从“无意义 500”变成了“能定位到是哪个 query 挂了、挂在哪一层”。排查体验才算正常。

3.4 一张排查表，省去下次百分之八十的定位时间

踩坑踩多了之后，我把最容易犯的问题整理成了一张表，放在 t3code 的 README 里。这里分享出来：

这张表的思路其实是通用的：先判断问题是“类型层、运行时、还是打包层”，再各自排查。tRPC 的问题绝大多数逃不出这三个层面。

4. 页面数据流与内容体验：Server Components 为主，客户端查询为辅

骨架和坑都解决后，重点回到页面怎么写。t3code 的页面数据流我给自己的原则是：能用服务器组件拿数据，就不轻易上客户端请求；只有交互频繁的地方，才走 tRPC 客户端 Hook。

4.1 Server Components 里直接调用 tRPC，省一轮请求

App Router 下的 Server Components 最大的好处是，它能在服务端直接拿到数据库数据，不需要浏览器发请求。t3code 的文章列表页就是这么写的：

// app/(main)/posts/page.tsx import { createCaller } from "~/server/api/root"; import { headers } from "next/headers"; export default async function PostsPage() { // 注意：Next.js 15 里 headers() 是 async 的， // 如果你还在 Next.js 14，直接调 headers() 就行，不用 await。 const headerList = await headers(); const caller = createCaller({ session: null, headers: headerList, }); const posts = await caller.post.list({ publishedOnly: true }); return ( <div className="mx-auto max-w-3xl px-4 py-10"> {posts.map((post) => ( <article key={post.id} className="mb-8 rounded-lg border p-6"> <h2 className="text-xl font-bold">{post.title}</h2> <p className="mt-2 text-slate-600">{post.excerpt}</p> </article> ))} </div> ); }

这里有个很多人没意识到的好处：createCaller直接在服务端执行路由函数，不经过 HTTP。也就是说，它的性能和一个普通函数调用没有差别，少了网络往返，也少了序列化和反序列化的开销。而且因为整个调用发生在服务端渲染阶段，数据在返回浏览器之前就已经是 HTML 的一部分，首屏体验和 SEO 都照顾到了。

不过提醒一句，createCaller和真实 HTTP 请求在 context 上有细微差异。如果你的中间件依赖 header 里的 cookie 去解析 session，一定要像上面那样把headers传进去，否则登录态在服务端调用里是拿不到的。

4.2 客户端交互组件用 useQuery 处理状态，别自己维护 loading

文章详情页的点赞按钮，肯定不能走 Server Components 里的createCaller，因为点击是浏览器事件。这时就该让 tRPC React Query 接管：

"use client"; import { api } from "~/app/_trpc/client"; export function LikeButton({ postId }: { postId: string }) { const utils = api.useUtils(); const likeMutation = api.post.like.useMutation({ onSuccess: () => { utils.post.bySlug.invalidate(); }, }); return ( <button onClick={() => likeMutation.mutate({ postId })} className="rounded-full bg-slate-900 px-4 py-2 text-white" > 点赞 </button> ); }

注意两件事：

一是useMutation成功后一定要invalidate对应的查询 key。React Query 的失效机制能自动让相关查询重新拉取，不需要手动刷新页面。t3code 里文章浏览量、点赞数都是靠这个模式更新的。

二是状态处理。React Query v5 里，查询状态是isPending、isSuccess、isError这些字段。t3code 里列表页的加载状态我们从不手动写useState，一个post.listQuery.isLoading就解决了。如果你还在用 v4 的isLoading，升级到 v5 之后记得改掉，因为语义不同。

4.3 markdown 渲染和 Tailwind 排版：别在样式上重造轮子

博客站最核心的内容是 markdown 文章。t3code 我在服务端把 markdown 编译成 HTML，再配上@tailwindcss/typography插件渲染。安装和配置都很简单：

npm install -D @tailwindcss/typography

然后在tailwind.config.ts里挂载插件：

import type { Config } from "tailwindcss"; import typography from "@tailwindcss/typography"; export default { content: ["./src/**/*.{ts,tsx}"], plugins: [typography], } satisfies Config;

文章正文的 HTML 直接扔进prose类里，Tailwind 会把它排版成一套可读性很强的文章样式，连代码块、引用、列表的间距都帮你调好了：

<article className="prose prose-slate dark:prose-invert max-w-none" dangerouslySetInnerHTML={{ __html: post.contentHtml }} />

这里我想多说两句：如果你不是对排版有极其特殊的要求，真的别自己手写 markdown 样式。我一开始觉得prose类太模板化，非要自己定一套标题字号、行距、代码块背景，结果花了两天调出的效果还不如默认的prose看着舒服。后来干脆全站统一用prose，只在局部用 Tailwind 类覆盖暗色模式下的代码块样式。内容型站点，排版默认好看就是最大的性价比。

5. 部署与性能观察：构建、缓存和数据库连接的真实局面

功能都跑通之后，自然要部署上线。这一部分没有太多风花雪月，基本都是构建、缓存、连接池这些底层问题。我把 t3code 部署到服务端渲染环境（Vercel 风格）后，观察到的几个点值得分享。

5.1 客户端包体积：tRPC server 绝不能进浏览器 bundle

前面踩坑时已经提过import type的重要性。部署时更要加一道保险：在服务端模块里加上import "server-only"。这是 Next.js 生态里的一个安全标记包，一旦有人意外把服务端模块引到客户端，编译时会直接报错，而不是等到运行时才炸。

// src/server/db.ts import "server-only"; import { PrismaClient } from "@prisma/client"; // ...

有了这层保护，构建产物的体积也干净了。t3code 首次部署后我看了下客户端 bundle，最大的依赖来自 React Query 和 tRPC 客户端，Prisma、Node 的工具类完全没有进入浏览器。这个结果我是满意的，说明工程边界真正立住了。

5.2 页面缓存策略：别把所有页面都做成动态渲染

文章列表、详情这类页面，数据变化频率远低于用户请求频率。全站用动态渲染，数据库压力会白白升高。t3code 的做法是把不依赖登录态的页面标记为静态生成或 ISR：

// app/(main)/posts/[slug]/page.tsx export const revalidate = 60; // 每 60 秒后台重新生成一次 export default async function PostPage({ params, }: { params: { slug: string }; }) { // ... }

这样部署后，页面在第一次构建时生成静态 HTML，后续请求默认走缓存，每 60 秒后台触发一次重新生成。浏览量计数这种实时性要求不高的数据，也走 ISR 就够。

需要强调的是，涉及用户态、权限的页面千万别用revalidate，否则可能出现“A 登录后看到的页面被 B 的缓存命中”这种脏数据。t3code 里管理员后台全部标成动态渲染，不加缓存。

5.3 Prisma 连接池与 DATABASE_URL、directUrl 的处理

服务端渲染平台容易遇到一个痛点：函数实例会频繁冷启动，每个实例都会创建数据库连接。Prisma 默认使用连接池，但部署环境往往有连接数上限。t3code 的数据库是托管 PostgreSQL，我采用了两段式连接配置：

DATABASE_URL="postgresql://user:password@host:5432/dbname?connection_limit=5" DIRECT_URL="postgresql://user:password@host:5432/dbname"

DATABASE_URL走连接池，用于常规查询；DIRECT_URL用于需要直连的场景，比如 Prisma Migrate。设置一个合理的connection_limit很重要，默认连接数可能超出数据库实例的限制。我自己的设置为 5，对小型内容站来说足够，也留了并发余量。

这里还有一个容易被忽略的点：连接池不是越高越好。连接数过多反而会让数据库实例把所有内存花在维护连接上，查询变慢。压测时我把连接池从默认调到 5，响应时间反而从 400ms 附近降到 200ms 附近，就是因为在环境配置里减少了排队和锁竞争。

5.4 一次粗略压测与我的结论

用autocannon对首页做了 100 并发、持续 30 秒的压测，结果大概如下：

这个结果我没怎么优化就已经不错了，因为大部分页面都被 ISR 缓存成了静态响应。压测后我做了一件事：把“浏览量 +1”这个接口从同步 Mutation 改成数据库异步更新 + 本地乐观更新，这样用户即使快速刷新页面，也不会因为写操作把请求链路拖慢。

这个部分我想给的建议很朴素：性能优化之前，先让静态缓存扛掉 90% 的流量，再回来优化动态部分。tRPC 在动态交互上很方便，但在高并发页面渲染上，它不该是首选方案——该缓存就缓存，改静态就静态，类型安全不是阻碍缓存策略的理由。

最后说点个人体会。t3code 做完之后，我对“类型安全全链路”的理解变了不少。它最舒服的地方不在于少写了几个接口类型，而在于把前后端之间的“默契”变成了编译器能检查的约束。每次改动 Prisma schema，跑一次迁移，所有依赖这个模型的页面和接口会立刻被类型系统标出来，这种“改一处、全盘知晓”的感觉，是手写接口文档给不了的。而最贵的地方也很明显：tRPC 让前后端紧紧耦合在一起，如果你是做开放 API 或者要服务多个独立客户端，它未必合适。所以 t3code 的定位非常明确，它就是我这种“一个人同时写前端和后端”的项目形态的解法。如果你的项目也是这个形态，真的可以试试这套组合。