T3 Stack全栈实战：从零构建代码片段分享平台

1. t3code 是什么，我为什么把整套服务押在 T3 上

1.1 这个项目到底解决了什么问题

t3code 是我用大半个月时间做出来的一个代码片段分享与整理平台。名字里的 t3 有两层意思：一是整套技术栈顺着 T3 Stack 的思路来搭，二是核心围绕着 TypeScript、tRPC、Tailwind CSS 这三个 T 字头的东西展开。做它的初衷很朴素——我自己的代码散落在各种地方，本地文件夹、临时粘贴的 gist、聊天记录、笔记软件里的代码块，真要找一段两个月前写过的算法片段时，往往要翻好几个地方，最后还要猜当初写它到底是为了什么。

t3code 想解决的就是这个"代码收纳与分享"的问题：每条片段可以写标题、描述、打标签，可以设置为公开或私有，公开的片段能拿到独立详情页分享给同事，其他人还能在下面评论讨论。功能规模不算大，但它把一个全栈应用该有的环节全走了一遍：账号登录、数据建模、增删改查、列表分页、动态路由、分享页面、评论互动。对我来说，它同时也是个试验场——我想验证一个老问题：用一套 TypeScript 技术栈把前后端整个串起来，到底能不能做到省心。

如果你正处于"想做一个中小型产品，但又不想同时维护前端和后端两个工程"的阶段，这篇文章比较适合你。后面我会按真实开发顺序来讲，从选型、初始化、建表、写接口、渲染页面，到部署上线和踩坑记录，你照着做基本能完整复现。

1.2 技术选型：为什么选择 T3 全家桶

动工之前，我认真对比过几条路线。

传统方案是 React 前端加 Express 后端，走 REST 接口。这套很成熟，但类型没法共享，前端一套接口定义、后端一套类型声明，改一个字段经常要动两处代码，还记得你上次因为忘了同步类型导致线上报错是什么时候吗？GraphQL 方案类型共享体验不错，可光是 schema、resolver、codegen 那套配置，对个人项目来说明显偏重。

真正让我定下来用 T3 的理由只有一个：tRPC 能在前端"直接调用"后端函数的同时，把输入输出的类型完整复用，不需要手写接口文档，也不需要单独维护一套类型对接层。打个比方，以前前后端交互像两个部门靠邮件沟通，每个接口都要写清楚参数格式；用 tRPC 之后相当于两边共用同一本通讯录，函数名和参数类型在编辑器里直接能看到，少掉一整层沟通成本。

我最终的选型清单：

这套组合最大的特点是"少选择、多约定"。对个人项目和中小型产品来说，选择少反而是优势，你能把精力集中在业务上，而不是三天两头纠结某个中间件到底用谁。

2. 从零初始化项目：脚手架、数据建模与环境变量

2.1 create-t3-app 脚手架搭建

初始化我用的是官方脚手架，包管理器选 pnpm：

pnpm create t3-app@latest t3code

交互式引导会让你勾选需要的模块。我勾了 NextAuth.js、Prisma、Tailwind CSS、tRPC，ESLint 也保留。T3 脚手架虽然上手快，但务必重视它生成的目录结构，后面很多类型报错都跟"文件放错位置"有关。

生成之后的核心结构：

t3code/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── app/api/auth/[...nextauth]/route.ts # NextAuth 入口 │ ├── server/ │ │ ├── api/routers/ # tRPC 路由 │ │ ├── api/trpc.ts │ │ ├── auth.ts │ │ └── db.ts │ └── trpc/ │ └── server.ts # 服务端调用器

t3code 用的新版脚手架默认走 App Router，但核心逻辑都收敛在 server 目录里，页面只管调用，所以就算你用的是旧版脚手架，迁移成本也不高。

2.2 Prisma 数据模型设计

t3code 的主数据模型规划了四张表：用户、代码片段、标签、评论。先看 schema：

model User { id String @id @default(cuid()) name String? email String? @unique image String? snippets Snippet[] comments Comment[] } model Snippet { id String @id @default(cuid()) title String description String? code String language String @default("plaintext") visibility String @default("public") createdAt DateTime @default(now()) updatedAt DateTime @updatedAt authorId String author User @relation(fields: [authorId], references: [id], onDelete: Cascade) tags SnippetTag[] comments Comment[] } model Tag { id String @id @default(cuid()) name String @unique snippets SnippetTag[] } model SnippetTag { snippetId String tagId String snippet Snippet @relation(fields: [snippetId], references: [id], onDelete: Cascade) tag Tag @relation(fields: [tagId], references: [id], onDelete: Cascade) @@id([snippetId, tagId]) } model Comment { id String @id @default(cuid()) content String createdAt DateTime @default(now()) authorId String snippetId String author User @relation(fields: [authorId], references: [id], onDelete: Cascade) snippet Snippet @relation(fields: [snippetId], references: [id], onDelete: Cascade) }

几个设计决策直接说结论。

主键用 cuid 而不是自增 ID，因为公开详情页的 URL 会暴露给所有人，自增 ID 容易被遍历抓取，cuid 虽然不等于加密，但足够让 URL 不可猜测，也顺手避免掉了别人顺着 id 把公开数据全扒走的低级问题。

标签用多对多关联表而不是字符串数组。刚开始我想偷懒，在 Snippet 上放一个tags String[]，结果要实现"哪些代码用了这个标签"就得全表扫描做模糊匹配，数据量稍微上来就卡。拆成关联表之后，按标签筛选就是一次普通 join，代价只是多写一点嵌套代码。

所有外键都加了onDelete: Cascade，意思是用户删账号、删片段时，关联的评论、标签记录一并清理，不会留下孤儿数据。生产环境大表上 Cascade 要谨慎，但这个项目规模下完全合理。

2.3 环境变量与数据库初始化

本地开发我用 SQLite 文件起步，连接串长这样：

DATABASE_URL="file:./db.sqlite"

先用 SQLite 而不是直接上 Postgres，是因为本地验证业务逻辑完全够用，Prisma 也支持得很顺利。等要上生产再切 Postgres，改一下连接串重新 migrate 就行。同步表结构我用的命令：

npx prisma db push

开发阶段用 db push 最省事，它会直接比对 schema 和数据库并把差异同步上去。等模型稳定了，再切到正式的迁移流程。

NextAuth 需要两个环境变量：

NEXTAUTH_SECRET="<一串随机字符串>" NEXTAUTH_URL="http://localhost:3000"

密钥生成我推荐直接用系统命令：

openssl rand -base64 32

这里有个非常典型的翻车点：本地环境变量配置齐全，部署后 NEXTAUTH_URL 忘了改成正式域名，登录回调就会一直失败，页面报 500 你还不知道错在哪。这东西建议在项目第一天就写进 README。

3. 核心功能实战：认证、接口和页面的完整串联

3.1 NextAuth 会话如何进入 tRPC 上下文

登录部分我用的 GitHub OAuth。NextAuth 配置起来很省事，在src/server/auth.ts里导出 authOptions，再在 API 路由里暴露给 NextAuth：

// src/app/api/auth/[...nextauth]/route.ts import NextAuth from "next-auth"; import { authOptions } from "@/server/auth"; const handler = NextAuth(authOptions); export { handler as GET, handler as POST };

关键的一步是把 session 塞进 tRPC 的 context，这样每个接口都能知道自己"是谁在调用"：

// src/server/api/trpc.ts import { initTRPC, TRPCError } from "@trpc/server"; import type { CreateNextContextOptions } from "@trpc/server/adapters/next"; import { getServerSession } from "next-auth"; import { authOptions } from "../auth"; import { db } from "../db"; export const createContext = async (opts: CreateNextContextOptions) => { const session = await getServerSession(authOptions); return { db, session }; }; const t = initTRPC.context<typeof createContext>().create(); export const protectedProcedure = t.procedure.use(({ ctx, next }) => { if (!ctx.session?.user) { throw new TRPCError({ code: "UNAUTHORIZED" }); } return next({ ctx: { ...ctx, session } }); });

这个protectedProcedure是我在 T3 栈里最喜欢的抽象。它把"必须登录才能调用"封装成一个中间件，创建片段、发评论这些操作，直接声明用 protectedProcedure 就可以，鉴权逻辑不会散落在每个路由里重复写。如果会话不存在，统一抛出UNAUTHORIZED，前端拿到这个错误码就能跳转登录页，非常干净。

3.2 tRPC 路由：片段的创建、列表与详情

t3code 的核心路由大概长这样：

// src/server/api/routers/snippet.ts import { z } from "zod"; import { createTRPCRouter, protectedProcedure, publicProcedure } from "../trpc"; export const snippetRouter = createTRPCRouter({ create: protectedProcedure .input( z.object({ title: z.string().min(1).max(60), code: z.string().min(1), language: z.string().default("plaintext"), visibility: z.enum(["public", "private"]).default("public"), tags: z.array(z.string()).optional(), }) ) .mutation(async ({ ctx, input }) => { const snippet = await ctx.db.snippet.create({ data: { title: input.title, code: input.code, 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; }), list: publicProcedure .input( z.object({ cursor: z.string().nullish(), limit: z.number().min(1).max(50).default(10), tag: z.string().optional(), }) ) .query(async ({ ctx, input }) => { const items = await ctx.db.snippet.findMany({ where: { visibility: "public", ...(input.tag ? { tags: { some: { tag: { name: input.tag } } } } : {}), }, take: input.limit + 1, skip: input.cursor ? 1 : 0, cursor: input.cursor ? { id: input.cursor } : undefined, orderBy: { createdAt: "desc" }, include: { author: true, tags: { include: { tag: true } } }, }); let nextCursor: string | undefined; if (items.length > input.limit) { const nextItem = items.pop(); nextCursor = nextItem?.id; } return { items, nextCursor }; }), byId: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) => { const snippet = await ctx.db.snippet.findUnique({ where: { id: input.id }, include: { author: true, tags: { include: { tag: true } }, comments: { include: { author: true } }, }, }); if (!snippet) throw new TRPCError({ code: "NOT_FOUND" }); return snippet; }), });

这段代码里有三个容易出错的地方，挨个说。

connectOrCreate是标签去重的关键。没有它，重复提交同名标签会创建大量脏数据，还会触发唯一约束报错。用了它之后，同名的标签会直接复用已有记录，这是多对多标签系统里必须记住的写法。

列表查询用了基于游标的分页，而不是传统页数分页。原因很实际：代码片段列表是持续变动的，页数分页在数据插入时会出现重复或漏读。游标分页用"上一页最后一条的 id"作为下一页的起点，数据再怎么变都不会乱。

至于take: limit + 1，这是判断"还有没有下一页"的常用技巧：如果实际查出的是 limit+1 条，说明后面还有数据，把第 limit 条的 id 作为 nextCursor 返回给前端。nextCursor 为空即到达末尾。

3.3 页面渲染：服务端初值加客户端接管

列表页我用 App Router 的服务端组件拿首屏数据，因为搜索引擎和直接访问的用户需要看到即时内容：

// src/app/page.tsx import { HydrateClient } from "@/trpc/server"; import { api } from "@/trpc/server"; export default async function HomePage() { const initialData = await api.snippet.list({ limit: 10 }); return ( <HydrateClient> <SnippetList initialData={initialData} /> </HydrateClient> ); }

这里的api.snippet.list是脚手架提供的服务端调用器，它会在服务端直接执行 tRPC 路由并序列化结果到客户端。好处是首屏没有 loading 状态，也不会因为浏览器端再发一次请求造成数据不一致。

客户端组件里再用 useQuery 接管后续交互：

"use client"; import { api } from "@/trpc/react"; export function SnippetList({ initialData }) { const { data } = api.snippet.list.useQuery( { limit: 10 }, { initialData } ); // 渲染列表... }

注意一个原则：不要同时用服务端 caller 和客户端 query 去请求同一份数据，否则 React 会报 hydration 不匹配。正确姿势是服务端把初值塞进缓存，客户端 query 只在缓存 miss 时才发请求，之后的刷新全部交给客户端管理。这个配合关系我第一次用的时候没搞明白，导致首页每次刷新都闪一下 loading，排查半天才反应过来是重复请求导致缓存 key 对不上。

4. 踩坑实录：类型报错、迁移失败和线上白屏

4.1 tRPC 类型推断的翻车现场

开发第一周踩得最多的坑都集中在类型上。

症状一：改了后端返回结构，前端组件依然用旧字段，编译器全程没反应，直到运行时报 undefined。原因多半是某个 query 的返回值里显式写了any，把 tRPC 的类型保护整个关掉了。这里有个铁律：tRPC 的输入输出类型尽量让 TypeScript 自己推断，不要在路由层写as any，更不要把返回类型显式标成 any。一旦出现 any，前面做的所有类型安全工作全白费。

症状二：报错Type instantiation is excessively deep。原因是路由 input 对象存在过度嵌套。我那个片段的 tags 字段一开始直接引用了完整的 Tag 类型，zod 校验也没收口，导致类型展开过深。解决办法是 input 里只接收字符串数组，数据库查询结果交给 Prisma 推断，绝不手动引用模型类型当入参。

症状三：前端调用某个 mutation 后，返回值在编辑器里显示never。这通常是因为输入参数的 zod 校验和数据库 create 的 data 字段对不上，TypeScript 推断出永远不可能成立的联合类型。遇到这种问题，先删掉 input 里的 optional chain 看能不能复现，再逐步把字段加上，基本能定位。

排查 tRPC 类型问题我有一个固定流程：先pnpm tsc --noEmit看有没有全局类型错误，再用编辑器点进路由函数返回值确认推断是否正确，最后在前端组件里 hover 一下data字段看类型是否完整。三步做完，大部分类型断裂问题都能找到原因。

4.2 Prisma 迁移与 SQLite 的边界

Prisma 迁移流程本身不复杂，但有几个坑值得记录。

迁移文件只加不改。我不止一次想把历史迁移里的某个字段直接改掉，结果prisma migrate dev立刻报 drift detected，警告数据库状态和迁移历史不一致。正确的做法是：写错的字段就再新增一条迁移去改，历史迁移文件当只读资料，不要手动编辑。

SQLite 对ALTER TABLE支持有限。比如你给某个字段改了类型，Prisma 会发现 SQLite 做不了原地变更，会提示你重置数据库。开发阶段重置无所谓，但如果已经有线上数据就要非常谨慎。我现在的习惯是：模型稳定之前用prisma db push快速同步，模型稳定之后立刻切换到正式迁移，每一条迁移都用--name起清晰的名字，方便追溯：

npx prisma migrate dev --name add_snippet_comments

还有一个连接问题：开发时代码里直接new PrismaClient()没问题，但部署到无服务器平台后，每个函数实例都会尝试创建数据库连接，很容易把连接池打爆。解决方案是 Prisma 客户端做单例缓存，放在全局变量上，只在首次初始化时创建：

// src/server/db.ts 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;

4.3 部署后白屏与 500 的排查思路

t3code 第一次部署到 Vercel 后，登录功能正常，但首页一直 500。排查半天发现是环境变量没配齐：本地 .env 里有的变量线上没加进去，尤其是 NEXTAUTH_SECRET，本地有默认值导致代码怎么跑都正常，部署完就露馅。

第二个更隐蔽的问题：App Router 的服务端组件里调用 tRPC server caller 时，如果某个 query 因为数据库连接失败抛异常，整个页面都会挂掉，而且生产模式下的错误堆栈会被吞掉，只给你一个泛泛的 500。我当时的排查套路是：

1. 本地先执行一遍pnpm build，确认没有类型和编译错误。
2. 打开 Vercel 的 Functions 日志，把关键字捞出来，像prisma、unauthorized、DATABASE_URL都值得看一眼。
3. 检查环境变量面板里的键名是否和.env完全一致，注意大小写和下划线。

部署类问题我整理成了一张速查表：

生产日志这块我后来给 createContext 加了一层轻量容错：如果 session 查询失败，返回空 session 而不是直接崩溃，至少让公开页面能正常渲染，登录用户的功能单独报错。

5. 体验优化：分页缓存、暗色模式和高亮渲染

5.1 无限滚动与查询缓存

列表页改用无限滚动后，又碰上一个典型问题：从详情页返回列表页时，已经加载过的数据会重新请求一遍。

原因在于 tRPC 的查询缓存 key 是序列化后的完整输入参数，只要参数不同就是两个独立缓存条目。理论上没问题，但对列表这种频繁变参的场景，我建议直接用useInfiniteQuery接管翻页逻辑：

const { data, fetchNextPage, hasNextPage } = api.snippet.list.useInfiniteQuery( { limit: 10, tag: activeTag }, { getNextPageParam: (lastPage) => lastPage.nextCursor ?? null, initialData: propInitialData ? { pages: [propInitialData], pageParams: [null] } : undefined, } );

这里有两个细节。第一，initialData的结构必须是{ pages: [], pageParams: [] }，我第一次直接传了个数组进去，页面直接渲染崩溃。第二，路由里要返回{ items, nextCursor }这样的结构，getNextPageParam才能拿到正确的下一页游标。

另外，tRPC 的缓存是全局的，同一条 query 在不同组件里共享。这意味着列表页滚动到底部加载了五页数据后，切到另一个 tab 再切回来，缓存还在，不会白白浪费请求。这是 tRPC 相比手写 fetch 的优势，但前提是你不要在组件里随便关闭缓存。

5.2 暗色模式与代码高亮

t3code 的阅读场景大多是深夜写代码时查片段，暗色模式不是装饰，是刚需。我用的 next-themes 接入：

// src/app/providers.tsx "use client"; import { ThemeProvider } from "next-themes"; export function Providers({ children }: { children: React.ReactNode }) { return ( <ThemeProvider attribute="class" defaultTheme="system" enableSystem> {children} </ThemeProvider> ); }

Tailwind 侧在tailwind.config.ts里配好darkMode: "class"，组件里就可以写dark:bg-gray-900这类类名，很顺手。

代码高亮这块我用的prism-react-renderer，但这个组件有个隐藏问题：它依赖浏览器 DOM，如果直接在服务端组件里渲染，会报 hydration 错误。我的做法是把它单独封装成 client component，语言类型做兜底处理：

"use client"; import { Highlight, themes } from "prism-react-renderer"; export function CodeBlock({ code, language }: { code: string; language: string }) { return ( <Highlight theme={themes.nightOwl} code={code.trim()} language={language || "plaintext"}> {({ className, style, tokens, getLineProps, getTokenProps }) => ( <pre className={className} style={style}> {tokens.map((line, i) => ( <div key={i} {...getLineProps({ line })}> {line.map((token, key) => ( <span key={key} {...getTokenProps({ token })} /> ))} </div> ))} </pre> )} </Highlight> ); }

语言类型一定要兜底，遇到未知语言直接按 plaintext 处理，不然 prism 的 tokenizer 会抛异常，生产环境又是难排查的白屏。另外我给详情页加了一键复制按钮，用navigator.clipboard.writeText实现，简单直接，代码片段工具最核心的体验就是"看一眼 + 拷走用"。

6. 回看 t3code：一些真实的开发体会

项目收尾后，我最大的体会不是"这套栈真好用"，而是"约束的力量"。create-t3-app 把目录结构、认证方式、接口放置位置都定死了，我反而省掉了一大批"今天用 A 库还是 B 库"的决策成本。中小型全栈项目最怕的不是功能复杂，而是选择太多导致时间被磨掉。T3 给我的是一种近乎固执的约定，绑定它的同时，也把注意力解放给了真正的业务逻辑。

另一个很实在的经验是：环境变量和数据库迁移这两件事，务必要在项目第一天整理清楚。很多项目后期花大力气补环境变量文档、规范化迁移流程，代价远高于一开始就写好那一页 README。我自己就在 t3code 上因为 NEXTAUTH_URL 线上漏配折腾了两个小时，这种时间本不该花。

最后分享一个小技巧，算是我的习惯：每次新增或修改一个 tRPC 路由、改动 Prisma schema 之后，先在终端跑一遍pnpm tsc --noEmit，再打开浏览器把核心流程点一遍。这比写一堆测试更能早期暴露类型断裂问题，尤其对单人全栈项目来说，这是成本最低、收益最直接的验证方式。

t3code 目前还在迭代，我接下来打算加两个功能：一个是基于全文搜索的片段检索，目前列表页只能按标签过滤，等片段数量起来之后关键词搜索就是刚需；另一个是在线运行片段的能力，简单场景下可以直接在页面里执行 JavaScript 片段，避免用户为了验证一段代码再开一个编辑器。这两个功能做完之后，我再单独写一篇分享。