如果你跟我一样，在浏览器收藏夹里囤了两三百段代码，却从没在需要的时候找到过它们，那这个项目可能会让你有点共鸣。t3code 是我给自己写的一个代码片段管理工具：收集题解、顺手存下的 CSS 技巧、生产环境救过命的错误处理片段，统一打标签、可检索、公开分享。技术栈选了 T3 Stack——Next.js 负责 UI 和路由，tRPC 负责前后端接口，Prisma 管数据，Tailwind 写样式。这篇文章不是一份开箱即用的产品介绍，而是 t3code 从零到上线全过程的记录，适合想用 T3 Stack 做真实项目的朋友参考。
1. 为什么我选 T3 Stack，而不是"Next.js + 自己搭接口层"
1.1 我真正想要的是：改字段时前端当场报错
先说我最初的技术方案：Next.js 写页面，自建几个 REST API 路由，再用 axios 封装请求。听起来没什么问题，实际跑到第十个接口就开始难受了。后端返回的 snippet 对象里多了一个language字段，前端SnippetCard组件里忘了补上，编译期完全看不出来，只有打开页面发现语言标签不显示，再回头看接口文档，才知道漏了字段。
t3code 的字段不算少：标题、内容、语言、标签、作者、可见性、创建时间。字段一多，这种"契约漂移"的维护成本会成倍增加。换成 T3 Stack 之后，前后端共享同一套类型：后端在 tRPC 路由里定义 procedure 和 zod 输入，前端直接用从服务端推导出来的 client 调用。我在 Prisma schema 里给CodeSnippet加一个字段，前端所有用到它的组件会立刻标红，而不是等到接口联调才发现。
这个体验上的差别很难用几句话讲清。它不是"少写几个 interface"的问题，而是把整个联调阶段压缩到接近于零——因为类型系统已经在编译期替你做完了"接口对齐"这件事。对 t3code 这种生命周期长的个人项目来说，半年后回来改代码时，这个优势会被放得更大。
1.2 tRPC、GraphQL 与 REST 的取舍
决定用 T3 Stack 之前，我认真比较过 GraphQL。GraphQL 的强项是"前端按需取字段"和"多个客户端共用一套接口"，这对大型团队很有价值。但 t3code 只有一个前端、一个后端，数据模型也很简单，GraphQL 反而引入了一堆新概念：schema、resolver、codegen，每个都要学要维护，收益却很低。
REST 当然可以，但它要求我为每个资源手动设计端点、处理序列化、写校验，前端还要为每个接口维护一份类型定义。对"一个人维护一个小而完整的应用"这种场景，tRPC 的复杂度是最低的：路由本身就是函数，zod 同时承担输入校验和类型推导，不需要额外维护接口文档。
如果你担心将来要把 t3code 开放给第三方调用，其实也不冲突。真正需要开放 API 时，在 tRPC 外面再包一层 REST 端点即可，内部逻辑完全复用，不用推翻重来。
| 方案 | 类型安全程度 | 额外概念 | 适合场景 |
|---|---|---|---|
| REST + 手写类型 | 低，靠自觉 | 低 | 多端/第三方接入，团队流程成熟 |
| GraphQL | 高 | 高（schema、resolver、codegen） | 多客户端、字段差异大 |
| tRPC | 高 | 低 | 前后端自控、TypeScript 全栈项目 |
1.3 我刻意不用的东西
T3 Stack 之外，我没往项目里加任何状态管理库。t3code 的页面就那么几个：列表、详情、新建、编辑，UI 状态非常有限。React Query 已经通过 tRPC 的客户端内建能力处理了服务端状态缓存，再引入 Redux 或 Zustand 属于纯负担。
数据层我也没选重型方案。Prisma 自带的类型生成能力已经覆盖了"表结构 → TypeScript 类型"这一环，配 SQLite 做开发、PostgreSQL 做生产就够了。少一个库，就少一层需要维护的地基，这是我在 t3code 里最坚持的选型标准。
2. 从 create-t3-app 起跑：那些必须在初始化时定下的选择
2.1 初始化交互里勾选了什么
t3code 的初始化我只做了一次，但那次勾选我认真看了每个问题：
npm create t3-app@latest t3code交互式问答里会依次问：包管理器、TypeScript 是否启用、Tailwind CSS、tRPC、NextAuth.js、Prisma、App Router 还是 Pages Router。我建议第一次跑这个脚手架的同学，宁可少勾两个，跑通了再补。我见过不少人全选之后被生成的 demo 代码绕晕，一上来就删改，结果哪个模块都没理解透。
我勾的是：TypeScript、Tailwind、tRPC、NextAuth、Prisma，App Router 版本。Drizzle 那次我没选，因为 Prisma 已经足够，再多一个 ORM 选项只会让 schema 维护复杂化。
2.2 生成后的目录结构：每个文件在链路里的位置
create-t3-app 生成的目录非常有规律，我把关键文件的职责列一下：
src/server/db.ts：创建 PrismaClient 单例，避免热更新时重复实例化。src/server/auth.ts：NextAuth 配置，session 策略、OAuth provider、callbacks 都在这里。src/server/api/trpc.ts：tRPC 初始化，创建 context、定义publicProcedure和protectedProcedure。src/server/api/root.ts：把业务 router 合并成appRouter。src/server/api/routers/：具体的业务路由，t3code 里就是snippet.ts。src/trpc/server.ts：给 Server Components 的服务端调用器。src/trpc/react.tsx：给 Client Components 的 React hooks 封装。src/app/api/trpc/[trpc]/route.ts：tRPC 的 HTTP 端点，浏览器请求会打到这里。
我被问得最多的一个问题是："请求进来，数据是怎么走的？"简单说：浏览器请求app/api/trpc/[trpc]这个端点，它调用createTRPCContext注入了数据库实例和 session 信息，然后按 procedure 分发到具体路由函数，执行完返回序列化 JSON。整个过程里，前端调用的是类型安全的方法，而不是拼字符串的 URL。
2.3 第一轮裁剪：删 Demo，立规矩
创建完项目，我做的第一件事是把示例代码删掉。create-t3-app 默认会生成一个post相关的示例 router，schema.prisma里也带了示例模型。这两个地方要一起清理，否则执行prisma migrate时会生成一堆无关表格。
t3code 的路由我建在src/server/api/routers/snippet.ts，然后在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;这一步看着简单，其实决定了整个 API 的组织方式。appRouter是一个嵌套对象，前端调用时路径就是api.snippet.list、api.snippet.create，层级和文件结构一一对应，找代码的时候非常直观。
2.4 环境变量和数据库连接
t3code 开发阶段用的是 SQLite，DATABASE_URL是这样写的：
DATABASE_URL="file:./db.sqlite"NextAuth 在 v5 下面需要AUTH_SECRET，我用openssl rand -base64 32生成一串随机值，存进.env。这个值本地和线上必须是不同字符串，而且线上的一定要重新生成一遍——把本地 secret 带到线上，严格说是有安全风险的。
create-t3-app会生成一个src/env.js，专门校验环境变量是否齐全。我第一次部署到 Vercel 时忘了配AUTH_SECRET，build 直接失败，靠的就是这个文件里的校验逻辑提示。所以我的建议是：环境变量一定从项目一开始就规范化，别等到部署环节才补。
3. Prisma 数据建模：代码卡片、标签和作者的关系
3.1 两张核心表 + 一张中间表
t3code 的核心数据模型是用户和代码片段的关系。用户是一对多代码片段；片段和标签是多对多。因为 SQLite 不支持 PostgreSQL 那种String[]数组字段，所以标签用关联表的方式来做，反而更干净，将来做tag 统计也方便。
prisma/schema.prisma长这样（节选核心部分）：
model User { id String @id @default(cuid()) name String? email String? @unique emailVerified DateTime? image String? snippets CodeSnippet[] accounts Account[] sessions Session[] } model CodeSnippet { id String @id @default(cuid()) title String content String language String @default("plaintext") visibility String @default("public") author User @relation(fields: [authorId], references: [id], onDelete: Cascade) authorId String tags TagOnSnippet[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt @@index([authorId]) } model Tag { id String @id @default(cuid()) name String @unique snippets TagOnSnippet[] } model TagOnSnippet { snippet CodeSnippet @relation(fields: [snippetId], references: [id], onDelete: Cascade) tag Tag @relation(fields: [tagId], references: [id], onDelete: Cascade) snippetId String tagId String @@id([snippetId, tagId]) }TagOnSnippet是标准的多对多中间表，联合主键保证"同一片段给同一标签"不会出现重复。onDelete: Cascade表示删除代码片段时，中间表的记录也跟着删除，不会留下孤儿数据。
这里有一个我踩过的细节：language字段的值，我直接用字符串存。有人会问，为什么不用枚举？为了让新语言随时能加，不用动数据库结构。t3code 是收藏夹性质的应用，今天存 TypeScript，明天可能存 Rust，枚举反而限制死了。
3.2 从 SQLite 切到 PostgreSQL：迁移时最容易翻车的点
开发时 SQLite 确实方便，零配置、单文件，prisma migrate dev一把梭。但到了部署阶段就该换 PostgreSQL 了。因为 Serverless 平台上，每个函数实例可能分散在不同机器，SQLite 的单文件模式根本没法可靠地共享数据。
切换时最安全的做法是：把schema.prisma里的provider从"sqlite"改成"postgresql"，然后删掉本地旧的迁移记录，重新生成一份 PostgreSQL 的迁移，再执行：
npx prisma migrate dev --name init_postgres这里要提醒一句：两个数据库对默认函数、字段类型的支持有差别。比如 SQLite 下的某些默认值写法在 PostgreSQL 里可能不兼容，所以切 provider 之后一定要跑一次prisma generate，再重新跑迁移，别偷懒。
3.3 seed 脚本造数据
开发 UI 不能开着空数据库干瞪眼，我写了一个prisma/seed.ts，造了两个用户、二十条代码片段。seed 脚本里我用了connectOrCreate来塞标签，避免重复插入。
npx prisma db seedseed 脚本的原则是"纯逻辑、可重复执行"。每次跑完清掉重来，绝不能依赖本地文件系统或者某个特定目录，否则换台机器就跑不起来了。
4. tRPC 链路打通：查询、变更、登录保护与 zod 校验
4.1 tRPC 在 t3code 里的完整位置
tRPC 解决了什么？简单说，它让 t3code 的前端可以直接"调用"后端函数，而不是"请求接口"。这两个词听起来差不多，实际开发体验差很远。
后端在snippet.ts里定义list、create、delete等 procedure，前端调用api.snippet.list.useQuery()，输入输出类型完全自动推导。请求进来时，发生在createTRPCContext里的动作是：读取请求头里的 session，实例化 PrismaClient，把二者一起放进ctx。下面的代码展示了protectedProcedure的几个关键部分：
// src/server/api/trpc.ts import { TRPCError, initTRPC } from "@trpc/server"; import { type Session } from "next-auth"; const t = initTRPC .context<{ db: PrismaClient; session: Session | null }>() .create(); export const publicProcedure = t.procedure; export const protectedProcedure = t.procedure.use(({ ctx, next }) => { if (!ctx.session?.user) { throw new TRPCError({ code: "UNAUTHORIZED" }); } return next({ ctx: { session: ctx.session } }); });protectedProcedure本质是一个中间件。检查ctx.session，没有用户就抛UNAUTHORIZED，有则继续执行。所有需要登录的接口都换成这个 procedure，权限逻辑集中在一处，不用每个接口重复写 if。
4.2 第一个 query：公开列表
t3code 的公开列表对游客开放，所以用publicProcedure：
import { createTRPCRouter, publicProcedure } from "~/server/api/trpc"; export const snippetRouter = createTRPCRouter({ list: publicProcedure.query(async ({ ctx }) => { return ctx.db.codeSnippet.findMany({ where: { visibility: "public" }, orderBy: { createdAt: "desc" }, take: 50, include: { author: { select: { name: true } }, tags: { include: { tag: true } }, }, }); }), });分页用的是take: 50，先满足"最近 50 条"这个最常用的浏览场景。include把作者名和标签一起捞出来，避免前端再发一次请求。如果你觉得"连表查询很重"，可以后续改成select只取需要的字段，但 t3code 这个体量远没到需要优化那一步。
4.3 zod 定义输入：前后端共用一套校验
接下来是最让我舒服的部分：用 zod 一次性定义输入，前后端自动获取类型。
import { z } from "zod"; const createSnippetSchema = z.object({ title: z.string().min(1, "标题不能为空").max(100), content: z.string().min(1, "内容不能为空"), language: z.string().max(30).default("plaintext"), visibility: z.enum(["public", "private"]).default("public"), tags: z.array(z.string().max(20)).default([]), }); export const snippetRouter = createTRPCRouter({ create: protectedProcedure .input(createSnippetSchema) .mutation(async ({ ctx, input }) => { const snippet = await ctx.db.codeSnippet.create({ data: { title: input.title, content: input.content, language: input.language, visibility: input.visibility, authorId: ctx.session.user.id, tags: { create: input.tags.map((name) => ({ tag: { connectOrCreate: { where: { name }, create: { name }, }, }, })), }, }, }); return snippet; }), });这个 mutation 里有几个值得说的细节。
authorId从ctx.session.user.id取，而不是让前端传。这是安全边界：用户不能指定"我替某人发表"。connectOrCreate是标签系统的关键：标签名已存在就直接连接，不存在就创建，一句代码替代了"先查存在、再创建、再关联"的三步逻辑。
zod的.default()很有意思，输入里没传language时，它会在校验阶段自动填上默认值，类型推导也能正确反映"这个字段一定有值"。这样后端代码里就不用写input.language ?? "plaintext"这种防御逻辑了。
4.4 用中间件处理用户 ID，而不是在接口里硬取
在真实代码里，ctx.session.user.id并不是一开始就能拿到的。我遇到的坑是：NextAuth 的 session 默认不含id字段，需要手动在auth.ts的 callbacks 里把token.sub映射到session.user.id。我加了一小段代码：
callbacks: { session({ session, token }) { if (session.user) { session.user.id = token.sub as string; } return session; }, },加上之后，protectedProcedure里才能稳定拿到user.id。这个坑的排查过程我在后面"踩坑实录"里再展开。
5. 前端页面与服务端渲染：列表、详情、提交表单的搭建
5.1 App Router 下的页面组织
t3code 的页面结构是这样的：
/：主页，所有公开代码片段列表/snippets/[id]：单个片段详情页/new：新建片段的表单页
我按功能天然拆分到app目录里，目录名即路由。这里的关键问题不是目录怎么建，而是哪些组件用 Server Components、哪些用 Client Components。
列表页和详情页，我用了 Server Components。它们的任务是拉数据、渲染，几乎不需要交互。src/trpc/server.ts提供了一个服务端调用器，Server Component 里可以直接这样查数据：
import { api } from "~/trpc/server"; export default async function HomePage() { const snippets = await api.snippet.list(); return ( <main> {snippets.map((snippet) => ( <SnippetCard key={snippet.id} snippet={snippet} /> ))} </main> ); }这个api对象和 Client Components 里的api使用方式不同，但它依赖同一个appRouter类型。服务端直接把数据库查出来的数据渲染成 HTML，不经过一次多余的客户端请求，首屏速度肉眼可见地快。
5.2 新建表单：交互密集，交给 Client Components
新建页面的标签输入、语言选择、文本编辑都有大量交互，必须用 Client Components。t3code 里我用"use client"标注，然后调用 tRPC 的 React hooks：
"use client"; import { api } from "~/trpc/react"; export default function NewSnippetPage() { const utils = api.useUtils(); const createMutation = api.snippet.create.useMutation({ onSuccess: () => { utils.snippet.list.invalidate(); router.push("/"); }, }); // 表单提交逻辑略 }utils.snippet.list.invalidate()是我很喜欢的一个能力：提交成功之后，把缓存里的老列表标记为失效，React Query 会自动重新拉取新数据。不用手动刷新页面，也不用写复杂的请求时序逻辑。
顺带提一个性能层面的小建议：如果页面里大部分内容是静态的，只有个别按钮需要交互，那就让 Server Component 渲染静态部分，把交互组件单独抽到 Client Components 里，不要整页 "use client"。t3code 的详情页就是这样组织的，首屏 JavaScript 量比一开始全用 Client Components 时小了很多。
5.3 搜索和过滤：先别急着上数据库查询
t3code 的列表页加了一个搜索框和一个语言筛选下拉框。我的第一版处理方式是在客户端内存中过滤：先把所有公开片段拉到前端，然后按query和language做过滤。
这个方案在数据量几千条以内完全够用，而且交互反馈是即时的。如果等数据库查询，每次敲键盘都要发请求，还得做防抖，复杂度一下子上去。等片段真的过万了，再把过滤条件作为 tRPC query 参数传给 Prisma 的contains查询也不迟。先解决眼前问题，不提前优化，是我写这个项目时最坚持的原则之一。
5.4 Tailwind 搭卡片和标签样式
Tailwind 在这类项目里的体验确实是"不用离开 HTML 就能写样式"。t3code 的代码卡片是一个圆角矩形，标题一行截断，正文保留两行省略，语言标签用不同颜色，作者和日期放在底部。
标签样式我用了一个小的映射函数，根据语言返回不同配色：
const languageColor: Record<string, string> = { typescript: "bg-blue-100 text-blue-800", rust: "bg-orange-100 text-orange-800", css: "bg-purple-100 text-purple-800", plaintext: "bg-gray-100 text-gray-800", };自定义样式库的好处是换主题时只改这里。t3code 后来加了深色模式支持，我差不多就是加一套暗色配色映射的事，没有全局搜索替换的痛苦。
6. 部署到 Vercel 与生产环境检查清单
6.1 部署前必须过的四道检查关
t3code 上线前，我按清单逐项排查，任何一项有问题都会直接 500 或构建失败：
- 环境变量：
DATABASE_URL、AUTH_SECRET、OAuth Provider 的 Client ID / Secret。不同平台的变量名可能不同，本地.env里写的AUTH_DISCORD_ID，线上也要保持一致。 - Prisma 客户端：执行
npx prisma generate，确认node_modules/.prisma里的客户端版本和schema.prisma一致。 - 数据库迁移：
npx prisma migrate deploy而不是migrate dev，后者是开发用的，会在线上环境提示交互操作。 - NextAuth 回调地址：Vercel 给的自然域名为
https://xxx.vercel.app，OAuth Provider 后台必须把这个域名加进回调白名单，否则登录直接转圈。
6.2 为什么生产数据库换成了 PostgreSQL
开发时 SQLite 是单文件模式，跑在本地毫无压力。但一旦部署到 Vercel 的 Serverless Function 上，每个实例是独立且冷启动的，SQLite 文件无法在多个实例之间可靠共享，并发读写还会锁库。
我换成了 Neon 的云 Postgres，连接串形如：
DATABASE_URL="postgresql://user:password@ep-xxx.us-east-2.aws.neon.tech/t3code?sslmode=require"另一个选择是用 Prisma Accelerate，它负责把数据库连接通过加速器转发，减少 Serverless 环境下的连接数压力。如果项目是社区公开的、会有并发访问的，这个方案更稳妥。t3code 目前流量不大，一个连接池字符串就够用。
6.3 RSC 带来多少真实收益
部署完我看了一次 lighthouse 和 Vercel Analytics，有个数字印象很深：列表页和详情页的首屏 JavaScript，在改用 Server Components 之后降到了很低的值。原因很简单——这两页几乎没有交互，全部由服务端渲染纯 HTML，不需要下载 React 代码到浏览器再跑一遍。
我没做极限优化，只是把"能放在服务端渲染的组件留在服务端"，这个单一决策就带来了很大的收益。如果你在做一个内容展示型功能，这一点一定要用上。
6.4 日志和错误监控
Vercel 的日志面板只保留很短时间，而且没法做聚合查询。t3code 上线后第一周，我靠的就是 Sentry：把前端和后端的错误上报集中起来。实际帮到我的两次都是数据库相关的错误，一次是连接超时，一次是 Prisma 客户端初始化失败。没有日志直接看错误栈，这种问题要排查很久。
我的建议是：任何要上线的 Side Project，都用一天时间接一个错误监控，成本很低，回报极高。
7. 六次踩坑换来的排错思路：t3code 开发实录
7.1 改了 router，前端却提示"属性不存在"
现象：新增一个api.snippet.deleteprocedure，前端调用时报"属性不存在"。
原因：tRPC 客户端类型是从服务端类型推导出来的，但 dev server 的类型缓存没有实时刷新。这个坑几乎每个用 tRPC 的人都会遇到，不是代码写错了，是类型缓存机制的问题。
解决：重启 dev server。如果重启还不行，检查src/trpc/react.tsx里导出的api是否正确地使用了AppRouter类型。
7.2 Serverless 环境下 Prisma 连接数被打满
现象：并发请求一上来，偶发PrismaClientInitializationError，页面随机 500。
原因：Serverless 平台每个函数实例都会创建一次 PrismaClient，如果不做单例，连接池很快被占满。
解决：src/server/db.ts里用全局单例，避免每次请求都 new 一个 client：
import { PrismaClient } from "@prisma/client"; const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient }; export const db = globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = db;另外在连接串里加上连接池参数，或使用 Prisma Accelerate。前者开销小，后者更稳。
7.3 NextAuth session 里没有 user.id
现象：登录后创建片段，接口报 401，日志提示session.user.id是undefined。
原因：NextAuth v5 的默认 session 回调并没有把数据库里的id暴露给前端 session 对象。常规做法是在auth.ts的callbacks.session里把token.sub映射成session.user.id，前提是 session 策略是 JWT。
排查过程：我先确认了前端能拿到session.email和session.name，说明 session 本身是正常的。然后打印了完整的session对象，发现确实没有id，再翻 NextAuth 文档，才确认需要在 callbacks 里补一段逻辑。如果你用的是 Prisma adapter 加 database session 策略，那 user 会直接出现在 session 回调里，写法和 JWT 策略不同，需要分开记。
7.4 本地跑得好好的，线上 500
现象：本地npm run dev一切正常，push 到 Vercel 后首页直接 500。
原因：绝大多数情况是环境变量问题，其次是 OAuth 回调地址没配。t3code 那次是忘了配AUTH_SECRET，env.js的校验直接让 build 失败。还有一次是DATABASE_URL里的账号密码含有特殊字符，没有做 URL 编码，导致连接串解析异常。
我的做法是本地.env和线上 Environment Variables 逐项对照，一项一项勾掉。如果没有env.js这样的校验层，我建议你也加一个：哪怕只是简单检查会不会 throw，也能避免部署到一半才发现变量缺失。
写在最后：t3code 做完之后我对 T3 Stack 的判断
t3code 前前后后改了三轮，第一轮用 REST 写了一半，第二轮切 tRPC 重写，第三轮换 App Router。三轮下来最大的体会是：技术选型不需要"最先进"，需要"最匹配"。T3 Stack 不是银弹，但如果你跟我一样是"一个人维护一个小而完整的应用"，它把类型、校验、数据库、登录揉到一起的方式，确实能省掉不少心事。
做完这个项目，我给自己定的硬性要求只有一个：任何时候字段改名，前端必须当场报错，而不是等到接口联调才发现。这也算是我写 t3code 最有成就感的时刻。说句实话，如果你手头也有一个"攒了好多代码片段却不好找"的痛点，自己写一个 t3code 这样的工具，比满世界找替代品要靠谱得多——顺带还能把 T3 Stack 完整学一遍，两全其美。
