前几个月，我把手头所有零散的小项目统一收敛成一个代号，就叫 t3code。这个代号没什么玄学，就是 T3 Stack 里三个 T 的组合：TypeScript、Tailwind CSS、tRPC，再加上 Next.js 当骨架。我用它做了一个个人代码片段管理工具，把收藏、标签、搜索这些功能全塞进去，顺带把前后端类型不一致的老毛病一次性解决掉。这篇文章把从选型到落地的完整过程记一遍，重点写为什么这么选、具体参数怎么配、以及哪些坑是官方文档里看不到的。如果你刚想接触 T3 技术栈，或者打算拿这套组合做内部工具和个人项目，这篇可以直接当路线图看。
1. 从项目代号重新认识 T3 Stack 的技术取向
1.1 t3code 到底在解决什么问题
t3code 不是某个新框架，它是我对自己项目技术栈的一种收敛。底层核心是 Next.js，负责页面路由、SSR、SSG；TypeScript 定义整个项目的类型纪律；Tailwind CSS 处理样式；tRPC 解决客户端到服务端的 API 调用；Prisma 管理数据库访问；NextAuth 处理登录。这一套组合下来，你会发现一个特点：每个环节都在为"类型安全"服务。
我过去做个人项目最头疼的不是功能写不出来，而是写接口的时候前后端各维护一份类型定义，前端改了一个字段，后端没跟上，接口直接崩。t3code 这个项目里，这种问题从根上被消灭了。tRPC 可以在不写 REST 路由、不写 Swagger 文档的前提下，让前端直接拿到后端的函数和类型，改一处，另一处马上编译报错。
另一个隐藏价值是维护成本。个人项目经常写完就扔，三个月后再回来改需求，连自己都不记得接口长什么样。T3 Stack 把所有 API 集中到 router 里，数据模型又跟 Prisma schema 绑定，看一眼 schema 就能想起来全貌。这种"代码即文档"的特性，对我这种习惯一个人维护多个小项目的人来说，价值比团队协作场景还要大。
1.2 为什么不用 REST API 或 GraphQL
我在技术选型时不是没想过 REST。REST API 当然成熟，但它的类型问题是结构性的：你写一个GET /api/snippets，后端返回的数据要和前端对齐，只能靠手动维护 interface 或者生成 openapi-typescript 这类工具。分清 controller、service、router 这几个层，每层都要过一遍类型，一个接口前后端加模板代码轻松上百行。
GraphQL 我也研究过，它的类型系统是强，但需要引入 schema 定义、解析器、codegen 流程，对一个小项目来说，工具链太重了。尤其是自己一个人开发的场景，GraphQL 的灵活查询能力其实是过剩的，而它带来的 schema 维护成本是实打实的。
对比之下，tRPC 的思路很像直接在 TS 里调用函数。后端定义一个 procedure，前端通过 hooks 拿到同名函数调用，所有入参出参类型都由编译器推断，根本不需要定义第二份类型。拿一个常见的"创建代码片段"接口举例：REST 要写 handler、DTO、校验、client 封装，tRPC 只需要在 router 里写一个 mutation，前端直接调用，Zod 负责校验。能少写大概一半样板代码。
1.3 create-t3-app 脚手架的取舍逻辑
t3code 的初始化并没有我手动搭，而是用了官方脚手架 create-t3-app。这个脚手架不是简单的代码生成器，它更像一个"决策收敛器"：你一上来就需要做一轮技术栈取舍，选完它再帮你把目录、依赖、基础配置全部铺好。
脚手架默认启用 TypeScript 的 strict 模式、ESLint、Prettier，这一点看着不起眼，实际作用很大。很多项目最后类型混乱，就是因为没开 strict，各种 implicit any 混过去。脚手架强制帮你把纪律立住，后面维护少掉很多头发。
不过它也替你做了一些我认为非常合理的默认选择：比如默认使用 App Router，默认把 tRPC 和 NextAuth 接好，默认把 Prisma client 实例化并注入上下文。这些代码新手自己拼，最容易拼错的是各种类型泛型、上下文注入、Cookie 传递。脚手架把这些"拼接胶水"提前做好，你只需要往 router 里填业务逻辑。
2. t3code 快速搭建流程与原理解读
2.1 初始化命令与选项
创建 t3code 项目只需要一条命令，官方现在默认用 create-t3-app 的最新版本：
npm create t3-app@latest命令跑起来之后，脚手架会进入交互式选择流程。我当时的实际选项如下：
- 项目名称：输入
t3code - TypeScript / JavaScript：选 TypeScript
- Tailwind CSS：启用
- tRPC：启用
- Prisma：启用
- NextAuth.js：启用
- App Router：是
- 导入别名：
~前缀，保持默认
这套组合选完，脚手架会把 Next.js 项目目录、Tailwind 配置、tRPC 初始化代码、Prisma schema、NextAuth 基础配置全部生成好。我当时没选 Drizzle 而是选了 Prisma，主要是个人经验里 Prisma migrate 流程更顺手，而且它的类型生成跟 tRPC 配合得很自然。
2.2 目录结构与数据流
初始化完成后，t3code 的目录结构里最需要看懂的是这几块：
src/ app/ api/trpc/[trpc]/route.ts layout.tsx page.tsx server/ api/ root.ts routers/ snippet.ts post.ts trpc.ts auth.ts db.ts trpc/ react.tsx server.ts utils/ api.ts prisma/ schema.prismasrc/server/api/trpc.ts是核心工厂，它创建 tRPC 的 router 和 procedure，同时把 Prisma client 和当前会话注入到 context 里。src/server/api/root.ts把所有子 router 合并成 appRouter。src/trpc/react.tsx负责创建 React Query 的 client 和 Provider，src/utils/api.ts是你前端调用 API 的唯一入口。
数据流大致是这样：前端页面 importapi，调用api.snippet.getAll.useQuery()，请求会通过 tRPC HTTP Handler 进入/api/trpc/[trpc]这条路由，然后由 tRPC 解析到对应的 router 方法，方法内部通过ctx.db访问 Prisma，查完数据库把结果原路返回。整个过程没有手写 fetch 地址，也没有定义 interface，类型全程自动流动。
2.3 数据模型设计与 Prisma 初始化
t3code 的核心功能是管理代码片段，所以我的 Prisma 模型分成三张表：用户、片段、标签。用户和 NextAuth 直接关联，片段属于某个用户，标签跟片段是多对多关系。
model User { id String @id @default(cuid()) name String? email String? @unique snippets Snippet[] } model Snippet { id String @id @default(cuid()) title String content String @db.Text language String createdAt DateTime @default(now()) updatedAt DateTime @updatedAt author User @relation(fields: [authorId], references: [id]) authorId String tags Tag[] } model Tag { id String @id @default(cuid()) name String snippets Snippet[] }写下 schema 之后，执行：
npx prisma migrate dev --name init这一步会创建数据库表并生成 Prisma Client。migrate 看似简单，但它背后做的事很多：diff 出 SQL 变更、创建迁移文件、应用迁移、重新生成 client。我的习惯是每改一次 schema 就迁一次，尽量让迁移文件跟代码提交保持同步，这样部署的时候可以直接prisma migrate deploy。
3. t3code 里类型安全怎么贯穿三层
3.1 tRPC Router 与 Zod 校验
t3code 里的业务逻辑大部分写在 router 文件中。拿代码片段列表接口为例，它做了两件事：限制只能查自己的数据，支持按标签过滤和关键词搜索。
// src/server/api/routers/snippet.ts import { z } from "zod"; import { createTRPCRouter, protectedProcedure } from "~/server/api/trpc"; export const snippetRouter = createTRPCRouter({ getAll: protectedProcedure .input( z.object({ tag: z.string().optional(), query: z.string().optional(), }) ) .query(async ({ ctx, input }) => { return ctx.db.snippet.findMany({ where: { authorId: ctx.session.user.id, ...(input.tag ? { tags: { some: { name: input.tag, }, }, } : {}), ...(input.query ? { OR: [ { title: { contains: input.query, mode: "insensitive" } }, { content: { contains: input.query, mode: "insensitive" } }, ], } : {}), }, include: { tags: true }, orderBy: { createdAt: "desc" }, }); }), });这里protectedProcedure会先检查 session，没登录直接抛错。如果用 REST 思路，这个校验要在中间件或业务代码里重复写；但 tRPC 把鉴权变成一个 procedure 的修饰器，哪个接口需要登录就挂哪个，不需要登录的用publicProcedure。Zod 负责运行时校验，前端传一个不合法类型进来，不用等业务逻辑跑起来，入口直接拦截。
3.2 前端 useQuery 的零成本类型调用
前端调用时不需要知道后端路由地址，直接 import 同一个 api：
// src/app/tags/[tag]/page.tsx "use client"; import { api } from "~/utils/api"; import { useParams } from "next/navigation"; export default function TagPage() { const params = useParams<{ tag: string }>(); const { data, isLoading, refetch } = api.snippet.getAll.useQuery({ tag: params.tag, }); if (isLoading) return <p>加载中...</p>; return ( <div> {data?.map((snippet) => ( <pre key={snippet.id}>{snippet.content}</pre> ))} </div> ); }这段代码有个很有意思的点：api.snippet.getAll这个链式调用是从后端 router 自动推导出来的。如果后端把返回值里的content字段改名了，这边访问snippet.content会直接编译报错。不需要跑服务、不需要联调、不需要 mock 数据，类型错误在开发阶段就被按住了。
tRPC 还内置了 TanStack Query，所以缓存、重试、刷新这些能力是开箱即用的。我写创建片段的 mutation 时，就用到了它的失效刷新机制：
const createSnippet = api.snippet.create.useMutation({ onSuccess: () => { apiUtils.snippet.getAll.invalidate(); }, });invalidate 之后，列表自动重新请求，我不会手动去维护全局 store。这是 T3 组合拳里很舒服的一点：类型出错了编译器先告诉你，数据过期了 React Query 帮你处理，而我只需要关心业务逻辑。
3.3 Tailwind 在 t3code 里的实际配置
样式部分，t3code 用了 Tailwind CSS。脚手架默认生成 tailwind.config.ts 和全局 CSS 文件。我给代码片段卡片设计了很简单但实用的样式布局：
<article className="rounded-lg border border-neutral-200 bg-white p-4 shadow-sm hover:shadow-md transition-shadow"> <h3 className="font-medium text-neutral-900">{snippet.title}</h3> <pre className="mt-2 overflow-x-auto rounded-md bg-neutral-50 p-4 text-sm text-neutral-800"> {snippet.content} </pre> </article>这里我刻意用 utility class 而不是写一堆 CSS 文件。个人项目里我最怕样式文件分散、命名冲突，Tailwind 的原子类让我在改样式时不用跳文件，维护成本低很多。如果你愿意，还可以在此基础上用 shadcn/ui 之类的组件库，但我的建议是先把原子类和响应式布局练熟，再考虑上组件来兜底，不然很容易陷入"改样式必须翻组件源码"的窘境。
4. 实操中的常见问题与排查实录
4.1 Prisma 连接池在开发环境的坑
开发 t3code 时我遇到的第一个坑来自 Prisma 和 Next.js 的配合。Next.js 开发模式会频繁重新编译，每次热更新都可能尝试创建新的 PrismaClient 实例，积累到数据库连接数上限，日志里会出现Too many connections。
解决方法是官方推荐的全局实例缓存模式：
// 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", "warn"], }); if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = db;这个模式把 PrismaClient 挂到 globalThis 上，开发环境不会重复创建实例。第二个连接池相关的因素是数据库本身的连接数限制。我用的是 PostgreSQL，默认 max connections 是 100，serverless 环境里每个请求都可能占用连接，所以我在部署环境里把连接池上限调低，并且设置了较短的 connect_timeout。建议尽快把 pool 参数写进 DATABASE_URL 的连接串里。
4.2 tRPC 与 NextAuth 会话的边界问题
一开始我在 t3code 里给所有页面都加了 Next.js 中间件，希望通过 middleware 统一拦截未登录请求。实测下来发现问题：middleware 只在路由层判断，并不了解数据库里的真实会话状态；而 NextAuth 的 JWT 会话在中间件里能拿到，但在某些边缘场景下会跟页面内 session 状态不一致。
我的最终用法是分层处理：middleware 只负责前置兜底跳转，真正的数据级保护交给 tRPC 的protectedProcedure。比如删除片段的那个 mutation，如果只依赖前端按钮显隐，那通过 API 直接调还是能删数据。挂上保护 procedure 以后，后端每个入口都会检查 session，这才是最终防线。
如果你的 t3code 需要在服务端组件里获取 session，我建议手动读取 Cookie 然后传给服务端调用器。tRPC 的 server caller 支持传入包含 Cookie 的请求头，不然服务端渲染时拿不到当前用户身份。
4.3 部署到 Vercel 时容易踩的坑
t3code 部署用的是 Vercel，整体体验很顺，但有几个点必须先处理。第一，数据库不能用 SQLite。Vercel Serverless 函数的文件系统是临时的，任何本地写入都会丢失，必须换成托管 PostgreSQL。我选了 Neon 和 Supabase 这一类的云数据库，连接串直接填到DATABASE_URL。
第二，迁移命令要用migrate deploy，而不是migrate dev。在本地开发时migrate dev会生成新的迁移文件；部署环境里直接执行prisma migrate deploy，按已有迁移文件顺序建表，不触发交互。
第三，环境变量容易漏配置。t3code 至少需要三个关键变量：DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL。NEXTAUTH_SECRET如果忘了设，生产环境登录会直接报错，而且错误信息不容易一眼看出原因。部署前我建议先在本地 build 一次，把类型检查、Prisma generate、环境变量引用问题全部暴露出来，再推 Vercel。
4.4 给新手的避坑清单
这一节是我自己重构 t3code 过程中总结出的经验，不一定适合所有团队，但对单人或少量开发者特别适用。
第一，不要过早抽象数据访问层。很多从企业项目转过来的朋友一上来就在 Prisma 外面包 repository 和 service。T3 的官方风格是直接在 router 方法里写 Prisma 查询，这对大多数业务场景已经够用了。等真出现多端复用或者复杂事务，再考虑抽层，不要提前给代码加杠杆。
第二，不要自己封装一个"统一返回结构"。习惯写{ code, data, message }的人会下意识想给 tRPC 套一层。这个做法会直接废掉 tRPC 的类型推导，因为前端拿到的不再是精准的数据类型，而是一个包装壳。tRPC 的错误处理原生支持 throwing，你不需要再发明一种错误格式。
第三，Zod schema 尽量放在离 router 近的位置。有时候客户端也会用到同一个 schema，直接导出后在页面里 import 即可，不要专门维护一个巨大的 schema 目录，那样反而增加跳转成本。
第四，注意 tRPC 的 query key 设计。当你传多个筛选条件时，React Query 会根据 input 自动生成 key。我一开始担心它会缓存混串，实测没有这问题，只要服务端按条件查询，前端invalidate 就会刷新。别动用手动 key 去干扰它，天然机制已经够用。
第五，Tailwind 样式如果越写越乱，先检查是不是组件拆得太碎。我在 t3code 里把代码片段卡片、标签、编辑器拆成独立组件之后，样式冲突就基本消失了。原子类本身不难，难的是决定每段 UI 的边界。
这个项目跑起来大概两周，后面我基本不用再花时间维护类型定义和接口文档。真正花时间的反而是数据模型设计和搜索条件梳理。T3 这套组合把我的问题从"前后端类型不一致"转移到了"业务逻辑本身"，这是它最让我舒服的地方。如果你也打算拿它做自己的工具站点，我的建议是先画几版最丑的草图，把核心表和交互定下来，然后让 tRPC 直接驱动页面。抽象层、接口文档、额外状态管理这些，能晚一点加就晚一点加。
