T3技术栈实战：用tRPC+Prisma打造代码片段管理工具

如果你常刷全栈圈，对“T3”这个词应该不陌生——Next.js、TypeScript、Tailwind 和 tRPC 的组合拳。t3code 这个项目，名字里就写了一半答案：T3 技术栈 + code 管理。简单说，这是一个用 T3 全家桶搭建的个人代码片段管理工具，用来解决我日常开发里最烦的一个问题：代码片段散落各处，真到要用的时候找不到。

这个项目麻雀虽小，但五脏俱全：GitHub 登录、数据库建模、服务端接口、前端页面、部署上线全走了一遍。它是全栈新手快速理解 T3 技术栈如何端到端打通的最佳示例，也是老手用于沉淀内部小工具的高效模板。下面我把整个从零到跑通的过程，包括选型逻辑、目录结构、核心实现和踩坑记录都拆开讲。

1. t3code 是个什么项目：需求与定位

1.1 一个非常具体的痛点：代码片段去哪了

很多项目做不起来，不是技术不行，是需求太虚。t3code 这个项目恰恰相反，需求是我自己实实在在踩过的坑。

我的日常开发横跨好几个仓库，再加上临时排查问题时写的调试脚本，代码片段分散得很厉害。浏览器收藏夹存一段、公司 Wiki 贴一段、本地笔记塞一段，真要找的时候一片混乱。比如某种特定格式的正则、一段处理时区的 SQL、一份 Docker Compose 模板，三个月后回头找，至少要翻十来分钟历史记录。这个频率一高，人就烦了。

所以 t3code 的目标很朴素：一个自己能随时访问的代码片段仓库。支持登录、增删改查、按语言和标题过滤，最好还能用 Markdown 加一些使用说明。这个需求用商业产品也能解决，但我有自己的坚持——不想把内部代码片段放到第三方平台，也不希望数据被格式化和广告绑架。自己做一个自托管的版本，一劳永逸。

1.2 为什么要做成一个“全栈应用”而不是脚本

第一反应可能是：存个代码片段而已，写个 Node 脚本加 JSON 文件不就行了？

我一开始也这么想，但很快就放弃了。因为代码片段不是写完就完的静态数据，它有高频的检索、更新、删除需求，还要区分私有和公共展示。纯文件方案在单机条件下可以，一旦想多设备访问、想支持多人协作或者团队内部共享，就得补大量的同步逻辑，最终还是要被迫写一套 Web 应用。

选择全栈应用还意味着可以顺便验证一个我一直想确认的技术问题：T3 这套组合到底能不能在一个周末内支撑起完整的 CRUD + 认证 + 部署闭环。事实证明确实能，而且过程比传统前后端分离方案清爽太多。

1.3 项目边界：哪些功能做了，哪些故意不做

做一个项目最怕的就是无限加需求。t3code 第一版的功能列表我很克制：

• GitHub OAuth 登录，免密进入
• 代码片段的创建、编辑、删除、列表查看
• 按编程语言和标题关键字过滤
• Markdown 格式的备注说明，支持预览
• 私有片段只对自己可见

故意没做的也列一下：团队协作、公共广场、富文本编辑器、AI 代码总结。这些听起来很香，但每一项都会极大拉长工期。个人工具的核心价值是聚焦，先把主链路跑通，后续真要扩展再往上叠。

2. 技术选型：为什么是这四个组件而不是其他组合

2.1 核心矛盾：API 层的重复代码到底怎么消掉

最开始我也考虑过传统方案：Next.js 只当展示层，后端单独起一个 Express 或 Fastify 服务，两边通过 REST 接口通信。这种模式成熟，但有个绕不开的问题——类型定义要维护两份。前端一份，后端一份，API 文档又是一份，改一个字段要同步改三处，漏一处就是运行时才暴露的 bug。

tRPC 解决的就是这个核心矛盾：让前端直接调用后端函数，类型从服务端自动推导到客户端。后端 Router 里定义好的create、list、delete，前端引进来就是类型完整的方法。接口层的事实来源只有一个：Router 定义本身。

我当时做过一个直观对比，这也是我最终确定技术路线的参考依据：

如果你做的是开放平台、需要大量外部客户端接入的 B 端 API，REST + OpenAPI 依然是更稳妥的选择。但 t3code 定位是内部工具，tRPC 的优势完美贴合。

2.2 数据库层：Prisma 让表结构成为编译期事实

数据库选型没有悬念，就是 Prisma。真正让我下决心的不是 ORM 本身的便利，而是它把数据库结构变成了“单一事实来源”。

在 Prisma 里，prisma/schema.prisma一个文件描述了所有表结构、字段类型、关联关系。改了 schema 之后执行npx prisma migrate dev，它会生成对应的 SQL 迁移文件，同时重新生成类型安全的客户端。写代码的时候，ctx.db.snippet.findMany()的返回值类型是完全可推导的，字段写错了 IDE 直接标红，根本轮不到运行时再炸。

这一点对个人项目的意义很大——没有专职 DBA，也没有专门的联调环境，越早暴露错误越好。编译期能发现的问题，绝不让它拖到部署后。

2.3 认证选型：为什么直接用 NextAuth 而不是自己写 Session

很多教程喜欢教你手写 JWT、Redis Session，看起来高深，实际项目里纯属自找麻烦。t3code 选择 NextAuth.js，核心原因是它把这套链路整个包好了：OAuth 登录、Session 管理、CSRF 防护、Callback 转发都是开箱即用的。

GitHub OAuth 是我们最顺手的登录方式。程序员群体基本人手一个 GitHub 账号，授权登录点一下就结束，用户价值很高，也省去了邮箱注册、密码找回这一整套复杂度。

2.4 样式与客户端状态：能省则省

样式上 Tailwind CSS 是 T3 标准配置，原因很实际——内部工具的页面通常不追求视觉效果，但要求快速迭代。Tailwind 的原子类方式让我不用在 CSS 文件里反复切来切去，直接改 className 就能调样式。

客户端状态管理没有额外引入 Redux 或 Zustand。tRPC 底层自带 TanStack Query，服务端数据天然有缓存、失效、重试机制。局部 UI 状态（比如弹窗开关）直接 useState 就够了。少一个依赖就少一个心智负担，这是个人项目的生存法则。

3. 从 create-t3-app 到能跑的骨架：初始化全过程

3.1 初始化命令与交互选项

T3 技术栈的官方脚手架是 create-t3-app，它会自动生成一个包含所有核心约定的基础工程。初始化命令很简单：

npm create t3-app@latest t3code cd t3code npm install

执行时它会用交互式问答确认要启用哪些能力。我建议你这样选：

• App Router：选 Yes，这是 Next.js 目前的主推方向
• TypeScript：选 Yes，不用犹豫
• Tailwind CSS：选 Yes，配合样式处理
• tRPC：选 Yes，本项目的核心
• Prisma：选 Yes，数据库层需要它
• NextAuth.js：选 Yes，登录认证离不开它
• ESLint：选 Yes，保持代码规范性

Prettier 项看个人偏好，我一般也会带上，省得格式化问题引发无意义的代码争执。

脚手架生成的项目不是一个空 Hello World，而是一个已经跑通 tRPC 回合、NextAuth 回调和数据库连接的完整骨架。这对新手极其友好：你有一条已知可用的基线，再往上叠业务逻辑，出问题时知道是自己引入的，不是环境问题。

3.2 生成后的目录结构逐层拆解

初始化完成后，目录结构大致长这样。我挑几个关键路径解释，理解了它们，后面写业务就很顺：

t3code/ ├─ prisma/ │ └─ schema.prisma # 所有数据模型和数据库连接配置 ├─ src/ │ ├─ app/ │ │ ├─ api/ │ │ │ ├─ trpc/[trpc]/route.ts # tRPC HTTP 入口 │ │ │ └─ auth/[...nextauth]/route.ts # NextAuth 路由入口 │ │ ├─ _trpc/ │ │ │ ├─ client.ts # 前端 tRPC 客户端实例 │ │ │ └─ Provider.tsx # SessionProvider + tRPCProvider 包裹 │ │ └─ layout.tsx │ ├─ server/ │ │ ├─ api/ │ │ │ ├─ routers/ # 业务 Router，按模块拆分 │ │ │ ├─ root.ts # 聚合所有业务 Router │ │ │ └─ trpc.ts # tRPC 服务端上下文和初始化逻辑 │ │ ├─ auth.ts # NextAuth 配置（providers、callbacks） │ │ └─ db.ts # Prisma Client 单例 │ ├─ trpc/ │ │ ├─ server.ts # 服务端 tRPC 封装（供 RSC 调用） │ │ └─ react.tsx # 前端 React 封装（供组件调用） │ └─ env.js # 环境变量校验 ├─ .env # 本地环境变量 └─ next.config.js

这个结构最大的特点是职责分明：server目录里全是后端逻辑，app目录里全是界面和路由，trpc目录是连接前后端的类型安全通道。新写一个功能模块时，你只需要新增一个 router 文件 + 一个页面组件，其他都是约定俗成的路径。

3.3 环境变量与校验逻辑

环境变量这个环节经常被轻视，直到部署后才开始折磨人。create-t3-app 默认通过@t3-oss/env-nextjs做运行时校验，配置写得很直观：

import { createEnv } from "@t3-oss/env-nextjs"; import { z } from "zod"; export const env = createEnv({ server: { DATABASE_URL: z.string().url(), NEXTAUTH_SECRET: z.string().min(1), NEXTAUTH_URL: z.string().url().optional(), GITHUB_CLIENT_ID: z.string().min(1), GITHUB_CLIENT_SECRET: z.string().min(1), }, runtimeEnv: { DATABASE_URL: process.env.DATABASE_URL, NEXTAUTH_SECRET: process.env.NEXTAUTH_SECRET, NEXTAUTH_URL: process.env.NEXTAUTH_URL, GITHUB_CLIENT_ID: process.env.GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET: process.env.GITHUB_CLIENT_SECRET, }, });

它的好处很直接：环境变量缺失时应用启动阶段就报错，而不是等到某个 API 被调用时才报一个莫名其妙的连接错误。我第一次配置时忘记填NEXTAUTH_SECRET，页面一打开立刻被拦截，省了很多排查时间。

本地开发时把DATABASE_URL指向 SQLite 文件即可，零成本起跑：

DATABASE_URL="file:./db.sqlite"

4. 核心功能链路：从 Prisma 表结构到 tRPC Router 再到页面

4.1 数据模型设计：先定表结构，后写业务

t3code 的数据模型很直接。除了 NextAuth 需要的User、Account、Session这些模型之外，业务核心是Snippet。我把它定义成下面这样：

model Snippet { id String @id @default(cuid()) title String content String language String @default("plaintext") isPublic Boolean @default(false) userId String user User @relation(fields: [userId], references: [id], onDelete: Cascade) createdAt DateTime @default(now()) updatedAt DateTime @updatedAt @@index([userId]) @@index([language]) }

几个细节说明一下。主键用的是cuid()而不是自增数字，因为自增 ID 会暴露用户量和插入顺序，cuid 没有这个顾虑，而且分布式环境下不需要中心协调。@@index([userId])是给外键加索引，否则随着 snippet 数量增长，按用户查询会逐渐变慢。onDelete: Cascade保证用户注销时关联数据一并清理。

定义好之后执行迁移命令，生成本地数据库：

npx prisma migrate dev --name init-snippet

这条命令会创建一个迁移记录，同时重新生成 Prisma Client。之后每次改 schema，流程都是先改文件，再执行迁移，保持表结构和代码模型一致。

4.2 服务端：tRPC Router 的编写思路

有了数据模型，接下来就是服务端接口层。在routers/snippet.ts里写业务 Router，核心代码大概是这样的：

import { z } from "zod"; import { createTRPCRouter, protectedProcedure } from "~/server/api/trpc"; export const snippetRouter = createTRPCRouter({ list: protectedProcedure .input( z .object({ language: z.string().optional(), keyword: z.string().optional(), }) .optional() ) .query(async ({ ctx, input }) => { return ctx.db.snippet.findMany({ where: { userId: ctx.session.user.id, ...(input?.language ? { language: input.language } : {}), ...(input?.keyword ? { title: { contains: input.keyword } } : {}), }, orderBy: { updatedAt: "desc" }, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1).max(100), content: z.string().min(1), language: z.string().default("plaintext"), isPublic: z.boolean().default(false), }) ) .mutation(async ({ ctx, input }) => { return ctx.db.snippet.create({ data: { ...input, userId: ctx.session.user.id, }, }); }), delete: protectedProcedure .input(z.object({ id: z.string() })) .mutation(async ({ ctx, input }) => { await ctx.db.snippet.deleteMany({ where: { id: input.id, userId: ctx.session.user.id, }, }); return { success: true }; }), });

注意三个点。第一，每个 Procedure 都用了protectedProcedure而不是publicProcedure，这意味着未登录用户会被直接拒绝。第二，输入参数全部用 zod 校验，前端传的字段在服务端会再次验证，不依赖前端的自觉。第三，delete操作我刻意用了deleteMany加userId条件，防止越权删掉别人的 snippet——这类安全问题在个人项目里也很重要，养好习惯成本很低。

写完 Router 之后，还要在root.ts里注册一下：

import { createTRPCRouter } from "~/server/api/trpc"; import { snippetRouter } from "~/server/api/routers/snippet"; export const appRouter = createTRPCRouter({ snippet: snippetRouter, }); export type AppRouter = typeof appRouter;

AppRouter这个类型是前后端共享的关键，前端所有类型推导都来源于它。

4.3 前端页面：类型贯通后的调用体验

前端组件里，tRPC 的调用体验接近于“直接的本地调用”。因为AppRouter类型已经推到了前端，api.snippet.list.useQuery()的返回值、参数、错误类型全部自动推导，不需要手写任何接口类型。

"use client"; import { api } from "~/trpc/react"; export function SnippetList() { const { data, isLoading } = api.snippet.list.useQuery(); if (isLoading) return <div>加载中...</div>; return ( <div className="space-y-4"> {data?.map((snippet) => ( <div key={snippet.id} className="rounded border p-4"> <div className="text-lg font-semibold">{snippet.title}</div> <pre className="mt-2 overflow-x-auto text-sm"> <code>{snippet.content}</code> </pre> </div> ))} </div> ); }

新增或删除数据后，需要让列表重新拉取。tRPC 底层是 TanStack Query，所以缓存失效也走它的标准模式：

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

invalidate会在操作成功后让相关 query 的缓存变 stale，下次渲染自动重新请求。整个过程不需要手动管理 loading 状态、不需要手写请求失败处理，代码量比传统 fetch 方案少了一半不止。

4.4 认证保护链路：从 OAuth 到 Session 再到 Router

前面用了protectedProcedure，很多人可能好奇它是怎么工作的。T3 默认模板给了标准实现：

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

这里的关键在于服务端上下文。每次 tRPC 请求进来，都会先调用createTRPCContext，它读取当前的 Session 信息挂到上下文里，后续所有 Procedure 可以通过ctx.session拿到用户身份。

换句话说，认证不是每个接口自己去判断的，而是收敛到中间件层。新写一个接口时，只要选对 Procedure 类型，认证规则就自动生效。这个抽象非常舒服，写业务的人不需要关心“这个接口要不要验证登录”这种重复问题。

5. 开发踩坑与调试实录

5.1 改了 Router 类型，前端死活不更新

这是 tRPC 开发里最容易撞上的坑。你明明在服务端 Router 里加了一个新查询，前端api.snippet.xxx却提示不存在，或者类型还是旧的。

原因是 Next.js 的 dev server 对.next目录里的类型缓存处理没有 tRPC 敏感。改了root.ts或 router 文件后，tRPC 的类型信息要经过 TS 编译再同步到前端，这一步经常会被增量编译缓存住。

解法很简单，按顺序试：

rm -rf .next npm run dev

清掉.next缓存后重新启动，类型一定是最新的。后来我养成习惯：改完 router 结构，先停 dev server 再重启，省得被怪异报错浪费十分钟。你要是遇到“代码看起来没问题但类型就是不对”，优先想到这个坑。

5.2 Prisma 客户端多实例警报

开发模式下，Next.js 的热更新会反复加载模块。如果 Prisma Client 在每次加载时都new一个实例，跑一段时间后终端会飘出经典报错：

Already 10 Prisma Clients are actively running

原因就是模块热更新生成了太多 PrismaClient 实例，而每个实例都占着数据库连接。解决方式是全局单例模式，create-t3-app 默认生成的server/db.ts也是这么处理的：

import { PrismaClient } from "@prisma/client"; const globalForPrisma = globalThis as unknown as { prisma: PrismaClient | undefined; }; export const db = globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV !== "production") { globalForPrisma.prisma = db; }

这段代码利用globalThis在模块热更新时保留同一个实例，生产环境每次冷启动也只建一次。个人项目可能不常遇到这个报错，但团队里多人开发时就很容易触发，先记住这个写法。

5.3 NextAuth 回调地址与 CSRF 的隐藏要求

集成 GitHub OAuth 时最磨人的不是代码，而是配置。你需要在 GitHub 的 OAuth Apps 设置里，把 Authorization callback URL 精确填成：

http://localhost:3000/api/auth/callback/github

漏掉/api/auth/callback/github这一截，或者域名用了127.0.0.1而不是localhost，登录时就会在 GitHub 那一跳之后回不来。

还有一个容易被忽略的 NEXTAUTH 环境变量。在本地开发时，NEXTAUTH_URL最好显式设置为http://localhost:3000。有些教程说可以不设，但我实测下来，不设它会在某些版本的 NextAuth 下出现登录回调 URL 拼接错误，报一个很晦涩的 CSRF 相关异常。填上之后世界安静了。

另外，新版 NextAuth 在 App Router 下必须提供app/api/auth/[...nextauth]/route.ts，不能再走旧的 pages API 方式：

import NextAuth from "next-auth"; import { authOptions } from "~/server/auth"; const handler = NextAuth(authOptions); export { handler as GET, handler as POST };

5.4 从 SQLite 到 PostgreSQL：部署前的必修课

本地用 SQLite 开发非常舒服，零配置，文件即数据库。但上线部署到 Vercel 时，SQLite 就成了烫手山芋——serverless 函数是临时环境，文件系统不可持久化，写在磁盘上的db.sqlite随时可能被回收。

所以在部署前，我把数据库换成了 Neon 的 PostgreSQL Serverless 服务。连接串类似这样：

DATABASE_URL="postgresql://user:password@ep-xxx.us-east-2.aws.neon.tech/t3code?sslmode=require"

切库的步骤并不复杂，核心是改一行schema.prisma：

datasource db { provider = "postgresql" url = env("DATABASE_URL") }

然后重新生成客户端：

npx prisma generate npx prisma migrate deploy

Vercel 部署时还有两个小细节值得注意。第一，在项目 Settings 的 Root Directory 或者 Build Command 里，确保安装依赖后执行了prisma generate，否则 Serverless 环境里找不到 Prisma Client。通常的做法是在 package.json 里加一个postinstall：

{ "scripts": { "postinstall": "prisma generate" } }

第二，所有环境变量（DATABASE_URL、NEXTAUTH_SECRET、GITHUB_CLIENT_ID等）都要在 Vercel 的项目设置里配置，本地.env不会自动同步到云端，这是新手最容易漏掉的一环。

5.5 调试效率：善用 tRPC 的错误格式化和日志

tRPC 默认的错误信息已经够用，但实际开发时，我更推荐在服务端上下文里加上一个自定义的errorFormatter，把 zod 的校验错误结构化输出。这样前端拿到的不再是一句笼统的 “Internal Server Error”，而是精确到哪个字段格式不对。

export const t = initTRPC.context<typeof createTRPCContext>().create({ transformer: SuperJSON, errorFormatter({ shape, error }) { return { ...shape, data: { ...shape.data, zodError: error.cause instanceof ZodError ? error.cause.flatten() : null, }, }; }, });

这个格式化的价值在前后端联调时体现得最明显。前端传错参数，后端返回的错误信息直接告诉你title字段哪一项不满足min(1)，而不是让你对着 500 状态码猜半天。

再分享一个调试习惯：不要只盯着网络面板看请求结果，配合 TanStack Query 的 devtools 面板观察缓存状态更有帮助。tRPC 自带 React Query 能力，数据有没有命中缓存、invalidate 是否生效，开发者工具里一眼就能看清，比盲猜“为什么页面没刷新”高效得多。

6. 最后一公里：部署上线和持续演进

我一直认为，一个项目只有真正部署上线、跑在自己随时可访问的域名下，才算完成闭环。t3code 的部署流程走的是 Vercel + Neon 的组合，整个过程大概半小时。部署完成之后，我给自己定了一个顺手的使用约定：能放进 t3code 的片段，绝不留在浏览器收藏夹；每条片段尽量附带一段“为什么这样写”的说明，而不是只贴代码。这样积累下来的片段，半年后翻出来依然能秒懂。

做完这个项目之后，我最大的体感是：全栈 TypeScript 的收益不在于“少写了几个字节”，而在于重构时可以非常自信地下手。改了 Prisma 模型，TS 会立刻把所有用到旧字段的地方标红；改了 tRPC Router 签名，前端所有调用点同步报错。这种跨端反馈，是单独写前端或单独写后端时完全体会不到的。

如果你也想跑一遍这套流程，我个人的建议是别找太复杂的业务需求，就用一个自己真正需要的内部小工具开刀。从 create-t3-app 初始化，到添加第一个数据模型，再到部署上线，整个过程本身就是最好的全栈实战课。踩过的坑我已经帮你垫平了，剩下的就剩动手。最后再分享一个小习惯：每次改完 Router 或 Prisma schema，我都先看 TS 有没有红色波浪线，再看运行时页面，按这个顺序排查速度会快很多。