刚开始接触 t3code 这个项目名时很多人会下意识问一句这到底是个库、一个框架还是一个网站的代号我的答案是它既不是某个开源工具的名字也不是一个组织推出的新产品而是一个全栈项目的仓库名。当时我给这个项目起名叫 t3code是因为项目底层采用了 T3 技术栈Next.js、TypeScript、tRPC、Tailwind CSS 这些核心组合而 code 则代表整个仓库的核心使命——不追求花哨的界面把尽可能多的真实业务场景用干净、类型安全的代码串起来。这篇内容适合两类人看。第一类是正在纠结全栈技术选型的人尤其是不确定前后端到底要不要分离类型安全到底值不值得花时间的开发者第二类是已经听说过 tRPC 和 T3 栈但还没真正跑过一遍完整项目、想看看真实落地时有哪些坑的实践者。我不会去讲那些官方文档里已经写得很清楚的基础概念而是以 t3code 这个项目从初始化、建模、认证到部署的完整推进过程为线索把每一步的取舍理由、踩坑记录、优化方案都摊开来聊。1. 从T3到t3code这个项目名背后是一套完整的选型逻辑1.1 T3 不是什么新框架而是一种类型安全优先的工程理念先说清楚一个容易混淆的地方T3 Stack 并不是某个团队开发的统一框架而是一套由开发者社区总结出来的技术组合思路。它的核心倡议很简单——在你构建全栈应用时把类型安全放到最高优先级让 TypeScript 的类型系统从左到右贯穿整个链路数据库 schema、服务端 API、前端请求调用、组件 props全都由一份类型推导出来。t3code 这个项目就是在这一理念下诞生的。我的目标是做一个类似个人笔记 轻量发布的 Web 应用用户注册、登录后能创建笔记、修改笔记、查看自己的内容列表。这类业务用传统方式做通常要写三样东西数据库表、后端接口、前端接口封装。三个地方各写各的类型定义改一个字段名往往要全局搜索替换好几轮。而 t3code 想验证的就是这种类型穿透到底的方案能不能让整个开发体验简化到一个字段从数据库改到前端只需要动一处。1.2 前后端分离方案的隐性成本恰恰是 t3code 想绕开的我不是说前后端分离不好它在大型团队协作、多端复用、权限隔离等场景下有明显优势。但很多中小型全栈应用选择分离方案时实际付出的隐性成本被严重低估了需要维护一套接口文档Swagger/OpenAPI或者靠约定俗称的口口相传前后端需要各写一份 DTO 类型两边经常出现后端改了字段类型前端还在按 string 处理的错位联调阶段大量时间消耗在接口返回结构又变了这个字段到底可空不可空这类沟通上如果需要通过代码生成工具从前端生成 API 类型整套工具链的接入成本也不小。所以 t3code 从第一天起就选了另一条路把 Next.js 当作前端框架同时用它跑服务端逻辑用 tRPC 替代传统的 REST API 路由让前端组件直接引用后端查询函数用 Prisma 定义数据库模型并把模型类型自动提供给 tRPC。整个过程里TypeScript 是唯一的事实来源。为了更直观地说明差异我整理了一份对比这也是当时选型阶段经常被问到的问题维度传统前后端分离t3codeT3 组合方案类型维护前端、后端、API 文档各一份一份 Prisma schema全链路推导接口联调需要核对 URL、参数、返回结构前端直接调用类型化的服务端函数接口文档依赖 Swagger 或手动维护基本不需要独立文档类型即文档新增一个字段数据库/后端接口/前端类型三处改动改数据库模型类型自动同步复杂度上限适合大型团队、多端复杂生态适合 2-5 人团队、业务明确的全栈项目这里并不是说 T3 方案可以包治百病。如果团队成员超过一定规模或者前端需要独立于服务端部署这套组合的边界就会变得明显。但对于 t3code 这种快速迭代的轻量产品它的收益远远大于成本。2. 初始化 t3code环境准备、目录约定与依赖选择2.1 用交互式脚手架起步但要克制住全选的冲动t3code 的初始化方式我建议直接走官方脚手架命令很简单pnpm dlx create-t3-applatest t3code这个命令会拉取交互式配置让你选择是否包含 NextAuth、Prisma、Tailwind CSS、tRPC 等模块。第一次跑这个命令的人很容易把选项全勾上我后来发现这是一个典型的过度初始化陷阱。全勾意味着脚手架会同时生成认证、数据库、路由、样式、ESLint、环境变量模板等一整套东西目录结构在一开始就会显得很厚重对理解类型安全链路反而造成干扰。我当时的做法是分两次选择。第一次初始化只勾了 Next.js、TypeScript、Tailwind CSS 这三个基础项先让项目跑起来把页面渲染链路和样式体系确认好第二次再通过安装依赖的方式把 Prisma、tRPC、NextAuth 依次加进来。这样每一部分加入时我都明确知道它解决的是什么问题而不是面对一个已经生成完毕的全家桶去反推结构。如果你更习惯手动搭建核心依赖清单大致如下pnpm add trpc/server trpc/client trpc/react-query trpc/next tanstack/react-query zod superjson pnpm add prisma/client prisma --save-dev pnpm add next-auth auth/prisma-adapter bcryptjs注意一点版本不要盲目选 latest。t3code 项目跑通时我遇到过一个非常典型的问题——tRPC v11 和 Next.js 14 App Router 的适配写法与 v10 完全不同。如果你跟着网上一些旧教程安装会拿到一堆过时的 API 用法。建议安装后先看一眼 node_modules 里对应包的版本再决定参考哪套文档。这个习惯能省下你一整天的排查时间。2.2 目录结构不是随便分的它本身就在传递类型源头的思想初始化完成后项目里最有价值的部分其实不是配置代码而是目录约定。t3code 采用了 T3 脚手架推荐的分层方式prisma/ schema.prisma # 数据库模型全链路类型的源头 src/ app/ # Next.js App Router 的页面与布局 pages/api/ # 服务端 API 路由入口trpc、auth 挂载点 server/ auth.ts # NextAuth 配置 db.ts # Prisma Client 单例 api/ routers/ # tRPC 路由定义 root.ts # 根路由汇总 trpc.ts # tRPC 上下文与初始化 components/ # 前端组件 lib/ # 共享工具这套结构最核心的一个思想是所有类型都从prisma/schema.prisma出发流向src/server再流向src/components。你不可能在前端组件里凭空定义一份游离的接口类型因为组件拿到的数据来源就是 tRPC 的返回类型而 tRPC 的返回类型又由 Prisma 模型决定。用一句话概括目录结构本身就是类型安全链路的地图。看懂了这个分层后续写代码就不会迷路。3. 类型安全链路实战Prisma、tRPC 与前端组件如何无缝衔接3.1 用 Prisma 定义业务模型字段可空性和关联关系是第一道关卡t3code 的业务模型非常简单只有两个核心实体用户User和笔记Note一个用户拥有多条笔记。这刚好覆盖了最常见的关联查询场景又不会让模型复杂到干扰主要目标。prisma/schema.prisma的核心内容大致长这样model User { id String id default(cuid()) email String unique passwordHash String? name String? createdAt DateTime default(now()) updatedAt DateTime updatedAt notes Note[] } model Note { id String id default(cuid()) title String content String? published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id], onDelete: Cascade) createdAt DateTime default(now()) updatedAt DateTime updatedAt }这里有三个细节值得展开。第一User.passwordHash字段我标记为可空原因在于后续接入第三方 OAuth 登录时用户可以不走密码注册这个字段自然为空。如果一开始就把它设置为必填字符串后面接 GitHub 登录时还得专门刷一次数据库迁移得不偿失。第二Note.authorId和author这种外键关联关系定义了级联删除策略onDelete: Cascade意味着删除用户时其笔记一并删除。如果你不想这样也可以改成SetNull但前提是authorId字段必须可空。这个细节在初期可能看不出差别一旦用户注销功能上线就是安全事故。第三content字段我特意设为可空是因为在 t3code 的产品设计里允许用户只写标题不写正文比如把笔记当成灵感清单。实际开发中字段可空性是最容易被忽略的类型约束而它直接影响前端组件对空数据的处理逻辑。类型安全的收益在此时就能体现编辑器组件会强制要求处理/空字符串而不用靠运行时防御首算法。模型定义完成后执行一次迁移就能生成客户端类型pnpm dlx prisma migrate dev --name init执行完这条命令prisma/client会自动生成基于当前 schema 的完整类型比如Note、User、PrismaClient等。从这一步开始所有 TypeScript 类型约束便有了唯一事实来源。3.2 tRPC Router把数据库查询变成前端的函数调用而不是拼 URLt3code 的 API 层没有使用 RESTful 风格也没有把所有接口堆进pages/api而是通过 tRPC 路由统一管理。先看根初始化文件的核心逻辑// 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 ~/server/auth; export const createContext async (opts: CreateNextContextOptions) { const session await getServerSession(authOptions); return { session, db: prisma, }; }; const t initTRPC.contexttypeof createContext().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, session: ctx.session, }, }); }); export const router t.router;这里的关键是protectedProcedure。它和publicProcedure的核心差别在于它把登录态校验从控制器层提前到了路由中间件层。任何挂载在该过程下的接口都默认携带用户身份上下文。换句话说前端根本不可能调用到需要登录却没带 session 的接口因为请求在进入路由函数前就被拦截了。接下来看笔记路由的定义// src/server/api/routers/note.ts import { z } from zod; import { router, publicProcedure, protectedProcedure } from ../trpc; export const noteRouter router({ getAll: protectedProcedure.query(async ({ ctx }) { const notes await ctx.db.note.findMany({ where: { authorId: ctx.session.user.id }, orderBy: { createdAt: desc }, }); return notes; }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().optional() })) .mutation(async ({ ctx, input }) { const note await ctx.db.note.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); return note; }), });注意到两个特点。一是输入校验完全交给zod处理字段必填、长度、格式约束都在 schema 层面完成前端拿到的是已经校验通过的数据二是输出不需要手写返回类型findMany的查询结果会自动以类型化形式提供给前端包括id、title、content、createdAt等字段。这就是类型即文档的直观体现前端不用看接口文档只看类型定义就知道能拿到什么数据。3.3 前端组件直接消费类型化的数据流一次完整的 C 端交互前端调用 tRPC 的方式和调用一个本地的 hooks 函数非常接近。以笔记列表页为例// src/components/NoteList.tsx import { api } from ~/utils/api; export function NoteList() { const { data: notes, isLoading } api.note.getAll.useQuery(); if (isLoading) return div加载中.../div; return ( ul {notes?.map((note) ( li key{note.id} h3{note.title}/h3 {note.content p{note.content}/p} /li ))} /ul ); }这里的api.note.getAll是从根路由器对象中自动提取的notes的类型就是 PrismaNote[]。如果后端未来给Note增加一个tags数组字段前端这里不需要做任何类型声明修改编译器会自动提示新的字段。这类开发体验在传统 REST 模式下几乎是不可能的。新建笔记的组件大同小异关键是 mutation 的用法import { api } from ~/utils/api; export function NoteEditor() { const utils api.useUtils(); const createNote api.note.create.useMutation({ onSuccess: async () { await utils.note.getAll.invalidate(); }, }); const handleSubmit (e: React.FormEventHTMLFormElement) { e.preventDefault(); const formData new FormData(e.currentTarget); createNote.mutate({ title: String(formData.get(title)), content: String(formData.get(content) || ), }); }; return ( form onSubmit{handleSubmit} input nametitle / textarea namecontent / button typesubmit发布/button /form ); }onSuccess里调用invalidate是 React Query 的经典用法它会使笔记列表缓存失效并重新请求保证创建完成后列表立即刷新。这也是 tRPC React Query 组合最顺滑的地方你不需要自己写fetch、管理 loading 状态、处理请求竞态这些都由底层封装揽走了。我实测下来一个标准的全栈 CRUD 页面从 schema 到组件落地写代码的时间大概只有 REST 方案的一半而且几乎没有接口又双叒叕没对齐的烦恼。4. 认证与权限NextAuth 和 tRPC 中间件的组合玩法4.1 为什么认证是这类项目的分水岭而不是加分项很多全栈 demo 项目在认证这块选择先跳过或在本地存储里塞一个假的 user_id。在 t3code 里我从一开始就决定把认证体系和业务模型绑定好原因很简单权限隔离是整个类型安全链路里不该被打破的最后一环。前面链路再安全如果任何接口都能被匿名请求直呼那前面做的所有类型保障都没有实际意义。认证方案上我选了 NextAuth.js。它和 Next.js App Router 的集成度最高也天然适配 tRPC 的上下文机制。接入方式分两步先在pages/api/auth/[...nextauth].ts挂载处理函数再在src/server/auth.ts中配置认证选项。4.2 Credentials 与 OAuth 的取舍密码登录的安全责任这里需要做一个关键决策支持邮箱密码登录还是只提供 GitHub OAuth我当时两个都配置了但想强调一个原则——OAuth 是优先方案密码登录是兜底方案。GitHub OAuth 的配置相对简单你只需要在开发者设置里创建应用拿到Client ID和Client Secret后填入环境变量。难点在于密码登录。因为 NextAuth 的 Credentials Provider 默认不提供密码哈希和注册流程这两部分需要自己实现。t3code 里我用的是bcryptjs注册接口就是一个普通的 tRPC publicProcedureimport bcrypt from bcryptjs; import { z } from zod; import { publicProcedure } from ../trpc; export const authRouter router({ register: publicProcedure .input( z.object({ email: z.string().email(), password: z.string().min(8), }) ) .mutation(async ({ ctx, input }) { const existing await ctx.db.user.findUnique({ where: { email: input.email }, }); if (existing) throw new Error(邮箱已被注册); const passwordHash await bcrypt.hash(input.password, 10); const user await ctx.db.user.create({ data: { email: input.email, passwordHash, }, }); return { email: user.email }; }), });密码哈希强度选 10 个因子是平衡安全性和响应速度的常用值。更关键的是整个过程里passwordHash永远不会通过 tRPC 返回给前端——因为符合protectedProcedure返回类型要求的数据里根本没包含它。这就是类型约束在敏感数据维度上的天然防火墙。4.3 protectedProcedure 的实战价值权限不再靠前端代码自觉前面定义了protectedProcedure后业务路由里所有需要登录的接口直接用它即可。比如笔记路由里的getAll和create。这样设计的价值在真实项目里体现得非常充分任何前端代码要想拿到笔记列表就必须先通过登录态校验如果 session 失效服务端直接抛出UNAUTHORIZED错误而不是返回一串空数据或报 500 状态码。对于需要展示当前用户信息的组件还可以通过一个轻量路由暴露 sessionexport const authRouter router({ getSession: publicProcedure.query(({ ctx }) ctx.session), });前端想判断用户是否登录只需要api.auth.getSession.useQuery()。这里有个小坑getSession返回的是Session | null在 React 组件里要记得处理空值分支否则首屏渲染会不稳定。早期我在组件里直接解构session.user.email页面明明能看到内容却总是报Cannot read properties of null查了半天才发现是 session 还没加载完。后面我加了一个isLoading判断就清爽了。5. 上线过程中的坑与优化清单5.1 build 阶段最容易翻车的三个点我全踩过t3code 第一次跑next build时我连续踩了三个坑分别对应依赖生成、环境变量和数据库连接。第一个坑Prisma Client 没有在 build 前重新生成。因为 schema 在这个阶段做过调整但没有执行pnpm dlx prisma generate导致服务端代码里引用的某些新字段在类型上不存在报错信息还特别抽象配合提示某个字段在类型上不存在。解决办法很直接把生成命令加进 build 流程或者至少养成改完 schema 先跑 generate 的习惯。第二个坑环境变量缺失。构建过程中初始化 Prisma Client 时程序会尝试读取DATABASE_URL如果没配置直接抛异常导致整个构建失败。处理方案本地开发用.envCI 环境在构建任务里注入环境变量确保DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL这些关键配置在任何构建环境下都存在。第三个坑与前两个不同它更隐蔽NEXT_PUBLIC 前缀的环境变量有暴露风险不能用它存放密钥。早期的我犯过把NEXTAUTH_SECRET加进 NEXT_PUBLIC 前缀的错误后来发现这类变量会打进浏览器 bundle相当于明文泄露。这个错误非常危险我在项目上线前专门清理了一遍所有 NEXT_PUBLIC 前缀的变量只保留那些确实需要在浏览器端读取的配置。5.2 运行时优化别急着上缓存框架先看数据链路有没有多余的重复请求t3code 上线后我发现一个有意思的现象首屏加载笔记列表的速度不错但在快速切换页面时偶发闪烁。排查后发现是 React Query 的默认缓存策略。这个场景很多人会遇到所以单独提一下。React Query 对查询结果默认缓存 5 分钟后标记为 stale网络请求只在挂载新组件时发出。对于高频列表切换场景这其实是够用的。但如果你在同一个路由下多次调用同一个 query比如列表页既在getStaticProps里请求了一次又在组件里请求了一次就会造成冗余。t3code 的做法是把列表查询全部收敛为客户端查询服务端只返回页面布局利用 React Query 的缓存机制避免同一列表被反复拉取。另外一个优化点是在 tRPC 路由层。早期我把所有笔记查询放在一个noteRouter的getAll里后来列表页和详情页的字段需求越来越不一样列表需要精简单字段详情需要完整内容。起初为省事直接复用getAll结果是列表接口多返回了一堆大字段白白增加传输体积。后来拆成getList和getDetail两个路由用不同的字段选择效果立竿见影。TypeScript 类型同时跟着收窄组件里几乎不会再出现用一个几十字段的对象只是为了显示其中两个字段的尴尬。5.3 部署环境的选择与数据库连接的稳定性t3code 部署时我走的是通用 Node.js 服务方案准备一台装有 Node 18 的主机或 Docker 容器执行pnpm build pnpm start即可。这里有一个核心注意事项如果你的服务端数据库和 Node 进程在不同机房或地域连接延迟会直接影响首屏数据的返回速度。Prisma 连接池的默认行为是每个进程维持固定数量的连接如果请求量大了连接池不足就会报错报连接超时。我的做法是在DATABASE_URL上显式配置连接池上限比如?connection_limit10并根据业务量逐步调整。另外对 Node 版本的约束要写到 package.json 或 Dockerfile 里避免部署环境默认 Node 版本过新导致某些依赖不兼容。我在一次部署环境里遇到过 Node 21 下bcryptjs偶发不稳定的情况后来统一锁到 Node 18 LTS 版本再没有出现过这个级别的问题。关于 t3code 的后续想法如果你也想复刻一个类似的项目我最后再分享一条从 t3code 里总结出来的经验不要一开始就追求把认证、状态管理、数据库、文件上传、多语言等全塞进同一套脚手架。t3code 的价值不在于它用到了多少前沿技术而在于它把一条核心链路——数据库到 API 到组件——跑得足够通透。等这条链路你真正吃透了再往里加东西会顺手很多。另外环境变量管理这件事越早规范化越省心。建议从项目第一天就在仓库里放一个.env.example模板把用到的变量都列出来并标注哪些是公开的、哪些是私有的。虽然这事看着琐碎但经历过部署环境少配一个变量导致登录功能整体失效之后你就知道这 10 分钟的收益有多高了。
刚开始接触 t3code 这个项目名时很多人会下意识问一句这到底是个库、一个框架还是一个网站的代号我的答案是它既不是某个开源工具的名字也不是一个组织推出的新产品而是一个全栈项目的仓库名。当时我给这个项目起名叫 t3code是因为项目底层采用了 T3 技术栈Next.js、TypeScript、tRPC、Tailwind CSS 这些核心组合而 code 则代表整个仓库的核心使命——不追求花哨的界面把尽可能多的真实业务场景用干净、类型安全的代码串起来。这篇内容适合两类人看。第一类是正在纠结全栈技术选型的人尤其是不确定前后端到底要不要分离类型安全到底值不值得花时间的开发者第二类是已经听说过 tRPC 和 T3 栈但还没真正跑过一遍完整项目、想看看真实落地时有哪些坑的实践者。我不会去讲那些官方文档里已经写得很清楚的基础概念而是以 t3code 这个项目从初始化、建模、认证到部署的完整推进过程为线索把每一步的取舍理由、踩坑记录、优化方案都摊开来聊。1. 从T3到t3code这个项目名背后是一套完整的选型逻辑1.1 T3 不是什么新框架而是一种类型安全优先的工程理念先说清楚一个容易混淆的地方T3 Stack 并不是某个团队开发的统一框架而是一套由开发者社区总结出来的技术组合思路。它的核心倡议很简单——在你构建全栈应用时把类型安全放到最高优先级让 TypeScript 的类型系统从左到右贯穿整个链路数据库 schema、服务端 API、前端请求调用、组件 props全都由一份类型推导出来。t3code 这个项目就是在这一理念下诞生的。我的目标是做一个类似个人笔记 轻量发布的 Web 应用用户注册、登录后能创建笔记、修改笔记、查看自己的内容列表。这类业务用传统方式做通常要写三样东西数据库表、后端接口、前端接口封装。三个地方各写各的类型定义改一个字段名往往要全局搜索替换好几轮。而 t3code 想验证的就是这种类型穿透到底的方案能不能让整个开发体验简化到一个字段从数据库改到前端只需要动一处。1.2 前后端分离方案的隐性成本恰恰是 t3code 想绕开的我不是说前后端分离不好它在大型团队协作、多端复用、权限隔离等场景下有明显优势。但很多中小型全栈应用选择分离方案时实际付出的隐性成本被严重低估了需要维护一套接口文档Swagger/OpenAPI或者靠约定俗称的口口相传前后端需要各写一份 DTO 类型两边经常出现后端改了字段类型前端还在按 string 处理的错位联调阶段大量时间消耗在接口返回结构又变了这个字段到底可空不可空这类沟通上如果需要通过代码生成工具从前端生成 API 类型整套工具链的接入成本也不小。所以 t3code 从第一天起就选了另一条路把 Next.js 当作前端框架同时用它跑服务端逻辑用 tRPC 替代传统的 REST API 路由让前端组件直接引用后端查询函数用 Prisma 定义数据库模型并把模型类型自动提供给 tRPC。整个过程里TypeScript 是唯一的事实来源。为了更直观地说明差异我整理了一份对比这也是当时选型阶段经常被问到的问题维度传统前后端分离t3codeT3 组合方案类型维护前端、后端、API 文档各一份一份 Prisma schema全链路推导接口联调需要核对 URL、参数、返回结构前端直接调用类型化的服务端函数接口文档依赖 Swagger 或手动维护基本不需要独立文档类型即文档新增一个字段数据库/后端接口/前端类型三处改动改数据库模型类型自动同步复杂度上限适合大型团队、多端复杂生态适合 2-5 人团队、业务明确的全栈项目这里并不是说 T3 方案可以包治百病。如果团队成员超过一定规模或者前端需要独立于服务端部署这套组合的边界就会变得明显。但对于 t3code 这种快速迭代的轻量产品它的收益远远大于成本。2. 初始化 t3code环境准备、目录约定与依赖选择2.1 用交互式脚手架起步但要克制住全选的冲动t3code 的初始化方式我建议直接走官方脚手架命令很简单pnpm dlx create-t3-applatest t3code这个命令会拉取交互式配置让你选择是否包含 NextAuth、Prisma、Tailwind CSS、tRPC 等模块。第一次跑这个命令的人很容易把选项全勾上我后来发现这是一个典型的过度初始化陷阱。全勾意味着脚手架会同时生成认证、数据库、路由、样式、ESLint、环境变量模板等一整套东西目录结构在一开始就会显得很厚重对理解类型安全链路反而造成干扰。我当时的做法是分两次选择。第一次初始化只勾了 Next.js、TypeScript、Tailwind CSS 这三个基础项先让项目跑起来把页面渲染链路和样式体系确认好第二次再通过安装依赖的方式把 Prisma、tRPC、NextAuth 依次加进来。这样每一部分加入时我都明确知道它解决的是什么问题而不是面对一个已经生成完毕的全家桶去反推结构。如果你更习惯手动搭建核心依赖清单大致如下pnpm add trpc/server trpc/client trpc/react-query trpc/next tanstack/react-query zod superjson pnpm add prisma/client prisma --save-dev pnpm add next-auth auth/prisma-adapter bcryptjs注意一点版本不要盲目选 latest。t3code 项目跑通时我遇到过一个非常典型的问题——tRPC v11 和 Next.js 14 App Router 的适配写法与 v10 完全不同。如果你跟着网上一些旧教程安装会拿到一堆过时的 API 用法。建议安装后先看一眼 node_modules 里对应包的版本再决定参考哪套文档。这个习惯能省下你一整天的排查时间。2.2 目录结构不是随便分的它本身就在传递类型源头的思想初始化完成后项目里最有价值的部分其实不是配置代码而是目录约定。t3code 采用了 T3 脚手架推荐的分层方式prisma/ schema.prisma # 数据库模型全链路类型的源头 src/ app/ # Next.js App Router 的页面与布局 pages/api/ # 服务端 API 路由入口trpc、auth 挂载点 server/ auth.ts # NextAuth 配置 db.ts # Prisma Client 单例 api/ routers/ # tRPC 路由定义 root.ts # 根路由汇总 trpc.ts # tRPC 上下文与初始化 components/ # 前端组件 lib/ # 共享工具这套结构最核心的一个思想是所有类型都从prisma/schema.prisma出发流向src/server再流向src/components。你不可能在前端组件里凭空定义一份游离的接口类型因为组件拿到的数据来源就是 tRPC 的返回类型而 tRPC 的返回类型又由 Prisma 模型决定。用一句话概括目录结构本身就是类型安全链路的地图。看懂了这个分层后续写代码就不会迷路。3. 类型安全链路实战Prisma、tRPC 与前端组件如何无缝衔接3.1 用 Prisma 定义业务模型字段可空性和关联关系是第一道关卡t3code 的业务模型非常简单只有两个核心实体用户User和笔记Note一个用户拥有多条笔记。这刚好覆盖了最常见的关联查询场景又不会让模型复杂到干扰主要目标。prisma/schema.prisma的核心内容大致长这样model User { id String id default(cuid()) email String unique passwordHash String? name String? createdAt DateTime default(now()) updatedAt DateTime updatedAt notes Note[] } model Note { id String id default(cuid()) title String content String? published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id], onDelete: Cascade) createdAt DateTime default(now()) updatedAt DateTime updatedAt }这里有三个细节值得展开。第一User.passwordHash字段我标记为可空原因在于后续接入第三方 OAuth 登录时用户可以不走密码注册这个字段自然为空。如果一开始就把它设置为必填字符串后面接 GitHub 登录时还得专门刷一次数据库迁移得不偿失。第二Note.authorId和author这种外键关联关系定义了级联删除策略onDelete: Cascade意味着删除用户时其笔记一并删除。如果你不想这样也可以改成SetNull但前提是authorId字段必须可空。这个细节在初期可能看不出差别一旦用户注销功能上线就是安全事故。第三content字段我特意设为可空是因为在 t3code 的产品设计里允许用户只写标题不写正文比如把笔记当成灵感清单。实际开发中字段可空性是最容易被忽略的类型约束而它直接影响前端组件对空数据的处理逻辑。类型安全的收益在此时就能体现编辑器组件会强制要求处理/空字符串而不用靠运行时防御首算法。模型定义完成后执行一次迁移就能生成客户端类型pnpm dlx prisma migrate dev --name init执行完这条命令prisma/client会自动生成基于当前 schema 的完整类型比如Note、User、PrismaClient等。从这一步开始所有 TypeScript 类型约束便有了唯一事实来源。3.2 tRPC Router把数据库查询变成前端的函数调用而不是拼 URLt3code 的 API 层没有使用 RESTful 风格也没有把所有接口堆进pages/api而是通过 tRPC 路由统一管理。先看根初始化文件的核心逻辑// 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 ~/server/auth; export const createContext async (opts: CreateNextContextOptions) { const session await getServerSession(authOptions); return { session, db: prisma, }; }; const t initTRPC.contexttypeof createContext().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, session: ctx.session, }, }); }); export const router t.router;这里的关键是protectedProcedure。它和publicProcedure的核心差别在于它把登录态校验从控制器层提前到了路由中间件层。任何挂载在该过程下的接口都默认携带用户身份上下文。换句话说前端根本不可能调用到需要登录却没带 session 的接口因为请求在进入路由函数前就被拦截了。接下来看笔记路由的定义// src/server/api/routers/note.ts import { z } from zod; import { router, publicProcedure, protectedProcedure } from ../trpc; export const noteRouter router({ getAll: protectedProcedure.query(async ({ ctx }) { const notes await ctx.db.note.findMany({ where: { authorId: ctx.session.user.id }, orderBy: { createdAt: desc }, }); return notes; }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().optional() })) .mutation(async ({ ctx, input }) { const note await ctx.db.note.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); return note; }), });注意到两个特点。一是输入校验完全交给zod处理字段必填、长度、格式约束都在 schema 层面完成前端拿到的是已经校验通过的数据二是输出不需要手写返回类型findMany的查询结果会自动以类型化形式提供给前端包括id、title、content、createdAt等字段。这就是类型即文档的直观体现前端不用看接口文档只看类型定义就知道能拿到什么数据。3.3 前端组件直接消费类型化的数据流一次完整的 C 端交互前端调用 tRPC 的方式和调用一个本地的 hooks 函数非常接近。以笔记列表页为例// src/components/NoteList.tsx import { api } from ~/utils/api; export function NoteList() { const { data: notes, isLoading } api.note.getAll.useQuery(); if (isLoading) return div加载中.../div; return ( ul {notes?.map((note) ( li key{note.id} h3{note.title}/h3 {note.content p{note.content}/p} /li ))} /ul ); }这里的api.note.getAll是从根路由器对象中自动提取的notes的类型就是 PrismaNote[]。如果后端未来给Note增加一个tags数组字段前端这里不需要做任何类型声明修改编译器会自动提示新的字段。这类开发体验在传统 REST 模式下几乎是不可能的。新建笔记的组件大同小异关键是 mutation 的用法import { api } from ~/utils/api; export function NoteEditor() { const utils api.useUtils(); const createNote api.note.create.useMutation({ onSuccess: async () { await utils.note.getAll.invalidate(); }, }); const handleSubmit (e: React.FormEventHTMLFormElement) { e.preventDefault(); const formData new FormData(e.currentTarget); createNote.mutate({ title: String(formData.get(title)), content: String(formData.get(content) || ), }); }; return ( form onSubmit{handleSubmit} input nametitle / textarea namecontent / button typesubmit发布/button /form ); }onSuccess里调用invalidate是 React Query 的经典用法它会使笔记列表缓存失效并重新请求保证创建完成后列表立即刷新。这也是 tRPC React Query 组合最顺滑的地方你不需要自己写fetch、管理 loading 状态、处理请求竞态这些都由底层封装揽走了。我实测下来一个标准的全栈 CRUD 页面从 schema 到组件落地写代码的时间大概只有 REST 方案的一半而且几乎没有接口又双叒叕没对齐的烦恼。4. 认证与权限NextAuth 和 tRPC 中间件的组合玩法4.1 为什么认证是这类项目的分水岭而不是加分项很多全栈 demo 项目在认证这块选择先跳过或在本地存储里塞一个假的 user_id。在 t3code 里我从一开始就决定把认证体系和业务模型绑定好原因很简单权限隔离是整个类型安全链路里不该被打破的最后一环。前面链路再安全如果任何接口都能被匿名请求直呼那前面做的所有类型保障都没有实际意义。认证方案上我选了 NextAuth.js。它和 Next.js App Router 的集成度最高也天然适配 tRPC 的上下文机制。接入方式分两步先在pages/api/auth/[...nextauth].ts挂载处理函数再在src/server/auth.ts中配置认证选项。4.2 Credentials 与 OAuth 的取舍密码登录的安全责任这里需要做一个关键决策支持邮箱密码登录还是只提供 GitHub OAuth我当时两个都配置了但想强调一个原则——OAuth 是优先方案密码登录是兜底方案。GitHub OAuth 的配置相对简单你只需要在开发者设置里创建应用拿到Client ID和Client Secret后填入环境变量。难点在于密码登录。因为 NextAuth 的 Credentials Provider 默认不提供密码哈希和注册流程这两部分需要自己实现。t3code 里我用的是bcryptjs注册接口就是一个普通的 tRPC publicProcedureimport bcrypt from bcryptjs; import { z } from zod; import { publicProcedure } from ../trpc; export const authRouter router({ register: publicProcedure .input( z.object({ email: z.string().email(), password: z.string().min(8), }) ) .mutation(async ({ ctx, input }) { const existing await ctx.db.user.findUnique({ where: { email: input.email }, }); if (existing) throw new Error(邮箱已被注册); const passwordHash await bcrypt.hash(input.password, 10); const user await ctx.db.user.create({ data: { email: input.email, passwordHash, }, }); return { email: user.email }; }), });密码哈希强度选 10 个因子是平衡安全性和响应速度的常用值。更关键的是整个过程里passwordHash永远不会通过 tRPC 返回给前端——因为符合protectedProcedure返回类型要求的数据里根本没包含它。这就是类型约束在敏感数据维度上的天然防火墙。4.3 protectedProcedure 的实战价值权限不再靠前端代码自觉前面定义了protectedProcedure后业务路由里所有需要登录的接口直接用它即可。比如笔记路由里的getAll和create。这样设计的价值在真实项目里体现得非常充分任何前端代码要想拿到笔记列表就必须先通过登录态校验如果 session 失效服务端直接抛出UNAUTHORIZED错误而不是返回一串空数据或报 500 状态码。对于需要展示当前用户信息的组件还可以通过一个轻量路由暴露 sessionexport const authRouter router({ getSession: publicProcedure.query(({ ctx }) ctx.session), });前端想判断用户是否登录只需要api.auth.getSession.useQuery()。这里有个小坑getSession返回的是Session | null在 React 组件里要记得处理空值分支否则首屏渲染会不稳定。早期我在组件里直接解构session.user.email页面明明能看到内容却总是报Cannot read properties of null查了半天才发现是 session 还没加载完。后面我加了一个isLoading判断就清爽了。5. 上线过程中的坑与优化清单5.1 build 阶段最容易翻车的三个点我全踩过t3code 第一次跑next build时我连续踩了三个坑分别对应依赖生成、环境变量和数据库连接。第一个坑Prisma Client 没有在 build 前重新生成。因为 schema 在这个阶段做过调整但没有执行pnpm dlx prisma generate导致服务端代码里引用的某些新字段在类型上不存在报错信息还特别抽象配合提示某个字段在类型上不存在。解决办法很直接把生成命令加进 build 流程或者至少养成改完 schema 先跑 generate 的习惯。第二个坑环境变量缺失。构建过程中初始化 Prisma Client 时程序会尝试读取DATABASE_URL如果没配置直接抛异常导致整个构建失败。处理方案本地开发用.envCI 环境在构建任务里注入环境变量确保DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL这些关键配置在任何构建环境下都存在。第三个坑与前两个不同它更隐蔽NEXT_PUBLIC 前缀的环境变量有暴露风险不能用它存放密钥。早期的我犯过把NEXTAUTH_SECRET加进 NEXT_PUBLIC 前缀的错误后来发现这类变量会打进浏览器 bundle相当于明文泄露。这个错误非常危险我在项目上线前专门清理了一遍所有 NEXT_PUBLIC 前缀的变量只保留那些确实需要在浏览器端读取的配置。5.2 运行时优化别急着上缓存框架先看数据链路有没有多余的重复请求t3code 上线后我发现一个有意思的现象首屏加载笔记列表的速度不错但在快速切换页面时偶发闪烁。排查后发现是 React Query 的默认缓存策略。这个场景很多人会遇到所以单独提一下。React Query 对查询结果默认缓存 5 分钟后标记为 stale网络请求只在挂载新组件时发出。对于高频列表切换场景这其实是够用的。但如果你在同一个路由下多次调用同一个 query比如列表页既在getStaticProps里请求了一次又在组件里请求了一次就会造成冗余。t3code 的做法是把列表查询全部收敛为客户端查询服务端只返回页面布局利用 React Query 的缓存机制避免同一列表被反复拉取。另外一个优化点是在 tRPC 路由层。早期我把所有笔记查询放在一个noteRouter的getAll里后来列表页和详情页的字段需求越来越不一样列表需要精简单字段详情需要完整内容。起初为省事直接复用getAll结果是列表接口多返回了一堆大字段白白增加传输体积。后来拆成getList和getDetail两个路由用不同的字段选择效果立竿见影。TypeScript 类型同时跟着收窄组件里几乎不会再出现用一个几十字段的对象只是为了显示其中两个字段的尴尬。5.3 部署环境的选择与数据库连接的稳定性t3code 部署时我走的是通用 Node.js 服务方案准备一台装有 Node 18 的主机或 Docker 容器执行pnpm build pnpm start即可。这里有一个核心注意事项如果你的服务端数据库和 Node 进程在不同机房或地域连接延迟会直接影响首屏数据的返回速度。Prisma 连接池的默认行为是每个进程维持固定数量的连接如果请求量大了连接池不足就会报错报连接超时。我的做法是在DATABASE_URL上显式配置连接池上限比如?connection_limit10并根据业务量逐步调整。另外对 Node 版本的约束要写到 package.json 或 Dockerfile 里避免部署环境默认 Node 版本过新导致某些依赖不兼容。我在一次部署环境里遇到过 Node 21 下bcryptjs偶发不稳定的情况后来统一锁到 Node 18 LTS 版本再没有出现过这个级别的问题。关于 t3code 的后续想法如果你也想复刻一个类似的项目我最后再分享一条从 t3code 里总结出来的经验不要一开始就追求把认证、状态管理、数据库、文件上传、多语言等全塞进同一套脚手架。t3code 的价值不在于它用到了多少前沿技术而在于它把一条核心链路——数据库到 API 到组件——跑得足够通透。等这条链路你真正吃透了再往里加东西会顺手很多。另外环境变量管理这件事越早规范化越省心。建议从项目第一天就在仓库里放一个.env.example模板把用到的变量都列出来并标注哪些是公开的、哪些是私有的。虽然这事看着琐碎但经历过部署环境少配一个变量导致登录功能整体失效之后你就知道这 10 分钟的收益有多高了。
实战与调优指南)
