t3code 是我最近给团队搭的一套 TypeScript 全栈脚手架代号。当时手头有个内部工具要从零写起REST API 要维护两份类型定义GraphQL 的 schema 层又重得让人提不起劲最后我选了更务实的路用 T3 Stack 全家桶Next.js、tRPC、Prisma、Tailwind把前后端焊死在一起。最打动我的地方是写接口像写本地函数一样自然前端调后端拿到的类型就是后端 return 的类型几乎没有中间损耗。如果你也在搭新项目或者正犹豫要不要从 REST 迁到 tRPC这篇聊聊我落地 t3code 的完整过程——从脚手架初始化到线上部署踩坑能帮你少绕不少弯。1. t3code 到底是什么不造框架只沉淀一套工程化约定很多第一次听到 t3code 的人会以为它又是个新框架其实不是。它是 T3 Stack 这套技术选型落地后的代码形态准确说是一套被验证过的全栈工程约定。T3 Stack 的核心主张是“TypeScript First”项目里尽量让类型从数据库一路贯穿到浏览器中间不丢信息。t3code 这个名字只是我给这套内部模板起的代号方便团队沟通时说“按 t3code 的规范来”。1.1 这套约定由哪几块组成Next.js 14App Router负责页面渲染、路由、服务端组件。tRPC负责“前后端接口调用”替代手写 REST 路由。Prisma负责数据库访问schema 即类型的源头。Tailwind CSS负责样式写起来快主体代码里不占核心逻辑。NextAuth.js负责登录态和 tRPC 的 context 天然配合。Zod负责输入校验和 tRPC 的 input 解析绑定。这套组合适合什么场景中小型应用、内部工具、快速迭代的业务系统、全栈 Demo。数据模型不算特别复杂但要求开发效率高、类型安全、一个人能端到端搞定。反过来如果你的团队已经有一套庞大的 REST API 体系或者需要开放给第三方开发者那 tRPC 不是最优解因为它把前后端绑得太紧不适合做公开接口。1.2 为什么我放弃手写 REST转向 tRPC为了说服团队我做过一个对比表维度RESTGraphQLtRPC类型安全需要手写或生成 DTO需要 codegen天然全链路推断学习成本低中低会写函数就会写接口调试难度中URL 可读性好中略麻烦但可加日志服务端实现成本中高schema、resolver极低适合开放 API好好差适合内部全栈一般一般极好REST 像打电话你不仅要拨号还得报一遍对方身份tRPC 像同一个进程里直接调用函数参数、返回值、异常类型全都由 TypeScript 编译器盯着。只要你接受“前端和后端是同一个代码库”这个前提它就非常顺手。2. 冷启动初始化一个 t3code 项目比想象中省事脚手架这东西用起来越无脑越好。T3 Stack 官方的 create-t3-app 已经把大部分脏活干完了你要做的是明确每个选项的含义。2.1 环境准备与创建命令Node.js 版本建议 18 以上我用的 20 LTS。包管理器推荐 pnpm因为依赖安装快、磁盘占用小T3 官方交互里也会提示你选。pnpm create t3-applatest t3code命令执行后会进入交互式选择。这一步很多人随手回车但每个选项背后都有代价我逐个说一下我的选择和理由。2.2 初始化交互到底怎么选选项我的选择理由TypeScript必须选这是整套方案的灵魂Tailwind CSS选写样式省时间团队没有历史包袱tRPC选核心中的核心不选就没意义了Prisma选数据访问层复用类型NextAuth选登录和 session 直接注入 tRPC contextESLint选团队规范强制省得以后补使用 App Router选服务端组件取数据更适合 tRPC 的 createCaller导入 alias选默认 / 路径少踩相对路径的坑如果你只是想先跑通一个 Demo数据库那一步可以直接选 SQLite省去搭 PostgreSQL 的麻烦。但我要提醒一句SQLite 在并发写入场景表现一般等真上了生产建议尽快切到 PostgreSQL而且 Prisma 的 schema 基本不用改只要换 provider 和连接串就行。2.3 初始化后的目录结构长什么样t3code/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── pages/api/ │ │ ├── auth/[...nextauth].ts │ │ └── trpc/[trpc].ts │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ ├── root.ts │ │ │ └── trpc.ts │ │ ├── db.ts │ │ └── auth.ts │ ├── trpc/ │ │ ├── react.tsx │ │ └── server.ts │ └── app/ └── env.js重点在 src/server/api/trpc.ts它是 tRPC 的根工厂src/server/db.ts 是 Prisma Client 单例src/trpc/server.ts 是服务端调用器后续所有页面取数都走它。理解这几个文件后面写业务就很顺。我踩过的第一个坑就是目录理解偏差以为 router 一定要往 pages/api 下面放结果把业务逻辑全部堆在 App Router 的api目录结构里绕了一大圈才发现 tRPC 的路由定义和 HTTP 入口是分离的。HTTP 入口只需一个[trpc].ts文件真正的业务路由全在src/server/api/routers/里。3. 数据库先行Prisma Schema 不是照抄是设计t3code 的类型安全链条是从数据库开始的。Prisma schema 写得清楚后面 TypeScript 类型就会长得很端正schema 写得随意后面每个页面都会感受到痛苦。3.1 为什么用 Prisma 作为数据层一开始有人提议用 TypeORM 或 Drizzle各有优点但 Prisma 赢在两点一是 schema 文件即可视化的数据模型文档新人看一遍就懂表关系二是prisma generate会根据 schema 生成完整的类型定义和 tRPC 联动非常自然。它的代价是运行时比 Drizzle 重一点但 t3code 这种体量的项目完全感受不到差异。3.2 设计一个最小内容模型假设 t3code 里要做一个“文章 标签”的功能这是非常典型的业务模型。先写 Prisma schemagenerator client { provider prisma-client-js } datasource db { provider sqlite url env(DATABASE_URL) } model User { id String id default(cuid()) name String? email String? unique emailVerified DateTime? image String? posts Post[] accounts Account[] sessions Session[] } model Post { id String id default(cuid()) title String content String published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id], onDelete: Cascade) tags PostTag[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Tag { id String id default(cuid()) name String unique posts PostTag[] } model PostTag { post Post relation(fields: [postId], references: [id], onDelete: Cascade) postId String tag Tag relation(fields: [tagId], references: [id], onDelete: Cascade) tagId String id([postId, tagId]) }说几个容易忽略的细节。主键用cuid()而不是自增整数因为后续如果做分库分表或分布式写字符串主键更好扩展。onDelete: Cascade确保删除文章时关联的 PostTag 自动清理不会残留脏数据。updatedAt会自动维护更新时间省去手动赋值。3.3 从 schema 到数据库迁移、生成、验证写完 schema执行迁移pnpm prisma migrate dev --name init这个命令会做三件事生成迁移 SQL 文件、同步到数据库、执行prisma generate更新客户端类型。之后可以用pnpm prisma studio打开一个本地管理界面直观检查数据我是把它当成简易后台来用的。如果只是调 schema 不关心迁移记录可以用pnpm prisma db push直接同步。但生产环境我强烈建议走 migrate 流程因为migrate deploy可以在部署时按顺序执行历史迁移可控性强。经验之谈每次改完 schema一定要重新跑一遍prisma generate否则编辑器里 Prisma Client 的类型还是旧的报错报得莫名其妙。这个顺手动作会在后面省掉大量排查时间。4. 类型安全的业务闭环tRPC 路由从 request 到 response 的完整链路tRPC 和 REST 最大的区别在感觉上REST 是“客户端请求一个 URL服务端响应 JSON”tRPC 是“客户端调用一个函数服务端执行并返回结果”。难点不在写路由而在理解 context 和 procedure 的注入机制。4.1 tRPC 的初始化三件套context、procedure、router先看src/server/api/trpc.ts的核心部分import { initTRPC, TRPCError } from trpc/server; import { getServerAuthSession } from ~/server/auth; import { db } from ~/server/db; export const createTRPCContext async (opts: { headers: Headers }) { const session await getServerAuthSession(); return { db, session, ...opts }; }; const t initTRPC.contexttypeof createTRPCContext().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: { ...ctx, userId: ctx.session.user.id }, }); }); export const createTRPCRouter t.router;这里有个关键点每次请求都会经过createTRPCContext把数据库实例和用户 session 装进 context。protectedProcedure是一个中间件如果没登录直接抛出 UNAUTHORIZED并把解析出来的userId塞进后面的 ctx。这样业务路由就再也不关心登录态判断了专心写逻辑即可。4.2 写第一个业务 mutation创建文章以一个“新建文章”的接口为例看完整链路。import { z } from zod; import { createTRPCRouter, protectedProcedure } from ~/server/api/trpc; export const postRouter createTRPCRouter({ create: protectedProcedure .input( z.object({ title: z.string().min(1, 标题不能为空), content: z.string().min(1, 内容不能为空), tagIds: z.array(z.string()).optional(), }) ) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.userId, tags: input.tagIds ? { create: input.tagIds.map((tagId) ({ tagId })) } : undefined, }, }); }), });注意input经过zod校验之后类型已经从unknown收窄成{ title: string; content: string; tagIds?: string[] }函数体里写input.title有完全的类型提示。这就是“校验即类型推导”不需要额外再写一遍接口定义。然后把路由挂到 rootimport { createTRPCRouter } from ~/server/api/trpc; import { postRouter } from ~/server/api/routers/post; export const appRouter createTRPCRouter({ post: postRouter, }); export type AppRouter typeof appRouter;export type AppRouter是给前端用的关键前端 import 这个类型就能拿到所有路由的输入输出类型。4.3 前端调用的三种姿势t3code 里调用接口有几种姿势按场景选。服务端组件里用createCallerimport { createCaller } from ~/trpc/server; export default async function PostsPage() { const caller createCaller(); const posts await caller.post.list(); return PostList posts{posts} /; }客户端组件里用 hooksuse client; import { api } from ~/trpc/react; function CreatePostForm() { const utils api.useUtils(); const createPost api.post.create.useMutation({ onSuccess: () { utils.post.list.invalidate(); }, }); return ( form onSubmit{(e) { e.preventDefault(); createPost.mutate({ title: 标题, content: 内容 }); }} button typesubmit发布/button /form ); }invalidate是 tRPC 的缓存失效机制执行 create 成功后会标记 post.list 查询数据过期下次重新拉取页面上的列表自动刷新。这比 React Query 里手动 refetch 省心很多。如果有人问为什么还要保留原生 fetch 入口我一般只在无法接入 tRPC 的外部脚本里才用。tRPC 本身也提供httpBatchLink聚合请求多个 query 在客户端会合并成一个 HTTP 请求性能上比一个个 REST 调用更好。5. 页面与数据流Next.js 服务端组件里怎么“安全地”取数t3code 用的 App Router 有个值得反复琢磨的点服务端组件和客户端组件拿数据的方式不一样。搞混了就会出现“Cant use hooks in server component”这类报错。5.1 App Router tRPC 的两条路第一条是服务端直接用createCaller适合首屏渲染、列表页、详情页第二条是客户端走httpLinkhooks适合交互性强的表单、筛选、实时操作。我一开始图省事全部用客户端 hooks结果首屏要等 JS 加载完才发请求白屏时间被拉得很长。后来把只读列表改成服务端createCaller首屏直接拿到渲染好的 HTML体验明显改善。经验是能服务端拿的就服务端拿客户端只在真正需要交互状态时才用 hooks。5.2 服务端组件里为什么不能用 api hooksapi.post.list.useQuery底层是 React Query依赖 React Context。服务端组件没有浏览器环境也没有 Context Provider自然用不了。t3code 的做法是在src/trpc/server.ts里为服务端场景封装createCallerimport { headers } from next/headers; import { cache } from react; import { createTRPCContext } from ~/server/api/trpc; import { appRouter } from ~/server/api/root; export const createCaller cache(async () { const h new Headers(); const headerStore await headers(); for (const [key, value] of headerStore.entries()) { h.set(key, value); } const ctx await createTRPCContext({ headers: h }); return appRouter.createCaller(ctx); });cache()保证在同一页面级渲染里复用同一个 caller不重复解析 session减少数据库和认证查询的次数。5.3 数据变更后的缓存刷新服务端拿数据的另一个问题变更后如何刷新。客户端可以invalidate服务端则用router.refresh()或revalidatePath()。比如在客户端组件里执行了发布文章的操作成功后调用router.refresh()刷新当前路由下服务端组件的渲染结果。这个 API 不会强制整页刷新只是重新从服务端拉当前路由的数据体验上很顺滑。我踩过的一个细节revalidatePath传参路径要写全比如说列表在/posts那就写revalidatePath(/posts)如果写成/posts/带了后缀斜杠Next.js 可能匹配不上。这属于那种查半小时文档都查不出来的隐性问题提前写下来帮你跨过。6. 部署与上线t3code 从 localhost 到生产环境的最后一公里开发环境跑得再欢部署才是暴露问题的时候。t3code 部署期间我遇到的最多问题集中在环境变量和迁移时机上。6.1 环境变量哪些是必须的.env至少要有这三类# 数据库连接 DATABASE_URLpostgresql://user:passwordhost:5432/t3code?connection_limit5 # NextAuth 必填 NEXTAUTH_SECRET由 openssl rand -base64 32 生成 NEXTAUTH_URLhttps://your-domain.com # 如果用了 GitHub/Google 登录 GITHUB_CLIENT_ID GITHUB_CLIENT_SECRETNEXTAUTH_SECRET 很多人随便填一个字符串然后登录回调一直 401。正确做法是用命令生成高熵值openssl rand -base64 32这个值在本地和生产必须一致否则 session 无法解密表现为“登录成功后立刻跳回未登录状态”。6.2 数据库迁移在生产环境的执行时机这是 t3code 部署最容易翻车的一步。很多人把prisma migrate deploy放在构建前的脚本里一旦数据库迁移失败整个构建就中断还有人直接把prisma migrate dev跑在生产环境dev 会尝试创建迁移记录稍有不慎就把迁移表搞乱。正确做法是分开执行构建镜像或打包只执行prisma generate。发布阶段单独执行prisma migrate deploy。应用启动只读数据库不做任何结构变更。如果你用 Docker可以利用 Dockerfile 里的多个 stage如果直接用平台内置部署流程那就把迁移命令放到 post-deploy hook 里而不是 build 阶段。6.3 日志与故障定位上线后一旦页面上出现 “UNAUTHORIZED” 或 “INTERNAL_SERVER_ERROR”第一件事是看服务端日志而不是改代码。t3code 里我习惯在每个 router 外层加一层简单的 logger把 method、path、耗时、status code 打出来export const loggerMiddleware t.middleware(async ({ path, type, next, ctx }) { const start Date.now(); const result await next({ ctx }); const durationMs Date.now() - start; console.log([tRPC] ${type} ${path} ${durationMs}ms ${result.ok ? ok : error}); return result; });部署环境里再挂一个日志采集把[tRPC]前缀的日志单独过滤出来排错效率高很多。下面是我在生产环境遇到的三类典型错误错误形态根因修复方向登录回调 500NEXTAUTH_SECRET 不一致用openssl rand重新生成并同步所有环境Prisma 连接数超限Serverless 并发连接池没限制DATABASE_URL 加?connection_limit5tRPC 反复 401context 里 session 是 null检查getServerAuthSession()是否在正确域名下7. 踩过的坑与绕过t3code 实战中真正烧时间的几个问题前面是流程性的东西这一节专门讲讲那些让我查了半宿的坑。每个都是真实发生过的。7.1 NextAuth 回调 401secret 不一致的排查链路现象是本地登录正常部署后点击登录跳到回调页就报 401。我一开始怀疑是域名白名单问题检查了AUTH_URL、NEXTAUTH_URL都对。后来打开服务器日志发现 JWT 解密失败才反应过来是NEXTAUTH_SECRET不匹配。排查链路复盘看日志确认错误发生在 JWT 解码阶段。对比本地、预发布、生产三份环境变量发现生产 Secret 是部署平台自动生成的每次发布都会变。固定一个值写入所有环境重启后解决。经验只要涉及多环境部署Secret 类变量必须显式固定不要依赖平台自动注入。7.2 Prisma 与 Serverless 的连接数爆了现象是接口偶发超时数据库 CPU 不高但连接数打满。原因很简单每个无服务函数实例都会创建自己的 Prisma Client连接池被实例数量放大。tRPC 的 context 每次调用都拿db实例如果服务端调用频率高连接数就炸了。解决有两步数据库连接串加connection_limit比如postgresql://...?connection_limit5。用全局单例复用 Prisma Client避免每个实例重复建连。Prisma 官方文档也提到在 serverless 环境要避免多个实例重复连接。我在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;7.3 tRPC 在服务端拿不到 session在客户端组件里用useSession()拿用户信息很正常但服务端组件里没这个 hook。我一开始顺手在服务端组件里 importuseSession然后 Next.js 直接报错。正确做法是调用getServerAuthSession()或通过createCaller的 context 拿。还有一个隐蔽点createCaller里构造 headers 如果没把原始请求头完整传进去NextAuth 的 CSRF 校验会失败。所以要用headers()把当前请求的 header 复制一份再传入createTRPCContext否则 session 始终为 null接口眼巴巴地全部 401。7.4 Zod 报 400 但前端不知道哪错了前端提交表单时少传了一个字段tRPC 返回 400但错误信息被吞掉React Query 的 error 对象里没有可读细节。原因是 zod 错误默认会经过trpc/server的序列化客户端要取error.shape.message或error.data才能看到具体字段。在客户端封装一个工具函数export function getTrpcErrorMessage(error: unknown): string { if (error typeof error object data in error) { const data (error as { data?: { zodError?: { fieldErrors?: Recordstring, string[] } } }).data; const firstFieldError data?.zodError?.fieldErrors ? Object.values(data.zodError.fieldErrors)[0] : undefined; return firstFieldError?.[0] ?? 请求参数有误; } return 网络异常请稍后重试; }表单里这样用setError(getTrpcErrorMessage(error))用户看到的就是中文校验提示而不是一串 JSON。7.5 类型参数嵌套过多编辑器卡顿t3code 全链路类型推导很爽但当你把AppRouter的类型暴露给前端后tsc 在大型项目里可能变慢。现象是编辑器提示突然延迟tsc --noEmit要跑十几秒。解决分几步路由按模块拆分不要让一个 root router 塞几十个业务文件。前端导入类型时用import type { AppRouter } from ~/server/api/root避免把运行时代码带进来。必要时给 tsc 加skipLibCheck: true减少第三方库类型检查量。这套组合拳下来类型推导依然全链路但编译速度恢复到可接受范围。8. 把 t3code 从模板变成产品的几条扩展路t3code 跑通之后你会发现这套骨架的扩展性比想象中好。这里是几个我实际验证过的方向。8.1 权限细化从“登录就行”到“谁可以做什么”protectedProcedure只是保证登录真实业务还要区分管理员、编辑、普通用户。我的做法是在 User 模型上加role字段然后扩展 procedure 链const adminProcedure protectedProcedure.use(({ ctx, next }) { if (ctx.session?.user.role ! ADMIN) { throw new TRPCError({ code: FORBIDDEN }); } return next({ ctx }); });调用时delete: adminProcedure .input(z.object({ id: z.string() })) .mutation(async ({ ctx, input }) { await ctx.db.post.delete({ where: { id: input.id } }); });这种约定式的权限写法比在每个接口里手写 if else 干净得多。8.2 缓存与性能Redis 接入点t3code 的 query 天然适合加缓存。客户端有 React Query 的 staleTime 兜底但服务端的createCaller查询每次都会打数据库。接入 Redis 时可以在 router 层做缓存装饰const cacheableProcedure publicProcedure.use(async ({ path, type, next, ctx }) { if (type ! query) return next({ ctx }); const key t3code:${path}; const cached await redis.get(key); if (cached) return { json: JSON.parse(cached) }; const result await next({ ctx }); await redis.set(key, JSON.stringify(result.json), EX, 30); return result; });30 秒的短过期适合列表页数据变更后可以用del主动清掉相关 key兼顾新度和性能。8.3 上传与文件处理Post 模型里加imageUrl字段上传接口也走 tRPC用publicProcedurez.instanceof(File)校验接收文件后存入对象存储把 URL 写回数据库。tRPC 的 input 支持 binary 处理配合httpBatchLink的formData配置即可比单独再挂一个上传后端省事得多。8.4 从 tRPC 到 OpenAPI要不要全量暴露如果有一天你决定让第三方接入可以用trpc-openapi给指定路由生成 OpenAPI 文档不用推翻重写。我的建议是不要全量暴露挑一批只读接口开放即可写操作继续走 tRPC保证内部架构不变形。最后再分享一个落地时的小技巧t3code 这套工程化约定真正让我受益的是“类型从一个源头贯穿到底”的心智负担。以前写后端定义一套 schema前端再造一遍类型两边四舍五入总有一处对不上排查一次至少半小时。现在从 Prisma schema 生成数据库类型再通过 tRPC 推导出前端类型中间环节全部由编译器兜底改一个字段所有用它的地方一起红。这个体验一旦习惯了就很难退回 REST。如果你准备用 t3code 起步自己的项目我的建议是别一股脑复制大项目的目录先对照这篇的初始化流程选最小集合跑通再按业务把 router 一个个拆出来。等数据模型稳定了再考虑权限、缓存、上传这些扩展能力。踩坑嘛肯定还会踩但只要每次都有一个像“先看日志再改代码”“环境变量显式固定”这样的复盘动作坑就会越踩越少。
t3code 是我最近给团队搭的一套 TypeScript 全栈脚手架代号。当时手头有个内部工具要从零写起REST API 要维护两份类型定义GraphQL 的 schema 层又重得让人提不起劲最后我选了更务实的路用 T3 Stack 全家桶Next.js、tRPC、Prisma、Tailwind把前后端焊死在一起。最打动我的地方是写接口像写本地函数一样自然前端调后端拿到的类型就是后端 return 的类型几乎没有中间损耗。如果你也在搭新项目或者正犹豫要不要从 REST 迁到 tRPC这篇聊聊我落地 t3code 的完整过程——从脚手架初始化到线上部署踩坑能帮你少绕不少弯。1. t3code 到底是什么不造框架只沉淀一套工程化约定很多第一次听到 t3code 的人会以为它又是个新框架其实不是。它是 T3 Stack 这套技术选型落地后的代码形态准确说是一套被验证过的全栈工程约定。T3 Stack 的核心主张是“TypeScript First”项目里尽量让类型从数据库一路贯穿到浏览器中间不丢信息。t3code 这个名字只是我给这套内部模板起的代号方便团队沟通时说“按 t3code 的规范来”。1.1 这套约定由哪几块组成Next.js 14App Router负责页面渲染、路由、服务端组件。tRPC负责“前后端接口调用”替代手写 REST 路由。Prisma负责数据库访问schema 即类型的源头。Tailwind CSS负责样式写起来快主体代码里不占核心逻辑。NextAuth.js负责登录态和 tRPC 的 context 天然配合。Zod负责输入校验和 tRPC 的 input 解析绑定。这套组合适合什么场景中小型应用、内部工具、快速迭代的业务系统、全栈 Demo。数据模型不算特别复杂但要求开发效率高、类型安全、一个人能端到端搞定。反过来如果你的团队已经有一套庞大的 REST API 体系或者需要开放给第三方开发者那 tRPC 不是最优解因为它把前后端绑得太紧不适合做公开接口。1.2 为什么我放弃手写 REST转向 tRPC为了说服团队我做过一个对比表维度RESTGraphQLtRPC类型安全需要手写或生成 DTO需要 codegen天然全链路推断学习成本低中低会写函数就会写接口调试难度中URL 可读性好中略麻烦但可加日志服务端实现成本中高schema、resolver极低适合开放 API好好差适合内部全栈一般一般极好REST 像打电话你不仅要拨号还得报一遍对方身份tRPC 像同一个进程里直接调用函数参数、返回值、异常类型全都由 TypeScript 编译器盯着。只要你接受“前端和后端是同一个代码库”这个前提它就非常顺手。2. 冷启动初始化一个 t3code 项目比想象中省事脚手架这东西用起来越无脑越好。T3 Stack 官方的 create-t3-app 已经把大部分脏活干完了你要做的是明确每个选项的含义。2.1 环境准备与创建命令Node.js 版本建议 18 以上我用的 20 LTS。包管理器推荐 pnpm因为依赖安装快、磁盘占用小T3 官方交互里也会提示你选。pnpm create t3-applatest t3code命令执行后会进入交互式选择。这一步很多人随手回车但每个选项背后都有代价我逐个说一下我的选择和理由。2.2 初始化交互到底怎么选选项我的选择理由TypeScript必须选这是整套方案的灵魂Tailwind CSS选写样式省时间团队没有历史包袱tRPC选核心中的核心不选就没意义了Prisma选数据访问层复用类型NextAuth选登录和 session 直接注入 tRPC contextESLint选团队规范强制省得以后补使用 App Router选服务端组件取数据更适合 tRPC 的 createCaller导入 alias选默认 / 路径少踩相对路径的坑如果你只是想先跑通一个 Demo数据库那一步可以直接选 SQLite省去搭 PostgreSQL 的麻烦。但我要提醒一句SQLite 在并发写入场景表现一般等真上了生产建议尽快切到 PostgreSQL而且 Prisma 的 schema 基本不用改只要换 provider 和连接串就行。2.3 初始化后的目录结构长什么样t3code/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── pages/api/ │ │ ├── auth/[...nextauth].ts │ │ └── trpc/[trpc].ts │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ ├── root.ts │ │ │ └── trpc.ts │ │ ├── db.ts │ │ └── auth.ts │ ├── trpc/ │ │ ├── react.tsx │ │ └── server.ts │ └── app/ └── env.js重点在 src/server/api/trpc.ts它是 tRPC 的根工厂src/server/db.ts 是 Prisma Client 单例src/trpc/server.ts 是服务端调用器后续所有页面取数都走它。理解这几个文件后面写业务就很顺。我踩过的第一个坑就是目录理解偏差以为 router 一定要往 pages/api 下面放结果把业务逻辑全部堆在 App Router 的api目录结构里绕了一大圈才发现 tRPC 的路由定义和 HTTP 入口是分离的。HTTP 入口只需一个[trpc].ts文件真正的业务路由全在src/server/api/routers/里。3. 数据库先行Prisma Schema 不是照抄是设计t3code 的类型安全链条是从数据库开始的。Prisma schema 写得清楚后面 TypeScript 类型就会长得很端正schema 写得随意后面每个页面都会感受到痛苦。3.1 为什么用 Prisma 作为数据层一开始有人提议用 TypeORM 或 Drizzle各有优点但 Prisma 赢在两点一是 schema 文件即可视化的数据模型文档新人看一遍就懂表关系二是prisma generate会根据 schema 生成完整的类型定义和 tRPC 联动非常自然。它的代价是运行时比 Drizzle 重一点但 t3code 这种体量的项目完全感受不到差异。3.2 设计一个最小内容模型假设 t3code 里要做一个“文章 标签”的功能这是非常典型的业务模型。先写 Prisma schemagenerator client { provider prisma-client-js } datasource db { provider sqlite url env(DATABASE_URL) } model User { id String id default(cuid()) name String? email String? unique emailVerified DateTime? image String? posts Post[] accounts Account[] sessions Session[] } model Post { id String id default(cuid()) title String content String published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id], onDelete: Cascade) tags PostTag[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Tag { id String id default(cuid()) name String unique posts PostTag[] } model PostTag { post Post relation(fields: [postId], references: [id], onDelete: Cascade) postId String tag Tag relation(fields: [tagId], references: [id], onDelete: Cascade) tagId String id([postId, tagId]) }说几个容易忽略的细节。主键用cuid()而不是自增整数因为后续如果做分库分表或分布式写字符串主键更好扩展。onDelete: Cascade确保删除文章时关联的 PostTag 自动清理不会残留脏数据。updatedAt会自动维护更新时间省去手动赋值。3.3 从 schema 到数据库迁移、生成、验证写完 schema执行迁移pnpm prisma migrate dev --name init这个命令会做三件事生成迁移 SQL 文件、同步到数据库、执行prisma generate更新客户端类型。之后可以用pnpm prisma studio打开一个本地管理界面直观检查数据我是把它当成简易后台来用的。如果只是调 schema 不关心迁移记录可以用pnpm prisma db push直接同步。但生产环境我强烈建议走 migrate 流程因为migrate deploy可以在部署时按顺序执行历史迁移可控性强。经验之谈每次改完 schema一定要重新跑一遍prisma generate否则编辑器里 Prisma Client 的类型还是旧的报错报得莫名其妙。这个顺手动作会在后面省掉大量排查时间。4. 类型安全的业务闭环tRPC 路由从 request 到 response 的完整链路tRPC 和 REST 最大的区别在感觉上REST 是“客户端请求一个 URL服务端响应 JSON”tRPC 是“客户端调用一个函数服务端执行并返回结果”。难点不在写路由而在理解 context 和 procedure 的注入机制。4.1 tRPC 的初始化三件套context、procedure、router先看src/server/api/trpc.ts的核心部分import { initTRPC, TRPCError } from trpc/server; import { getServerAuthSession } from ~/server/auth; import { db } from ~/server/db; export const createTRPCContext async (opts: { headers: Headers }) { const session await getServerAuthSession(); return { db, session, ...opts }; }; const t initTRPC.contexttypeof createTRPCContext().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: { ...ctx, userId: ctx.session.user.id }, }); }); export const createTRPCRouter t.router;这里有个关键点每次请求都会经过createTRPCContext把数据库实例和用户 session 装进 context。protectedProcedure是一个中间件如果没登录直接抛出 UNAUTHORIZED并把解析出来的userId塞进后面的 ctx。这样业务路由就再也不关心登录态判断了专心写逻辑即可。4.2 写第一个业务 mutation创建文章以一个“新建文章”的接口为例看完整链路。import { z } from zod; import { createTRPCRouter, protectedProcedure } from ~/server/api/trpc; export const postRouter createTRPCRouter({ create: protectedProcedure .input( z.object({ title: z.string().min(1, 标题不能为空), content: z.string().min(1, 内容不能为空), tagIds: z.array(z.string()).optional(), }) ) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.userId, tags: input.tagIds ? { create: input.tagIds.map((tagId) ({ tagId })) } : undefined, }, }); }), });注意input经过zod校验之后类型已经从unknown收窄成{ title: string; content: string; tagIds?: string[] }函数体里写input.title有完全的类型提示。这就是“校验即类型推导”不需要额外再写一遍接口定义。然后把路由挂到 rootimport { createTRPCRouter } from ~/server/api/trpc; import { postRouter } from ~/server/api/routers/post; export const appRouter createTRPCRouter({ post: postRouter, }); export type AppRouter typeof appRouter;export type AppRouter是给前端用的关键前端 import 这个类型就能拿到所有路由的输入输出类型。4.3 前端调用的三种姿势t3code 里调用接口有几种姿势按场景选。服务端组件里用createCallerimport { createCaller } from ~/trpc/server; export default async function PostsPage() { const caller createCaller(); const posts await caller.post.list(); return PostList posts{posts} /; }客户端组件里用 hooksuse client; import { api } from ~/trpc/react; function CreatePostForm() { const utils api.useUtils(); const createPost api.post.create.useMutation({ onSuccess: () { utils.post.list.invalidate(); }, }); return ( form onSubmit{(e) { e.preventDefault(); createPost.mutate({ title: 标题, content: 内容 }); }} button typesubmit发布/button /form ); }invalidate是 tRPC 的缓存失效机制执行 create 成功后会标记 post.list 查询数据过期下次重新拉取页面上的列表自动刷新。这比 React Query 里手动 refetch 省心很多。如果有人问为什么还要保留原生 fetch 入口我一般只在无法接入 tRPC 的外部脚本里才用。tRPC 本身也提供httpBatchLink聚合请求多个 query 在客户端会合并成一个 HTTP 请求性能上比一个个 REST 调用更好。5. 页面与数据流Next.js 服务端组件里怎么“安全地”取数t3code 用的 App Router 有个值得反复琢磨的点服务端组件和客户端组件拿数据的方式不一样。搞混了就会出现“Cant use hooks in server component”这类报错。5.1 App Router tRPC 的两条路第一条是服务端直接用createCaller适合首屏渲染、列表页、详情页第二条是客户端走httpLinkhooks适合交互性强的表单、筛选、实时操作。我一开始图省事全部用客户端 hooks结果首屏要等 JS 加载完才发请求白屏时间被拉得很长。后来把只读列表改成服务端createCaller首屏直接拿到渲染好的 HTML体验明显改善。经验是能服务端拿的就服务端拿客户端只在真正需要交互状态时才用 hooks。5.2 服务端组件里为什么不能用 api hooksapi.post.list.useQuery底层是 React Query依赖 React Context。服务端组件没有浏览器环境也没有 Context Provider自然用不了。t3code 的做法是在src/trpc/server.ts里为服务端场景封装createCallerimport { headers } from next/headers; import { cache } from react; import { createTRPCContext } from ~/server/api/trpc; import { appRouter } from ~/server/api/root; export const createCaller cache(async () { const h new Headers(); const headerStore await headers(); for (const [key, value] of headerStore.entries()) { h.set(key, value); } const ctx await createTRPCContext({ headers: h }); return appRouter.createCaller(ctx); });cache()保证在同一页面级渲染里复用同一个 caller不重复解析 session减少数据库和认证查询的次数。5.3 数据变更后的缓存刷新服务端拿数据的另一个问题变更后如何刷新。客户端可以invalidate服务端则用router.refresh()或revalidatePath()。比如在客户端组件里执行了发布文章的操作成功后调用router.refresh()刷新当前路由下服务端组件的渲染结果。这个 API 不会强制整页刷新只是重新从服务端拉当前路由的数据体验上很顺滑。我踩过的一个细节revalidatePath传参路径要写全比如说列表在/posts那就写revalidatePath(/posts)如果写成/posts/带了后缀斜杠Next.js 可能匹配不上。这属于那种查半小时文档都查不出来的隐性问题提前写下来帮你跨过。6. 部署与上线t3code 从 localhost 到生产环境的最后一公里开发环境跑得再欢部署才是暴露问题的时候。t3code 部署期间我遇到的最多问题集中在环境变量和迁移时机上。6.1 环境变量哪些是必须的.env至少要有这三类# 数据库连接 DATABASE_URLpostgresql://user:passwordhost:5432/t3code?connection_limit5 # NextAuth 必填 NEXTAUTH_SECRET由 openssl rand -base64 32 生成 NEXTAUTH_URLhttps://your-domain.com # 如果用了 GitHub/Google 登录 GITHUB_CLIENT_ID GITHUB_CLIENT_SECRETNEXTAUTH_SECRET 很多人随便填一个字符串然后登录回调一直 401。正确做法是用命令生成高熵值openssl rand -base64 32这个值在本地和生产必须一致否则 session 无法解密表现为“登录成功后立刻跳回未登录状态”。6.2 数据库迁移在生产环境的执行时机这是 t3code 部署最容易翻车的一步。很多人把prisma migrate deploy放在构建前的脚本里一旦数据库迁移失败整个构建就中断还有人直接把prisma migrate dev跑在生产环境dev 会尝试创建迁移记录稍有不慎就把迁移表搞乱。正确做法是分开执行构建镜像或打包只执行prisma generate。发布阶段单独执行prisma migrate deploy。应用启动只读数据库不做任何结构变更。如果你用 Docker可以利用 Dockerfile 里的多个 stage如果直接用平台内置部署流程那就把迁移命令放到 post-deploy hook 里而不是 build 阶段。6.3 日志与故障定位上线后一旦页面上出现 “UNAUTHORIZED” 或 “INTERNAL_SERVER_ERROR”第一件事是看服务端日志而不是改代码。t3code 里我习惯在每个 router 外层加一层简单的 logger把 method、path、耗时、status code 打出来export const loggerMiddleware t.middleware(async ({ path, type, next, ctx }) { const start Date.now(); const result await next({ ctx }); const durationMs Date.now() - start; console.log([tRPC] ${type} ${path} ${durationMs}ms ${result.ok ? ok : error}); return result; });部署环境里再挂一个日志采集把[tRPC]前缀的日志单独过滤出来排错效率高很多。下面是我在生产环境遇到的三类典型错误错误形态根因修复方向登录回调 500NEXTAUTH_SECRET 不一致用openssl rand重新生成并同步所有环境Prisma 连接数超限Serverless 并发连接池没限制DATABASE_URL 加?connection_limit5tRPC 反复 401context 里 session 是 null检查getServerAuthSession()是否在正确域名下7. 踩过的坑与绕过t3code 实战中真正烧时间的几个问题前面是流程性的东西这一节专门讲讲那些让我查了半宿的坑。每个都是真实发生过的。7.1 NextAuth 回调 401secret 不一致的排查链路现象是本地登录正常部署后点击登录跳到回调页就报 401。我一开始怀疑是域名白名单问题检查了AUTH_URL、NEXTAUTH_URL都对。后来打开服务器日志发现 JWT 解密失败才反应过来是NEXTAUTH_SECRET不匹配。排查链路复盘看日志确认错误发生在 JWT 解码阶段。对比本地、预发布、生产三份环境变量发现生产 Secret 是部署平台自动生成的每次发布都会变。固定一个值写入所有环境重启后解决。经验只要涉及多环境部署Secret 类变量必须显式固定不要依赖平台自动注入。7.2 Prisma 与 Serverless 的连接数爆了现象是接口偶发超时数据库 CPU 不高但连接数打满。原因很简单每个无服务函数实例都会创建自己的 Prisma Client连接池被实例数量放大。tRPC 的 context 每次调用都拿db实例如果服务端调用频率高连接数就炸了。解决有两步数据库连接串加connection_limit比如postgresql://...?connection_limit5。用全局单例复用 Prisma Client避免每个实例重复建连。Prisma 官方文档也提到在 serverless 环境要避免多个实例重复连接。我在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;7.3 tRPC 在服务端拿不到 session在客户端组件里用useSession()拿用户信息很正常但服务端组件里没这个 hook。我一开始顺手在服务端组件里 importuseSession然后 Next.js 直接报错。正确做法是调用getServerAuthSession()或通过createCaller的 context 拿。还有一个隐蔽点createCaller里构造 headers 如果没把原始请求头完整传进去NextAuth 的 CSRF 校验会失败。所以要用headers()把当前请求的 header 复制一份再传入createTRPCContext否则 session 始终为 null接口眼巴巴地全部 401。7.4 Zod 报 400 但前端不知道哪错了前端提交表单时少传了一个字段tRPC 返回 400但错误信息被吞掉React Query 的 error 对象里没有可读细节。原因是 zod 错误默认会经过trpc/server的序列化客户端要取error.shape.message或error.data才能看到具体字段。在客户端封装一个工具函数export function getTrpcErrorMessage(error: unknown): string { if (error typeof error object data in error) { const data (error as { data?: { zodError?: { fieldErrors?: Recordstring, string[] } } }).data; const firstFieldError data?.zodError?.fieldErrors ? Object.values(data.zodError.fieldErrors)[0] : undefined; return firstFieldError?.[0] ?? 请求参数有误; } return 网络异常请稍后重试; }表单里这样用setError(getTrpcErrorMessage(error))用户看到的就是中文校验提示而不是一串 JSON。7.5 类型参数嵌套过多编辑器卡顿t3code 全链路类型推导很爽但当你把AppRouter的类型暴露给前端后tsc 在大型项目里可能变慢。现象是编辑器提示突然延迟tsc --noEmit要跑十几秒。解决分几步路由按模块拆分不要让一个 root router 塞几十个业务文件。前端导入类型时用import type { AppRouter } from ~/server/api/root避免把运行时代码带进来。必要时给 tsc 加skipLibCheck: true减少第三方库类型检查量。这套组合拳下来类型推导依然全链路但编译速度恢复到可接受范围。8. 把 t3code 从模板变成产品的几条扩展路t3code 跑通之后你会发现这套骨架的扩展性比想象中好。这里是几个我实际验证过的方向。8.1 权限细化从“登录就行”到“谁可以做什么”protectedProcedure只是保证登录真实业务还要区分管理员、编辑、普通用户。我的做法是在 User 模型上加role字段然后扩展 procedure 链const adminProcedure protectedProcedure.use(({ ctx, next }) { if (ctx.session?.user.role ! ADMIN) { throw new TRPCError({ code: FORBIDDEN }); } return next({ ctx }); });调用时delete: adminProcedure .input(z.object({ id: z.string() })) .mutation(async ({ ctx, input }) { await ctx.db.post.delete({ where: { id: input.id } }); });这种约定式的权限写法比在每个接口里手写 if else 干净得多。8.2 缓存与性能Redis 接入点t3code 的 query 天然适合加缓存。客户端有 React Query 的 staleTime 兜底但服务端的createCaller查询每次都会打数据库。接入 Redis 时可以在 router 层做缓存装饰const cacheableProcedure publicProcedure.use(async ({ path, type, next, ctx }) { if (type ! query) return next({ ctx }); const key t3code:${path}; const cached await redis.get(key); if (cached) return { json: JSON.parse(cached) }; const result await next({ ctx }); await redis.set(key, JSON.stringify(result.json), EX, 30); return result; });30 秒的短过期适合列表页数据变更后可以用del主动清掉相关 key兼顾新度和性能。8.3 上传与文件处理Post 模型里加imageUrl字段上传接口也走 tRPC用publicProcedurez.instanceof(File)校验接收文件后存入对象存储把 URL 写回数据库。tRPC 的 input 支持 binary 处理配合httpBatchLink的formData配置即可比单独再挂一个上传后端省事得多。8.4 从 tRPC 到 OpenAPI要不要全量暴露如果有一天你决定让第三方接入可以用trpc-openapi给指定路由生成 OpenAPI 文档不用推翻重写。我的建议是不要全量暴露挑一批只读接口开放即可写操作继续走 tRPC保证内部架构不变形。最后再分享一个落地时的小技巧t3code 这套工程化约定真正让我受益的是“类型从一个源头贯穿到底”的心智负担。以前写后端定义一套 schema前端再造一遍类型两边四舍五入总有一处对不上排查一次至少半小时。现在从 Prisma schema 生成数据库类型再通过 tRPC 推导出前端类型中间环节全部由编译器兜底改一个字段所有用它的地方一起红。这个体验一旦习惯了就很难退回 REST。如果你准备用 t3code 起步自己的项目我的建议是别一股脑复制大项目的目录先对照这篇的初始化流程选最小集合跑通再按业务把 router 一个个拆出来。等数据模型稳定了再考虑权限、缓存、上传这些扩展能力。踩坑嘛肯定还会踩但只要每次都有一个像“先看日志再改代码”“环境变量显式固定”这样的复盘动作坑就会越踩越少。
