最近常被问到一个问题——“你项目里的 t3code 到底是什么” 每次我都要从头解释一遍 T3 Stack 的来历以及为什么我最终把团队内部知识库搭在这套组合上。t3code 在这个语境下可以理解为一套基于 T3 Stack 的全栈 TypeScript 工程实践前端 Next.js接口层 tRPC数据层 Prisma认证交给 NextAuth样式交给 Tailwind CSS。它最大的价值不是某一项技术多炫而是“前端、接口、数据库全程类型安全”这件事真正落到了日常开发里。这篇文章写给两类人一类是想看懂 t3code 但被各种英文缩写劝退的新手另一类是已经在用 create-t3-app 却总在边界问题上卡壳的开发者。我会尽量把选型逻辑、代码组织、认证权限、部署排错这些环节拆开讲清楚全部基于我真实跑过的项目流程可复现。1. 为什么是“t3code”从一次内部项目选型说起1.1 全栈类型安全的长期价值我们当时的项目是一个给团队内部用的知识库功能不多登录、文章列表、文章详情、写文章、标签筛选、管理员审核。按传统做法三周能做完但我有个强烈诉求——未来半年这个项目会频繁加功能前后端如果各写各的类型定义改一次接口就要同步改两处时间一长肯定漂移。t3code 这类实践解决的就是这个漂移问题。整个调用链路由一套 TypeScript 类型贯通客户端调用一个函数函数本身来自服务端 router 定义输入输出类型自动推导不靠手写。这就像前后端共用同一份接口合同并且这个合同由编译器强制检查。改动服务端接口定义后客户端立刻出现类型报错逼着你去处理而不是靠人肉维护文档。当然你也可以说“我写后端 Java 也有类型”但问题在于前后端之间那一层通常没有强约束。REST API 返回什么类型前端只能靠文档或手写 interface。t3code 把事情压缩成类型只在服务端定义一次从数据库查询结果一直到 React 组件里的data类型不散。1.2 tRPC、GraphQL、REST我为什么放弃后两者我在早期方案里认真考虑过 REST OpenAPI还专门试过 GraphQL codegen。这里给一个对比可能对正在选型的人有帮助方案类型安全共享程度学习成本适合场景团队约束REST OpenAPI需要手写/生成客户端容易漂移中对外公开 API多语言客户端需要严格的 schema 治理长期维护GraphQL codegen强代码生成可靠高复杂聚合查询、多端消费需要维护 GraphQL schema、resolver 体系tRPC极强完全自动推导低全栈 TypeScript 的内部/中小型应用基本限定在 TypeScript 前后端我们的内部知识库明显不属于前两类。它不需要对外提供 REST 接口也不需要 GraphQL 那套 schema 治理能力。tRPC 最合适因为团队本身是 TypeScript 为主前后端共享类型这件事的收益远大于框架本身的学习成本。1.3 t3code 代表的工程边界再明确一下 t3code 的工程含义。它不仅是package.json里那一组依赖还包括目录规范、环境变量校验、认证上下文注入、数据访问边界等约定。脚手架 create-t3-app 只是起点重点是形成一套“让类型安全在真实工程里稳定运行”的组织规则。从这次选型得出的结论是与其把工程约束散落在同事的脑子和微信群消息里不如把路由规范、错误码规范、数据库访问规范都写进项目初始模板。这也是 t3code 作为一套实践集合比单一框架更有价值的地方。2. 初始化一个 t3code 工程脚手架与目录规则2.1 create-t3-app 初始化手记我当时用的命令很常规但有几个前置检查容易忽略。node -v # 确保 18.17 以上最好用 LTS 版本 pnpm --version # 建议 8.x 以上 pnpm create t3-applatest my-kb为什么推荐 pnpm因为依赖安装更快node_modules 的隔离更严格create-t3-app 对 pnpm 支持也最好。初始化时交互式选择项按项目需要勾选我选了App RouterTailwind CSSPrismatRPCNextAuth.js生成后的核心目录结构大致如下App Router 版本和 Pages Router 版本略有差异我这里以 App Router 版本为主src/ app/ api/trpc/[trpc]/route.ts layout.tsx page.tsx server/ api/ root.ts routers/ auth.ts db.ts trpc/ server.ts react.tsx env.js这里我要提醒一句不同版本的 create-t3-app 生成的目录不一定完全一样尤其是 tRPC v11 和 NextAuth v4/v5 的版本差异会导致配置方式不同。看到别人的 demo 代码结构和你不一样先看版本号别急着照抄。2.2 env.js 到底在保护什么create-t3-app 默认生成env.js用 zod 对环境变量做运行时校验。为什么要强制校验因为常见的线上事故都是环境变量缺失导致运行时模糊报错。比如DATABASE_URL没配Prisma 启动时给一个“找不到数据库”的错你得花时间猜。而 env 校验可以在进程启动阶段就明确告诉你缺了哪个字段。const server envSchema.extend({ DATABASE_URL: z.string().url(), AUTH_SECRET: z.string().min(32), });我的经验是新增任何环境变量第一件事就是同步更新env.js并同步更新.env.example。如果你用 Next.js 旧版习惯环境变量名要加NEXT_PUBLIC_前缀才能在浏览器访问但 create-t3-app 的 env 配置里对客户端变量有专门校验。我强烈建议所有发给浏览器的变量都集中到这里管理而不是散落在代码里随手process.env。这个文件最容易被新人当成麻烦删掉或改宽松。我踩过这个坑早期图省事把 schema 改成宽松模式结果线上一半功能因为漏配变量跑不起来排查了很久才想起是环境变量校验被自己绕过了。强制校验本质上是把配置错误提前到启动阶段暴露。2.3 目录边界src/server、src/trpc、src/app 的分工这套目录规范的核心约束是代码层面的访问边界src/server只放服务端代码不能从客户端 import否则数据库密码这类配置会打进浏览器包。src/trpc提供服务端和客户端通用的 tRPC 工具函数包括鉴权中间件。src/app是 Next.js App Router 的页面与路由处理。实践里我习惯在src/server下的文件顶部加import server-only这是 Next.js 提供的编译期保护。如果有人误在组件里 import 了服务端模块构建直接报错比靠 code review 强制约束可靠得多。这也是 t3code 工程化细节里比较重要的一条把约束写进代码而不是写进文档。3. tRPC 主链路从 Router 到客户端类型推导3.1 定义 Context 与第一组 ProceduretRPC 的 Context 是每个请求进来时先执行的一段逻辑返回值会注入所有 procedure。我在内部知识库里就是从这里把 Prisma client 和登录 session 挂进去。import type { CreateNextContextOptions } from trpc/server/adapters/next; import { getServerSession } from next-auth; import { authOptions } from ~/server/auth; import { prisma } from ~/server/db; export const createContext async (opts: CreateNextContextOptions) { const session await getServerSession(opts.req, opts.res, authOptions); return { prisma, session }; }; export type Context AwaitedReturnTypetypeof createContext;接着初始化 tRPC 实例import { TRPCError, initTRPC } from trpc/server; import type { Context } from ~/server/api/context; const t initTRPC.contextContext().create(); export const router t.router; export const publicProcedure t.procedure; export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session || !ctx.session.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next(); });protectedProcedure 用中间件实现而不是在每个 router 里手动判断 session。权限属于公共逻辑抽出来之后任何 router 都能复用。写多了你会发现tRPC 的中间件模式很像 Express 的洋葱模型但它天然带着类型信息每个中间件修改 context 类型时后续 procedure 也能推出来。3.2 写一个业务 Router查询与变更的完整示例一个简单的文章模块长这样import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ~/server/api/trpc; export const postRouter createTRPCRouter({ list: publicProcedure .input(z.object({ tag: z.string().optional() })) .query(async ({ ctx, input }) { return ctx.prisma.post.findMany({ where: input.tag ? { tags: { some: { name: input.tag } } } : undefined, include: { author: { select: { name: true } } }, orderBy: { createdAt: desc }, take: 20, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1) })) .mutation(async ({ ctx, input }) { return ctx.prisma.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });query 用于读mutation 用于写client 端会对应生成useQuery和useMutation行为自动化。input 用 zod 定义所有校验在进入业务代码前完成返回值类型由你写回调时决定客户端会自动拿到完整类型。一个小细节createTRPCRouter是新版推荐写法老版本经常看到router({...})本质等价。不用看到不同代码就慌按你当前依赖版本走。3.3 客户端接入与类型推导的实际体验客户端设置只需要一行核心代码import { createTRPCRReact } from trpc/react-query; import type { AppRouter } from ~/server/api/root; export const api createTRPCRReactAppRouter();组件里调用use client; const { data, isLoading } api.post.list.useQuery({ tag: nextjs });实际体验就是当我改动服务端list查询的 input 结构组件里的useQuery参数立刻标红当我改变返回记录字段data的类型同步变化。这种“改一处、处处提醒”的体验是过去 REST 时代很难实现的。这也解释了为什么我用过之后很难回去手写 API 类型。3.4 文件变多后的 Router 合并策略当业务模块多起来router 文件按业务域拆routers/ post.ts user.ts admin.ts comment.tsroot.ts 里合并export const appRouter createTRPCRouter({ post: postRouter, user: userRouter, admin: adminRouter, comment: commentRouter, }); export type AppRouter typeof appRouter;这样客户端调用路径就是api.post.list、api.admin.someQuery在操作日志里也很容易追踪。我习惯一个业务域一个文件文件内再按“读/写/管理”分组而不是一个巨型 router 堆上百个 procedure否则类型文件大了以后 IDE 提示会明显变慢。4. Prisma 数据层接进来建模、迁移与服务端查询4.1 Schema 设计与迁移流程内部知识库的表结构用 Prisma Schema 定义model User { id String id default(cuid()) name String? email String unique posts Post[] } model Post { id String id default(cuid()) title String content String authorId String author User relation(fields: [authorId], references: [id]) tags TagOnPost[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Tag { id String id default(cuid()) name String unique posts TagOnPost[] } model TagOnPost { postId String post Post relation(fields: [postId], references: [id]) tagId String tag Tag relation(fields: [tagId], references: [id]) id([postId, tagId]) }这里多说一句多对多Prisma 支持隐式关系表但内部知识库我故意用了显式的TagOnPost中间表因为将来要扩展“谁给文章打的标签”这类字段。显式中间表能让 schema 更灵活缺点是要多写几行但长期维护更舒服。迁移命令是pnpm prisma migrate dev --name init pnpm prisma db seedmigrate dev和db push的区别很关键。开发期migrate dev会生成迁移文件并同步 schemadb push只是把 schema 直接推上去不生成历史。很多人图省事在开发时用 db push但生产环境必须有迁移历史否则同事拉代码后数据库版本对不上。我现在的习惯是开发阶段也用migrate dev让迁移文件从一开始就完整。4.2 在 tRPC 中查询和写数据的标准姿势数据访问层有一些长期适用的规则列表查询只返回需要的字段用select而不是一把梭include全部关联。列表接口必须给take分页参数不能一上来查全表。关联数据按需裁剪不要把rawContent、内部备注这类字段返回给前端。我早期犯过一个典型错误列表接口把 Post 的完整正文也返回了结果页面只是展示标题network payload 翻了一倍。后来在list查询里用select裁剪字段体感明显变快。这个问题和 tRPC 本身无关但 tRPC 的类型推导很强大反而容易让你忽略“返回数据是否真的需要这么大”。另外记得改 schema 后必须跑pnpm prisma generate否则 tRPC 返回的类型还是旧的。你如果发现类型和数据库不一致第一反应是重新 generate而不是怀疑代码。4.3 zod 校验与 TRPCError错误响应的边界控制写一个有权限校验的更新接口update: protectedProcedure .input( z.object({ id: z.string().cuid(), title: z.string().min(1).max(200), }) ) .mutation(async ({ ctx, input }) { const post await ctx.prisma.post.findUnique({ where: { id: input.id }, }); if (!post || post.authorId ! ctx.session.user.id) { throw new TRPCError({ code: FORBIDDEN, message: 只能编辑自己的文章 }); } return ctx.prisma.post.update({ where: { id: input.id }, data: { title: input.title }, }); }),错误码的分工很重要zod 校验失败会自动转成BAD_REQUEST未登录走UNAUTHORIZED无权限走FORBIDDEN业务逻辑异常再考虑INTERNAL_SERVER_ERROR。不要把非法操作全部抛成 500否则前端错误处理分支没法写排查问题也更困难。tRPC 的 errorFormatter 在生产环境建议把堆栈信息去掉只保留 code 和 message。否则错误详情直接暴露给浏览器等于是给攻击者递信息。我第一次上线时忘了改这个还好是内部工具没有造成实际损失但教训深刻。5. NextAuth 认证与权限控制的完整接入过程5.1 Provider 配置与 Session 策略选型内部知识库用 GitHub 登录就够了配置如下import type { NextAuthOptions } from next-auth; import GitHub from next-auth/providers/github; export const authOptions: NextAuthOptions { session: { strategy: jwt }, providers: [ GitHub({ clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, }), ], callbacks: { async jwt({ token, user }) { if (user) { const dbUser await prisma.user.findUnique({ where: { email: user.email! }, }); token.role dbUser?.role ?? USER; } return token; }, async session({ session, token }) { if (session.user) { session.user.id token.sub!; session.user.role token.role as string; } return session; }, }, };为什么用 JWT 策略而不是 database session因为内部知识库没有“踢人下线”的硬需求JWT 比 database session 少一次数据库查询在 serverless 环境下体验更好。将来如果需要强制会话失效再切也不难。第一个易踩的坑是 GitHub Provider 的回调地址。本地开发时必须在 GitHub OAuth App 设置里填http://localhost:3000/api/auth/callback/github线上填https://域名/api/auth/callback/github。我第一次配的时候忘了改本地回调授权结束后浏览器一直跳回首页但登录不进去看日志才发现是 callback URL 不匹配。5.2 服务端鉴权protectedProcedure 是怎么保护路由的上面章节里已经定义了protectedProcedure这里展开讲它在真实业务里的用法。以管理员审核接口为例export const requireAdmin protectedProcedure.use(({ ctx, next }) { const role ctx.session.user.role; if (role ! ADMIN) { throw new TRPCError({ code: FORBIDDEN }); } return next(); }); export const adminRouter createTRPCRouter({ listPending: requireAdmin.query(async ({ ctx }) { return ctx.prisma.post.findMany({ where: { status: PENDING }, take: 50, }); }), });路由层把权限卡住之后handler 里不需要再重复判断角色。每个请求都从 Context 里拿 session而 session 里的 role 是在 jwt callback 里从数据库查出来写进 token 的。注意 role 不会自动出现在 NextAuth 的 session 里必须自己通过 callback 扩展。5.3 NextAuth 升级与前端鉴权的边界版本升级是个大坑NextAuth v4 和 v5也就是 Auth.js的配置方式差异不小中间件、getServerSession、route handler 的用法都有变化。如果项目要升级先看 release notes别把 v4 的配置直接搬过去。前端鉴权我这里多说一句useSession在客户端渲染时一开始是 loading 状态直接拿 session 数据做条件渲染页面会闪一下。我的做法是页面级权限用服务端组件配合getServerSession判断客户端只处理交互性权限比如“是否显示编辑按钮”。这样可以避免登录态闪烁也减少客户端暴露权限判断逻辑。6. 部署到生产环境Vercel 与自托管分别怎么处理6.1 Vercel 部署清单与 Prisma 连接池问题在 Vercel 上部署前环境变量清单要齐全变量用途是否暴露到浏览器DATABASE_URLPrisma 连接数据库否AUTH_SECRETNextAuth 加密 JWT否GITHUB_CLIENT_IDGitHub OAuth 客户端 ID否GITHUB_CLIENT_SECRETGitHub OAuth 客户端密钥否AUTH_TRUST_HOSTNextAuth v5 部署需要否Prisma 在 serverless 下的连接池问题是最容易被忽视的。Vercel 上每个函数实例都会创建数据库连接如果直接用单个 PostgreSQL 连接串并发稍高就会出现too many connections。解决方式是使用支持连接池的地址比如 Neon、Supabase 提供的池化连接串或者自己部署 PgBouncer。我上线第一晚被这个告警打醒最后换了池化连接串并给列表查询加了分页才算稳定下来。6.2 Docker 自托管时容易漏的迁移与启动步骤如果不用 VercelDocker 自托管会有一堆更麻烦的细节。常见问题按频率排镜像构建时没有执行prisma generate导致 Prisma Client 找不到数据库引擎。启动时没有执行prisma migrate deploy数据库 schema 落后于代码。AUTH_SECRET没有持久化容器重启后 secret 变了所有用户 session 全部失效。Nginx 反向代理没调大client_max_body_size大请求直接被 413 挡掉。所以我现在的 Dockerfile 和启动脚本固定包含这些步骤# 构建阶段 pnpm prisma generate pnpm next build # 启动前 pnpm prisma migrate deploy node server.jsAUTH_SECRET用固定随机值写进环境变量不随容器重建变化。否则每次发布都是全员重新登录用户会很崩溃。6.3 上线后遇到的三个真实故障复盘这一节讲三个我实际踩过的故障重点是排查链路不是直接给答案。第一个故障登录后一直跳回登录页。当时的排查链路是先看网络请求发现/api/auth/session返回 200 但 session 为空再看 NextAuth 日志发现 JWT 解密失败。原因是首次部署时没设置AUTH_SECRETNextAuth 用了随机生成的默认值每次实例重启 secret 都不一样已经签发的 JWT 全部失效。修复方案是固定 secret并让用户重新登录。第二个故障Prisma 连接数打满。排查时先看数据库连接数指标日志里出现remaining connection slots are reserved再对应到代码里是列表页在客户端轮询每个请求都新建连接连接池被占满。修复方案是去掉轮询改用服务端刷新并给数据库连接池增加上限。第三个故障tRPC mutation 偶尔返回 500。这个最隐蔽排查时发现大 JSON 请求会被代理层拦截Nginx 默认client_max_body_size是 1MBtRPC 的 JSON payload 稍大就 413但前端收到了泛化的 500。修复方案是调整 Nginx 配置同时把图片上传改成对象存储直传应用只存 key不往 tRPC 里塞 base64。这个思路对任何全栈应用都适用大文件永远别走业务接口。7. 沉淀成团队脚手架t3code 的推广与边界7.1 从单个项目到团队模板当团队里其他项目也想采用 t3code 时我没有直接把项目仓库复制过去而是做了三件事把初始化后的项目整理成组织级模板固定依赖版本避免每个项目依赖漂移。写一份CONTRIBUTING.md说明新增路由、新增模型、新增环境变量的标准流程。统一 eslint、prettier、tsconfig用共享配置文件管理而不是各自维护一份。还定了一条规矩T3 全家桶里每个包独立演进升级时一次只动一个依赖跑通回归再动下一个。一次性升级 Next.js、tRPC、Prisma 三个大版本基本等于给自己找三天麻烦。7.2 哪些项目不适合硬上 t3code不是所有项目都适合 t3code我用下来的判断边界是静态展示站纯静态页面不需要后端Next.js Tailwind 就够加 tRPC 和 Prisma 是纯负担。对外开放的重 API 服务需要多语言客户端REST OpenAPI 更合适。数据仓库或报表类应用复杂 SQL 聚合多GraphQL 或专门的 BFF 层更顺手。团队完全没有 TypeScript 基础短期要交付的落地页也不必强行引入全栈类型体系。t3code 收益最大的是“改动频繁的中小型全栈应用”——内部工具、SaaS 前端、后台管理这类。每次改后端字段时前端立刻收到编译器的提醒这比自动化文档可靠多了。我自己实践下来的最大体会是t3code 真正的门槛不在于装依赖而在于约束自己遵守类型安全约定。环境变量集中校验、服务端模块禁止客户端引用、权限走中间件、列表查询加分页这些规则每条单独看都很简单组合起来才是它稳定运行的基础。最后分享一个推广技巧如果你要在团队里落地这套实践先挑一个小项目跑一个迭代把目录规范和环境变量清单写进 README然后再铺开。一上来就要求所有项目统一反而容易让团队觉得 TypeScript 全栈的复杂度陡增。
最近常被问到一个问题——“你项目里的 t3code 到底是什么” 每次我都要从头解释一遍 T3 Stack 的来历以及为什么我最终把团队内部知识库搭在这套组合上。t3code 在这个语境下可以理解为一套基于 T3 Stack 的全栈 TypeScript 工程实践前端 Next.js接口层 tRPC数据层 Prisma认证交给 NextAuth样式交给 Tailwind CSS。它最大的价值不是某一项技术多炫而是“前端、接口、数据库全程类型安全”这件事真正落到了日常开发里。这篇文章写给两类人一类是想看懂 t3code 但被各种英文缩写劝退的新手另一类是已经在用 create-t3-app 却总在边界问题上卡壳的开发者。我会尽量把选型逻辑、代码组织、认证权限、部署排错这些环节拆开讲清楚全部基于我真实跑过的项目流程可复现。1. 为什么是“t3code”从一次内部项目选型说起1.1 全栈类型安全的长期价值我们当时的项目是一个给团队内部用的知识库功能不多登录、文章列表、文章详情、写文章、标签筛选、管理员审核。按传统做法三周能做完但我有个强烈诉求——未来半年这个项目会频繁加功能前后端如果各写各的类型定义改一次接口就要同步改两处时间一长肯定漂移。t3code 这类实践解决的就是这个漂移问题。整个调用链路由一套 TypeScript 类型贯通客户端调用一个函数函数本身来自服务端 router 定义输入输出类型自动推导不靠手写。这就像前后端共用同一份接口合同并且这个合同由编译器强制检查。改动服务端接口定义后客户端立刻出现类型报错逼着你去处理而不是靠人肉维护文档。当然你也可以说“我写后端 Java 也有类型”但问题在于前后端之间那一层通常没有强约束。REST API 返回什么类型前端只能靠文档或手写 interface。t3code 把事情压缩成类型只在服务端定义一次从数据库查询结果一直到 React 组件里的data类型不散。1.2 tRPC、GraphQL、REST我为什么放弃后两者我在早期方案里认真考虑过 REST OpenAPI还专门试过 GraphQL codegen。这里给一个对比可能对正在选型的人有帮助方案类型安全共享程度学习成本适合场景团队约束REST OpenAPI需要手写/生成客户端容易漂移中对外公开 API多语言客户端需要严格的 schema 治理长期维护GraphQL codegen强代码生成可靠高复杂聚合查询、多端消费需要维护 GraphQL schema、resolver 体系tRPC极强完全自动推导低全栈 TypeScript 的内部/中小型应用基本限定在 TypeScript 前后端我们的内部知识库明显不属于前两类。它不需要对外提供 REST 接口也不需要 GraphQL 那套 schema 治理能力。tRPC 最合适因为团队本身是 TypeScript 为主前后端共享类型这件事的收益远大于框架本身的学习成本。1.3 t3code 代表的工程边界再明确一下 t3code 的工程含义。它不仅是package.json里那一组依赖还包括目录规范、环境变量校验、认证上下文注入、数据访问边界等约定。脚手架 create-t3-app 只是起点重点是形成一套“让类型安全在真实工程里稳定运行”的组织规则。从这次选型得出的结论是与其把工程约束散落在同事的脑子和微信群消息里不如把路由规范、错误码规范、数据库访问规范都写进项目初始模板。这也是 t3code 作为一套实践集合比单一框架更有价值的地方。2. 初始化一个 t3code 工程脚手架与目录规则2.1 create-t3-app 初始化手记我当时用的命令很常规但有几个前置检查容易忽略。node -v # 确保 18.17 以上最好用 LTS 版本 pnpm --version # 建议 8.x 以上 pnpm create t3-applatest my-kb为什么推荐 pnpm因为依赖安装更快node_modules 的隔离更严格create-t3-app 对 pnpm 支持也最好。初始化时交互式选择项按项目需要勾选我选了App RouterTailwind CSSPrismatRPCNextAuth.js生成后的核心目录结构大致如下App Router 版本和 Pages Router 版本略有差异我这里以 App Router 版本为主src/ app/ api/trpc/[trpc]/route.ts layout.tsx page.tsx server/ api/ root.ts routers/ auth.ts db.ts trpc/ server.ts react.tsx env.js这里我要提醒一句不同版本的 create-t3-app 生成的目录不一定完全一样尤其是 tRPC v11 和 NextAuth v4/v5 的版本差异会导致配置方式不同。看到别人的 demo 代码结构和你不一样先看版本号别急着照抄。2.2 env.js 到底在保护什么create-t3-app 默认生成env.js用 zod 对环境变量做运行时校验。为什么要强制校验因为常见的线上事故都是环境变量缺失导致运行时模糊报错。比如DATABASE_URL没配Prisma 启动时给一个“找不到数据库”的错你得花时间猜。而 env 校验可以在进程启动阶段就明确告诉你缺了哪个字段。const server envSchema.extend({ DATABASE_URL: z.string().url(), AUTH_SECRET: z.string().min(32), });我的经验是新增任何环境变量第一件事就是同步更新env.js并同步更新.env.example。如果你用 Next.js 旧版习惯环境变量名要加NEXT_PUBLIC_前缀才能在浏览器访问但 create-t3-app 的 env 配置里对客户端变量有专门校验。我强烈建议所有发给浏览器的变量都集中到这里管理而不是散落在代码里随手process.env。这个文件最容易被新人当成麻烦删掉或改宽松。我踩过这个坑早期图省事把 schema 改成宽松模式结果线上一半功能因为漏配变量跑不起来排查了很久才想起是环境变量校验被自己绕过了。强制校验本质上是把配置错误提前到启动阶段暴露。2.3 目录边界src/server、src/trpc、src/app 的分工这套目录规范的核心约束是代码层面的访问边界src/server只放服务端代码不能从客户端 import否则数据库密码这类配置会打进浏览器包。src/trpc提供服务端和客户端通用的 tRPC 工具函数包括鉴权中间件。src/app是 Next.js App Router 的页面与路由处理。实践里我习惯在src/server下的文件顶部加import server-only这是 Next.js 提供的编译期保护。如果有人误在组件里 import 了服务端模块构建直接报错比靠 code review 强制约束可靠得多。这也是 t3code 工程化细节里比较重要的一条把约束写进代码而不是写进文档。3. tRPC 主链路从 Router 到客户端类型推导3.1 定义 Context 与第一组 ProceduretRPC 的 Context 是每个请求进来时先执行的一段逻辑返回值会注入所有 procedure。我在内部知识库里就是从这里把 Prisma client 和登录 session 挂进去。import type { CreateNextContextOptions } from trpc/server/adapters/next; import { getServerSession } from next-auth; import { authOptions } from ~/server/auth; import { prisma } from ~/server/db; export const createContext async (opts: CreateNextContextOptions) { const session await getServerSession(opts.req, opts.res, authOptions); return { prisma, session }; }; export type Context AwaitedReturnTypetypeof createContext;接着初始化 tRPC 实例import { TRPCError, initTRPC } from trpc/server; import type { Context } from ~/server/api/context; const t initTRPC.contextContext().create(); export const router t.router; export const publicProcedure t.procedure; export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session || !ctx.session.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next(); });protectedProcedure 用中间件实现而不是在每个 router 里手动判断 session。权限属于公共逻辑抽出来之后任何 router 都能复用。写多了你会发现tRPC 的中间件模式很像 Express 的洋葱模型但它天然带着类型信息每个中间件修改 context 类型时后续 procedure 也能推出来。3.2 写一个业务 Router查询与变更的完整示例一个简单的文章模块长这样import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ~/server/api/trpc; export const postRouter createTRPCRouter({ list: publicProcedure .input(z.object({ tag: z.string().optional() })) .query(async ({ ctx, input }) { return ctx.prisma.post.findMany({ where: input.tag ? { tags: { some: { name: input.tag } } } : undefined, include: { author: { select: { name: true } } }, orderBy: { createdAt: desc }, take: 20, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1) })) .mutation(async ({ ctx, input }) { return ctx.prisma.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });query 用于读mutation 用于写client 端会对应生成useQuery和useMutation行为自动化。input 用 zod 定义所有校验在进入业务代码前完成返回值类型由你写回调时决定客户端会自动拿到完整类型。一个小细节createTRPCRouter是新版推荐写法老版本经常看到router({...})本质等价。不用看到不同代码就慌按你当前依赖版本走。3.3 客户端接入与类型推导的实际体验客户端设置只需要一行核心代码import { createTRPCRReact } from trpc/react-query; import type { AppRouter } from ~/server/api/root; export const api createTRPCRReactAppRouter();组件里调用use client; const { data, isLoading } api.post.list.useQuery({ tag: nextjs });实际体验就是当我改动服务端list查询的 input 结构组件里的useQuery参数立刻标红当我改变返回记录字段data的类型同步变化。这种“改一处、处处提醒”的体验是过去 REST 时代很难实现的。这也解释了为什么我用过之后很难回去手写 API 类型。3.4 文件变多后的 Router 合并策略当业务模块多起来router 文件按业务域拆routers/ post.ts user.ts admin.ts comment.tsroot.ts 里合并export const appRouter createTRPCRouter({ post: postRouter, user: userRouter, admin: adminRouter, comment: commentRouter, }); export type AppRouter typeof appRouter;这样客户端调用路径就是api.post.list、api.admin.someQuery在操作日志里也很容易追踪。我习惯一个业务域一个文件文件内再按“读/写/管理”分组而不是一个巨型 router 堆上百个 procedure否则类型文件大了以后 IDE 提示会明显变慢。4. Prisma 数据层接进来建模、迁移与服务端查询4.1 Schema 设计与迁移流程内部知识库的表结构用 Prisma Schema 定义model User { id String id default(cuid()) name String? email String unique posts Post[] } model Post { id String id default(cuid()) title String content String authorId String author User relation(fields: [authorId], references: [id]) tags TagOnPost[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Tag { id String id default(cuid()) name String unique posts TagOnPost[] } model TagOnPost { postId String post Post relation(fields: [postId], references: [id]) tagId String tag Tag relation(fields: [tagId], references: [id]) id([postId, tagId]) }这里多说一句多对多Prisma 支持隐式关系表但内部知识库我故意用了显式的TagOnPost中间表因为将来要扩展“谁给文章打的标签”这类字段。显式中间表能让 schema 更灵活缺点是要多写几行但长期维护更舒服。迁移命令是pnpm prisma migrate dev --name init pnpm prisma db seedmigrate dev和db push的区别很关键。开发期migrate dev会生成迁移文件并同步 schemadb push只是把 schema 直接推上去不生成历史。很多人图省事在开发时用 db push但生产环境必须有迁移历史否则同事拉代码后数据库版本对不上。我现在的习惯是开发阶段也用migrate dev让迁移文件从一开始就完整。4.2 在 tRPC 中查询和写数据的标准姿势数据访问层有一些长期适用的规则列表查询只返回需要的字段用select而不是一把梭include全部关联。列表接口必须给take分页参数不能一上来查全表。关联数据按需裁剪不要把rawContent、内部备注这类字段返回给前端。我早期犯过一个典型错误列表接口把 Post 的完整正文也返回了结果页面只是展示标题network payload 翻了一倍。后来在list查询里用select裁剪字段体感明显变快。这个问题和 tRPC 本身无关但 tRPC 的类型推导很强大反而容易让你忽略“返回数据是否真的需要这么大”。另外记得改 schema 后必须跑pnpm prisma generate否则 tRPC 返回的类型还是旧的。你如果发现类型和数据库不一致第一反应是重新 generate而不是怀疑代码。4.3 zod 校验与 TRPCError错误响应的边界控制写一个有权限校验的更新接口update: protectedProcedure .input( z.object({ id: z.string().cuid(), title: z.string().min(1).max(200), }) ) .mutation(async ({ ctx, input }) { const post await ctx.prisma.post.findUnique({ where: { id: input.id }, }); if (!post || post.authorId ! ctx.session.user.id) { throw new TRPCError({ code: FORBIDDEN, message: 只能编辑自己的文章 }); } return ctx.prisma.post.update({ where: { id: input.id }, data: { title: input.title }, }); }),错误码的分工很重要zod 校验失败会自动转成BAD_REQUEST未登录走UNAUTHORIZED无权限走FORBIDDEN业务逻辑异常再考虑INTERNAL_SERVER_ERROR。不要把非法操作全部抛成 500否则前端错误处理分支没法写排查问题也更困难。tRPC 的 errorFormatter 在生产环境建议把堆栈信息去掉只保留 code 和 message。否则错误详情直接暴露给浏览器等于是给攻击者递信息。我第一次上线时忘了改这个还好是内部工具没有造成实际损失但教训深刻。5. NextAuth 认证与权限控制的完整接入过程5.1 Provider 配置与 Session 策略选型内部知识库用 GitHub 登录就够了配置如下import type { NextAuthOptions } from next-auth; import GitHub from next-auth/providers/github; export const authOptions: NextAuthOptions { session: { strategy: jwt }, providers: [ GitHub({ clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, }), ], callbacks: { async jwt({ token, user }) { if (user) { const dbUser await prisma.user.findUnique({ where: { email: user.email! }, }); token.role dbUser?.role ?? USER; } return token; }, async session({ session, token }) { if (session.user) { session.user.id token.sub!; session.user.role token.role as string; } return session; }, }, };为什么用 JWT 策略而不是 database session因为内部知识库没有“踢人下线”的硬需求JWT 比 database session 少一次数据库查询在 serverless 环境下体验更好。将来如果需要强制会话失效再切也不难。第一个易踩的坑是 GitHub Provider 的回调地址。本地开发时必须在 GitHub OAuth App 设置里填http://localhost:3000/api/auth/callback/github线上填https://域名/api/auth/callback/github。我第一次配的时候忘了改本地回调授权结束后浏览器一直跳回首页但登录不进去看日志才发现是 callback URL 不匹配。5.2 服务端鉴权protectedProcedure 是怎么保护路由的上面章节里已经定义了protectedProcedure这里展开讲它在真实业务里的用法。以管理员审核接口为例export const requireAdmin protectedProcedure.use(({ ctx, next }) { const role ctx.session.user.role; if (role ! ADMIN) { throw new TRPCError({ code: FORBIDDEN }); } return next(); }); export const adminRouter createTRPCRouter({ listPending: requireAdmin.query(async ({ ctx }) { return ctx.prisma.post.findMany({ where: { status: PENDING }, take: 50, }); }), });路由层把权限卡住之后handler 里不需要再重复判断角色。每个请求都从 Context 里拿 session而 session 里的 role 是在 jwt callback 里从数据库查出来写进 token 的。注意 role 不会自动出现在 NextAuth 的 session 里必须自己通过 callback 扩展。5.3 NextAuth 升级与前端鉴权的边界版本升级是个大坑NextAuth v4 和 v5也就是 Auth.js的配置方式差异不小中间件、getServerSession、route handler 的用法都有变化。如果项目要升级先看 release notes别把 v4 的配置直接搬过去。前端鉴权我这里多说一句useSession在客户端渲染时一开始是 loading 状态直接拿 session 数据做条件渲染页面会闪一下。我的做法是页面级权限用服务端组件配合getServerSession判断客户端只处理交互性权限比如“是否显示编辑按钮”。这样可以避免登录态闪烁也减少客户端暴露权限判断逻辑。6. 部署到生产环境Vercel 与自托管分别怎么处理6.1 Vercel 部署清单与 Prisma 连接池问题在 Vercel 上部署前环境变量清单要齐全变量用途是否暴露到浏览器DATABASE_URLPrisma 连接数据库否AUTH_SECRETNextAuth 加密 JWT否GITHUB_CLIENT_IDGitHub OAuth 客户端 ID否GITHUB_CLIENT_SECRETGitHub OAuth 客户端密钥否AUTH_TRUST_HOSTNextAuth v5 部署需要否Prisma 在 serverless 下的连接池问题是最容易被忽视的。Vercel 上每个函数实例都会创建数据库连接如果直接用单个 PostgreSQL 连接串并发稍高就会出现too many connections。解决方式是使用支持连接池的地址比如 Neon、Supabase 提供的池化连接串或者自己部署 PgBouncer。我上线第一晚被这个告警打醒最后换了池化连接串并给列表查询加了分页才算稳定下来。6.2 Docker 自托管时容易漏的迁移与启动步骤如果不用 VercelDocker 自托管会有一堆更麻烦的细节。常见问题按频率排镜像构建时没有执行prisma generate导致 Prisma Client 找不到数据库引擎。启动时没有执行prisma migrate deploy数据库 schema 落后于代码。AUTH_SECRET没有持久化容器重启后 secret 变了所有用户 session 全部失效。Nginx 反向代理没调大client_max_body_size大请求直接被 413 挡掉。所以我现在的 Dockerfile 和启动脚本固定包含这些步骤# 构建阶段 pnpm prisma generate pnpm next build # 启动前 pnpm prisma migrate deploy node server.jsAUTH_SECRET用固定随机值写进环境变量不随容器重建变化。否则每次发布都是全员重新登录用户会很崩溃。6.3 上线后遇到的三个真实故障复盘这一节讲三个我实际踩过的故障重点是排查链路不是直接给答案。第一个故障登录后一直跳回登录页。当时的排查链路是先看网络请求发现/api/auth/session返回 200 但 session 为空再看 NextAuth 日志发现 JWT 解密失败。原因是首次部署时没设置AUTH_SECRETNextAuth 用了随机生成的默认值每次实例重启 secret 都不一样已经签发的 JWT 全部失效。修复方案是固定 secret并让用户重新登录。第二个故障Prisma 连接数打满。排查时先看数据库连接数指标日志里出现remaining connection slots are reserved再对应到代码里是列表页在客户端轮询每个请求都新建连接连接池被占满。修复方案是去掉轮询改用服务端刷新并给数据库连接池增加上限。第三个故障tRPC mutation 偶尔返回 500。这个最隐蔽排查时发现大 JSON 请求会被代理层拦截Nginx 默认client_max_body_size是 1MBtRPC 的 JSON payload 稍大就 413但前端收到了泛化的 500。修复方案是调整 Nginx 配置同时把图片上传改成对象存储直传应用只存 key不往 tRPC 里塞 base64。这个思路对任何全栈应用都适用大文件永远别走业务接口。7. 沉淀成团队脚手架t3code 的推广与边界7.1 从单个项目到团队模板当团队里其他项目也想采用 t3code 时我没有直接把项目仓库复制过去而是做了三件事把初始化后的项目整理成组织级模板固定依赖版本避免每个项目依赖漂移。写一份CONTRIBUTING.md说明新增路由、新增模型、新增环境变量的标准流程。统一 eslint、prettier、tsconfig用共享配置文件管理而不是各自维护一份。还定了一条规矩T3 全家桶里每个包独立演进升级时一次只动一个依赖跑通回归再动下一个。一次性升级 Next.js、tRPC、Prisma 三个大版本基本等于给自己找三天麻烦。7.2 哪些项目不适合硬上 t3code不是所有项目都适合 t3code我用下来的判断边界是静态展示站纯静态页面不需要后端Next.js Tailwind 就够加 tRPC 和 Prisma 是纯负担。对外开放的重 API 服务需要多语言客户端REST OpenAPI 更合适。数据仓库或报表类应用复杂 SQL 聚合多GraphQL 或专门的 BFF 层更顺手。团队完全没有 TypeScript 基础短期要交付的落地页也不必强行引入全栈类型体系。t3code 收益最大的是“改动频繁的中小型全栈应用”——内部工具、SaaS 前端、后台管理这类。每次改后端字段时前端立刻收到编译器的提醒这比自动化文档可靠多了。我自己实践下来的最大体会是t3code 真正的门槛不在于装依赖而在于约束自己遵守类型安全约定。环境变量集中校验、服务端模块禁止客户端引用、权限走中间件、列表查询加分页这些规则每条单独看都很简单组合起来才是它稳定运行的基础。最后分享一个推广技巧如果你要在团队里落地这套实践先挑一个小项目跑一个迭代把目录规范和环境变量清单写进 README然后再铺开。一上来就要求所有项目统一反而容易让团队觉得 TypeScript 全栈的复杂度陡增。
