我见过太多全栈项目死在了联调环节。后端把接口字段改了个名前端在代码里全局搜了半天才找到调用点Swagger 文档明明写着 string实际返回 null就算一切正常前后端的类型定义也是各写各的谁都不敢动。后来我开始尝试用 t3code 这套方案也就是社区里经常说的 T3 Stack算是把这类问题从根上解决了一大部分。一句话概括 t3code 是什么以 Next.js 为应用宿主以 TypeScript 贯穿前后端用 tRPC 替代传统 REST 接口层用 Prisma 管理数据库模型和迁移再用 Tailwind CSS 解决样式NextAuth.js 处理认证。你不用担心它又是一个绑架你的全家桶框架因为 create-t3-app 给了你一堆开关不想要的东西可以不选。它的核心思路不是帮你写好所有代码而是让类型从数据库、服务端、客户端一路亮绿灯改一个字段名所有没有同步修改的地方立刻编译报错而不是上线之后才暴露问题。这篇文章我会从“为什么这么选”开始讲起然后给出一套完整可复现的搭建流程最后把我实际踩过的坑按故障现象整理成速查表。如果你正在做中小型产品、想快速验证一个想法或者纯粹想找一个全栈开发的顺手姿势这篇内容应该能帮你省下不少试错时间。1. 先搞清楚 t3code 这套组合拳打的是什么痛点1.1 全栈项目最大的隐形成本类型断裂传统全栈项目最常见的状态是前端一个仓库、后端一个仓库或者勉强放在同一个仓库里但接口层用的是 REST 约定。于是同一份业务数据要出现在四个地方数据库迁移文件里的字段定义、后端 DTO 的类型、前端手写的 interface、以及早就没人维护的 Swagger 文档。任何一次字段改动至少得同步四个位置少改一个就埋一颗雷。我遇到过一个很典型的例子订单列表接口返回的字段叫 goodsName前端同事参照旧文档写的 interface 是 productName。联调的时候列表一直显示空内容排查了大半天最后发现两边都没写错就是字段名对不上。这类问题本质上不是技术难点而是“信息在不同位置重复存放”的必然结果。就像两个人约见面一个说东门一个理解成西门谁都没错但就是见不到。当项目规模变大、参与人数变多之后这种类型断裂问题会指数级放大。接口文档更新了但没人看后端重构了参数但前端不知道类型对不上只能在运行时靠 console.log 逐层找。这些消耗在“对齐信息”上的时间往往比写业务逻辑本身还多。1.2 T3 的设计哲学类型安全不是偏执是效率T3 Stack 的核心精神只有四个字类型安全。它的做法很有意思——我不靠文档来约定接口我把类型本身变成约定。Prisma 的 schema 文件是数据库的权威定义tRPC 的 router 是后端接口的权威定义前端通过自动生成的类型和 hooks 去调用后端中间不手写任何一个接口签名。从实际操作层面看这意味着改一个字段名如果后端 router 改了、Prisma client 重生成之后前端某处还引用旧字段编译器会直接把错误标出来。你不需要运行任何环境、不需要 mock 数据、不需要对着文档猜就能在编写阶段发现断裂点。用我同事的话说“以前是上线前提心吊胆现在是编译不过根本提不了。”T3 还有一个组织方式上的理念叫“纵向切片”不是传统的 controller / service / model 纵向分层而是一个功能从页面组件到数据库查询完整地走一遍。对中小项目来说这种组织方式让每个功能相对独立改帖子模块不会影响用户模块维护起来直观很多。社区里也常说 T3 是“约定而非框架”它不强求你每个项目都用全套工具而是提供一套默认合理的组合。1.3 这套方案到底适合谁先说结论它最适合中小型 SaaS、内部工具、MVP 验证和个人全栈项目。这类项目有一个共同点——业务逻辑的复杂度不算高但迭代速度要求快你不想花大量时间在接口层做重复劳动。反过来如果你的系统对多租户数据隔离极其复杂或者你们已经重度依赖一套成熟的 REST 生态甚至每个 API 都要独立部署到边缘节点追求冷启动性能那 t3code 就不太适合。tRPC 更适合单体全栈应用而不是微服务化的开放平台。认清适用边界才能在不同方案之间做出不拧巴的选择。2. T3 核心选型逐个拆解为什么是它们而不是别人2.1 Next.js App Router前后端住在同一个进程T3 选择 Next.js 当宿主我认为最核心的理由是它让“前端页面”和“后端服务”不再割裂。Next.js 本身是一个 React 框架但它的 App Router 支持服务端组件、路由处理器、Server Actions。你可以在页面组件里直接查数据库也可以在同一项目里提供 API 端点前后端共用一套代码仓库、一套依赖、一套部署链路。在 T3 的组合里Next.js 主要承担三件事渲染页面、作为 tRPC 端点的宿主、托管 NextAuth 的认证逻辑。这套架构的一个显著好处是部署简单——你不需要单独维护一个 Node.js API 服务也不需要配置跨域规则因为前端资源和 API 接口在同源下。坦白讲如果你不需要独立扩容后端这个取舍非常合理。当然App Router 的学习曲线比以前 Pages Router 陡一点特别是服务端组件和客户端组件的边界问题。但 create-t3-app 生成的模板已经把常见的坑填平了大半比如“use client”该加在哪、tRPC Provider 挂在哪个层级模板里都是现成的。对新手来说先照着模板跑通再慢慢理解原理比从空项目硬啃要舒服得多。2.2 tRPC接口层从“协商文档”变成“直接调函数”tRPC 是整个 t3code 的灵魂。它的思路说穿了很简单既然前后端都是 TypeScript那为什么接口层不能直接共享类型还要靠 REST 规范、Swagger 注释、手写 SDK 来缝缝补补tRPC 做的事情就是把后端路由函数的参数和返回值类型直接推断给前端调用方。你在浏览器端写api.post.list.useQuery()它看起来就是一个普通 React hook不需要拼接 URL、不需要手动处理 fetch、不需要定义响应类型。这里给不熟悉的朋友打个比方传统 REST 调用像寄快递你得写清楚地址、包裹内容、收货确认tRPC 像两个人直接视频通话你刚开口对方就明白你要什么返回结果也是即时当面告诉你。整个过程由 TypeScript 编译器在职守类型错了当场报错而不是等到运行时才发现“寄错了包裹”。很多人第一次听 tRPC 会担心“把所有后端函数直接暴露给前端安全吗”。实际上 tRPC 只是暴露一个统一的/api/trpc端点所有路由逻辑都跑在服务端浏览器拿到的只是执行结果你完全控制哪些 procedure 是公开的、哪些需要登录才能调用。它并没有把服务端代码直接下载给客户端这个疑虑可以打消。2.3 Prisma数据库结构的“单一事实来源”Prisma 在 t3code 里扮演的是“数据库权威定义”的角色。它用一个 schema 文件描述数据模型、字段类型、表关系然后根据这个文件生成类型安全的数据库客户端。你在 TypeScript 里写ctx.db.post.findMany()得到的对象是强类型的字段名、类型、可选性全部由 schema 推导出来写错了 IDE 立刻标红。Prisma 和其他 ORM 最大的区别是 schema 优先。你不在代码里散落地定义表结构所有改动都从 schema 开始然后通过迁移脚本同步到数据库。这样的好处是代码里的类型、数据库里的表、迁移历史里的记录三方永远保持一致。你也不会再遇到“代码里的字段和数据库对不上”这种低级问题。不过要诚实说一句Prisma 在复杂查询和原生 SQL 场景下会有一些限制。如果你需要特别复杂的联表和聚合逻辑Prisma 的 API 会比较啰嗦。但 T3 本身提供了一条逃生通道——你可以在 tRPC 路由里直接写ctx.db.$queryRaw执行原生 SQL。这不是什么非黑即白的问题知道哪里该用工具、哪里该自己写才是工程能力。2.4 Tailwind CSS 和 NextAuth.js默认武器足够省心T3 里 Tailwind CSS 不是必须项它的角色是提供原子化的 CSS 工具类让你不需要在页面和样式文件之间来回切换。有些人觉得 Tailwind 的 class 名很长不够“优雅”但我实际用下来的感受是对于全栈快速迭代它确实省事。你不是在花时间给 class 命名而是在组件内部直接完成样式调整改起来也特别快。NextAuth.js 则承担认证方案。它默认支持各种 OAuth 提供商也支持 Credentials 登录。T3 模板里把 NextAuth 和 Prisma 的 Adapter 接好了你在 schema 里定义好 User、Account、Session 这些模型登录功能就能跑起来。对于绝大多数中小项目来说自己从零写一套 Session 管理不值得NextAuth 是经过验证的默认选择。2.5 和传统方案对比REST Swagger vs GraphQL codegen vs T3很多人会问为什么不用 REST 或者 GraphQL它们各有各的好但场景不一样。方案类型安全学习成本适合场景主要痛点REST Swagger弱靠手写或插件生成低公开 API、开放平台文档和实现容易脱节类型靠人维护GraphQL codegen强但有额外 schema 语言中数据聚合复杂的前端驱动需要维护 resolver 和 codegen 流程tRPC最强类型即契约低TS 开发者内部全栈应用、产品型项目不适合公开 API前后端需同仓库或共享类型从这个对比可以看出来tRPC 并不是要取代 REST 或 GraphQL而是找到了一个更适合“自己人用”的中间地带。如果你的产品是给内部用户或自己的前端用搞一套完整的接口文档体系确实是浪费。这个选型逻辑比单纯比较“谁更先进”要实用得多。3. 手把手搭一个 t3code 项目从初始化到线上3.1 初始化create-t3-app 的交互选项怎么选初始化 t3code 项目最无脑的方式就是官方脚手架。我在写这篇内容时create-t3-app 已经到 7.x命令依然是npx create-t3-applatest my-t3-app执行之后它会问你几个问题包括项目名、想启用哪些技术模块。我的建议是第一次先全选跑通之后再看哪些不需要就移除。重点提一下它会让你在 Prisma 和 Drizzle 之间二选一如果你没有特别的偏好或者刚接触先选 Prisma 会更稳文档和社区资源都更丰富。初始化完成后的目录结构长这样my-t3-app/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── app/ │ │ └── api/trpc/[trpc]/route.ts │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ ├── root.ts │ │ │ └── trpc.ts │ │ └── db.ts │ ├── utils/ │ │ └── api.ts │ └── env.mjs └── package.json看到这个结构不用慌它已经把核心的关注点划分得很清楚prisma管数据模型server/api/routers放后端逻辑utils/api是前端调用 tRPC 的入口env.mjs统一做环境变量校验。后面的操作都围绕这几个目录展开。3.2 定义数据模型从 Prisma Schema 开始假设我们要做一个极简的帖子应用用户登录后可以发帖游客可以看帖子列表。首先在prisma/schema.prisma里定义模型model Post { id String id default(cuid()) title String content String? createdAt DateTime default(now()) updatedAt DateTime updatedAt createdBy User relation(fields: [createdById], references: [id]) createdById String } model User { id String id default(cuid()) name String? email String unique posts Post[] accounts Account[] sessions Session[] }这里我故意把title设为必填、content设为可选这样后面可以直观地看到 tRPC 的输入校验怎么和类型对齐。关系方面一个用户有多个帖子帖子必须属于一个用户。如果开了 NextAuth还需要在 schema 里补上Account、Session、VerificationToken这三个模型模板默认会生成不用自己手敲。写完 schema 后执行npx prisma migrate dev --name init这条命令会创建数据库表、生成 Prisma Client、更新类型定义。注意它需要DATABASE_URL环境变量已经配置好本地最简单的方式是用 SQLite直接把连接串写成file:./db.sqlite零配置就能跑起来。真到了生产环境再换 PostgreSQL连接串一换代码基本不用动。3.3 创建 tRPC Router让业务逻辑可被前端调用接着进入src/server/api/routers/post.ts创建一个帖子路由。我用两类 procedure 分别演示公开接口和登录接口import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure .query(async ({ ctx }) { return ctx.db.post.findMany({ orderBy: { createdAt: desc }, include: { createdBy: { select: { name: true } } }, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1, 标题不能为空), content: z.string().optional(), }) ) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, createdById: ctx.session.user.id, }, }); }), });这段代码有几个值得注意的点。第一publicProcedure不需要登录protectedProcedure会自动检查 Session没登录直接抛UNAUTHORIZED你不需要在每个路由里重复判断。第二input用 zod 定义它既是运行时校验也是静态类型推断的来源前端传参时类型和校验规则完全共享。第三ctx.db是模板注入的 Prisma Clientctx.session是当前登录用户信息这些东西由 tRPC 的 context 统一组装。创建完路由之后记得回到src/server/api/root.ts注册export const appRouter createTRPCRouter({ post: postRouter, }); export type AppRouter typeof appRouter;AppRouter这个类型是整个前后端共享的关键。前端所有的 hooks 类型都从它推导后端每新增一段逻辑前端不需要手动同步任何类型定义。3.4 前端页面调用useQuery 和 useMutation打开src/app/page.tsx或者自己新建一个客户端组件就可以直接调用接口了use client; import { api } from ~/utils/api; export default function PostList() { const { data, isLoading } api.post.list.useQuery(); const createPost api.post.create.useMutation(); const handleSubmit async () { await createPost.mutateAsync({ title: 测试标题, content: 测试内容 }); }; if (isLoading) return div加载中.../div; return ( div button onClick{handleSubmit}新建帖子/button ul {data?.map((post) ( li key{post.id} {post.title} - {post.createdBy?.name} /li ))} /ul /div ); }这里有个新手特别容易踩的坑tRPC 的useQuery和useMutationhooks 只能在客户端组件里使用所以组件顶部必须加use client。如果你在服务端组件里调这个 hook会直接报错。服务端组件想读取数据应该用 tRPC 的服务端调用器caller而不是 React hooks。模板里没有直接展示这个用法我在实际项目中习惯用一个 helper 包一下但初期先把 hooks 用顺就够了。从这个调用代码能看出什么你不需要写fetch(/api/trpc/post.list)不需要手动处理 JSON 序列化不需要定义响应类型。data的类型直接从appRouter推导过来如果后端改了返回结构这里编译就红了。3.5 把认证接进来NextAuth 的正确打开方式T3 模板已经把 NextAuth 的初始化代码放在src/server/auth.ts里默认接好了 PrismaAdapter。你真正要做的只有两件事配置环境变量以及决定用哪种登录方式。.env里至少要配这些DATABASE_URLfile:./db.sqlite NEXTAUTH_SECRET随便一个足够长的随机字符串 NEXTAUTH_URLhttp://localhost:3000如果你要接入 GitHub、Google 这类 OAuth 提供商还要在 schema 里保证Account模型存在然后在auth.ts的 providers 数组里填入对应的 Client ID 和 Client Secret。如果你不想接第三方登录也可以用 CredentialsProvider 自己实现账号密码登录但密码哈希这类事情就得自己处理了。我的建议是能走 OAuth 就走 OAuth省心又安全。认证和 tRPC 是配合工作的NextAuth 会把 Session 放进 tRPC 的 contextprotectedProcedure内部先检查ctx.session没有就抛错。前端在调用protectedProcedure的接口时如果弹了UNAUTHORIZED你就知道当前用户没登录或者登录已过期直接引导去登录页。这套链路在 T3 里是天然打通的不需要额外写中间件。3.6 部署到生产Vercel 上最容易出问题的地方t3code 项目部署到 Vercel 很方便因为 Next.js 本来就是 Vercel 家的产品。但你如果以为 push 到 GitHub 就能一键上线那就太天真了。最容易出问题的地方永远是数据库和构建阶段。第一本地用的 SQLite 文件是存在本地磁盘的Vercel 的函数运行环境是临时文件系统每次重新部署都会清空。也就是说本地辛辛苦苦写的测试数据部署上去可能只剩一个空数据库。生产环境请务必换成托管 PostgreSQLNeon、Supabase、Railway 都行只需要改DATABASE_URL。第二不要在 Vercel 的构建命令里跑prisma migrate deploy。比较稳妥的做法是把迁移单独放到发布流程里执行比如本地先跑prisma migrate deploy再部署或者用 GitHub Actions 在跑完测试之后统一迁移。否则一旦某个迁移有问题构建和部署都会卡住排查起来很痛苦。第三Vercel 的环境变量配置页面和本地.env有点区别——值不要带引号粘贴进去就行了。我之前犯过一次错把.env里带引号的值直接复制到 Vercel结果连接串里多了两个引号字符数据库连接失败页面全是 500。这类问题看起来低级但确实会真实发生。4. 实操中我踩过的坑按故障现象速查4.1 改了 Prisma Schema但 tRPC 返回的类型没变这个场景几乎每个用 T3 的人都会遇到在schema.prisma里加了published Boolean字段migration 也跑完了但前端代码里post.published一直标红。原因不是 tRPC 的问题而是你没有重新生成 Prisma Client。Prisma 是根据生成的 client 文件提供类型的schema 变了不代表 client 会自动变。解决办法很简单npx prisma generate如果你是先改 schema 再跑prisma migrate dev它会自动调用 generate。但如果只改了数据库或者单独更新了依赖就容易漏这一步。我的习惯是把 generate 写进项目的 pretest 脚本里确保每次自动检查前都生成最新类型避免科室里出现“我明明改了为什么报错”的假象。4.2 开发环境数据库连接被占满 / 热重载崩溃Next.js 开发模式下每次保存文件都会触发热重载如果你在代码里直接new PrismaClient()每次重载都会创建一个新的实例连接数会肉眼可见地飙升最后报“Too many connections”。T3 模板其实已经在src/server/db.ts里处理了这个坑——它用 globalThis 做单例缓存开发模式下所有热重载共享同一个 PrismaClient。你只要记住不要自己到处new PrismaClient()要用模板提供的db对象。很多自定义代码翻车就是因为绕开了默认封装。// 推荐模板默认 import { db } from ~/server/db; // 不推荐会炸连接池 import { PrismaClient } from prisma/client; const prisma new PrismaClient();4.3 部署后接口全部 500日志显示环境变量缺失在本地跑得好好的一部署到 Vercel 就 500最典型的原因就是环境变量没配齐。Vercel 不会自动读取你本地.env文件你需要在项目设置里的 Environment Variables 手动填入关键配置DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL以及业务上用到的第三方密钥。这里有一个隐蔽的坑——T3 项目的src/env.mjs会在构建阶段校验环境变量缺失的变量会让整个构建失败而不是运行时才报错。这其实是好事它把问题前移了但你第一次接触时可能会觉得“怎么连构建都不过”。解决方式就是打开 Vercel 的构建日志看看哪一行校验报错缺哪个补哪个就好。4.4 登录回调地址不对OAuth 一直失败OAuth 登录配置好后在本地测试正常部署到线上就不行点登录按钮出来一个redirect_uri不匹配的错误。这个 90% 是NEXTAUTH_URL设错了。NextAuth 在生成回调地址时依赖NEXTAUTH_URL或生产环境下的部署域名。如果你忘了设置或者设置成了http://localhost:3000那回调地址自然对不上。去授权平台的回调白名单里把生产域名加上同时确保NEXTAUTH_URL写的是线上地址。这个配置是认证链路的基石值得在部署清单里单独打勾。4.5 问题速查表故障现象排查方向解决办法修改 Prisma 后类型没更新Prisma Client 未重新生成执行npx prisma generatetRPC 调用返回 401调用了 protectedProcedure 但未登录检查 Session 状态引导用户登录开发时连接数暴涨PrismaClient 被反复实例化使用src/server/db.ts的全局单例Vercel 部署后所有接口 500环境变量缺失或带引号补全DATABASE_URL、NEXTAUTH_SECRET等变量OAuth 登录报 redirect_uri 错误NEXTAUTH_URL与白名单不一致配置线上域名确保回调地址匹配Query 报 missing required inputzod 校验与传入参数不一致检查前端传参与后端 input schema 是否对齐部署后本地数据消失SQLite 文件在临时文件系统被清空生产环境换托管 PostgreSQL速查表里的每一行都是真实存在过的教训不是网上抄来的。前端传参和 zod 校验不一致那一条尤其隐蔽因为类型上可能没问题但运行时校验会拦下来。写 tRPC 路由时先想清楚“这个接口接受什么”再用 zod 把边界卡住能省掉大量联调问题。5. 用了一段时间之后我的一些个人体会5.1 什么时候该用什么时候别硬上t3code 用顺了确实舒服但它不是万能药。我自己的判断标准很简单如果这个项目的接口主要是给自家人用前端是 Next.js 或者 React后端的复杂度在单体应用范围内那 t3code 会非常趁手。反过来如果我要做一个开放平台接口要给别人调用、要计费、要兼容多语言 SDK那 REST 仍然是更通用的选择因为 tRPC 的优势在跨出 JavaScript 生态之后就消失了。团队的技术背景也要考虑。如果你们整个团队都是 TypeScript 开发者引入 t3code 的摩擦非常小。但如果有大量后端同学不熟 TypeScript突然让他们接受“数据库查询直接暴露给前端层”这套思路可能会有点别扭。技术选型永远是场景优先不是流行度优先。5.2 可以怎么继续扩展t3code 搭出来的项目不是玩具它就着这套基础可以继续往上盖楼。等业务复杂起来你可以把项目改造成 pnpm monorepo把packages/db、packages/api、packages/web拆开类型依然在包之间共享想加测试可以用 Vitest 给 tRPC 路由写单元测试因为 router 是纯函数逻辑mock 掉 context 里的 db 就可以跑非常方便想换数据访问层新的 T3 模板支持 Drizzle它比 Prisma 更轻量SQL 风格更直接适合喜欢原生 SQL 的开发者。还有一个方向值得花时间研究对比一下 tRPC 和 Next.js Server Actions 的适用场景。Server Actions 在表单提交场景效率惊人tRPC 在需要通用类型安全接口层的场景更稳。两者不完全冲突但你想清楚边界能避免很多架构上的纠结。我最近的几个项目里简单表单直接用 Server Actions复杂数据流走 tRPC体验反而比只用一种更好。5.3 几个零散心得如果非要用一句话概括我对 t3code 的态度那就是“工具真正能帮你省时间的前提是你先愿意花时间理解它为什么这么设计”。我见过太多人复制一段模板代码跑通就丢一边遇到类型报错第一反应是删掉类型最后用成了“带类型的普通全栈项目”那真的白瞎了这个技术栈。另一个心得是T3 虽然解决了接口层的类型断裂但数据库 Schema 设计依然是你最大的瓶颈。工具再强也不会替你把表关系设计好。把精力花在梳理业务模型上做成什么样都不会太差。最后分享一个调试小技巧遇到 tRPC 接口报错时不要只看浏览器控制台server 端日志和 tRPC 的错误格式里往往带着路由名和错误码先看是BAD_REQUEST还是UNAUTHORIZED还是INTERNAL_SERVER_ERROR再按图索骥。这个习惯能让你在排查问题时少走至少一半弯路。 
长河君 · 2026/10/28 7:12:46 · 阅读 1.2k t3code全栈开发：用类型安全与tRPC根治前后端联调痛点
我见过太多全栈项目死在了联调环节。后端把接口字段改了个名前端在代码里全局搜了半天才找到调用点Swagger 文档明明写着 string实际返回 null就算一切正常前后端的类型定义也是各写各的谁都不敢动。后来我开始尝试用 t3code 这套方案也就是社区里经常说的 T3 Stack算是把这类问题从根上解决了一大部分。一句话概括 t3code 是什么以 Next.js 为应用宿主以 TypeScript 贯穿前后端用 tRPC 替代传统 REST 接口层用 Prisma 管理数据库模型和迁移再用 Tailwind CSS 解决样式NextAuth.js 处理认证。你不用担心它又是一个绑架你的全家桶框架因为 create-t3-app 给了你一堆开关不想要的东西可以不选。它的核心思路不是帮你写好所有代码而是让类型从数据库、服务端、客户端一路亮绿灯改一个字段名所有没有同步修改的地方立刻编译报错而不是上线之后才暴露问题。这篇文章我会从“为什么这么选”开始讲起然后给出一套完整可复现的搭建流程最后把我实际踩过的坑按故障现象整理成速查表。如果你正在做中小型产品、想快速验证一个想法或者纯粹想找一个全栈开发的顺手姿势这篇内容应该能帮你省下不少试错时间。1. 先搞清楚 t3code 这套组合拳打的是什么痛点1.1 全栈项目最大的隐形成本类型断裂传统全栈项目最常见的状态是前端一个仓库、后端一个仓库或者勉强放在同一个仓库里但接口层用的是 REST 约定。于是同一份业务数据要出现在四个地方数据库迁移文件里的字段定义、后端 DTO 的类型、前端手写的 interface、以及早就没人维护的 Swagger 文档。任何一次字段改动至少得同步四个位置少改一个就埋一颗雷。我遇到过一个很典型的例子订单列表接口返回的字段叫 goodsName前端同事参照旧文档写的 interface 是 productName。联调的时候列表一直显示空内容排查了大半天最后发现两边都没写错就是字段名对不上。这类问题本质上不是技术难点而是“信息在不同位置重复存放”的必然结果。就像两个人约见面一个说东门一个理解成西门谁都没错但就是见不到。当项目规模变大、参与人数变多之后这种类型断裂问题会指数级放大。接口文档更新了但没人看后端重构了参数但前端不知道类型对不上只能在运行时靠 console.log 逐层找。这些消耗在“对齐信息”上的时间往往比写业务逻辑本身还多。1.2 T3 的设计哲学类型安全不是偏执是效率T3 Stack 的核心精神只有四个字类型安全。它的做法很有意思——我不靠文档来约定接口我把类型本身变成约定。Prisma 的 schema 文件是数据库的权威定义tRPC 的 router 是后端接口的权威定义前端通过自动生成的类型和 hooks 去调用后端中间不手写任何一个接口签名。从实际操作层面看这意味着改一个字段名如果后端 router 改了、Prisma client 重生成之后前端某处还引用旧字段编译器会直接把错误标出来。你不需要运行任何环境、不需要 mock 数据、不需要对着文档猜就能在编写阶段发现断裂点。用我同事的话说“以前是上线前提心吊胆现在是编译不过根本提不了。”T3 还有一个组织方式上的理念叫“纵向切片”不是传统的 controller / service / model 纵向分层而是一个功能从页面组件到数据库查询完整地走一遍。对中小项目来说这种组织方式让每个功能相对独立改帖子模块不会影响用户模块维护起来直观很多。社区里也常说 T3 是“约定而非框架”它不强求你每个项目都用全套工具而是提供一套默认合理的组合。1.3 这套方案到底适合谁先说结论它最适合中小型 SaaS、内部工具、MVP 验证和个人全栈项目。这类项目有一个共同点——业务逻辑的复杂度不算高但迭代速度要求快你不想花大量时间在接口层做重复劳动。反过来如果你的系统对多租户数据隔离极其复杂或者你们已经重度依赖一套成熟的 REST 生态甚至每个 API 都要独立部署到边缘节点追求冷启动性能那 t3code 就不太适合。tRPC 更适合单体全栈应用而不是微服务化的开放平台。认清适用边界才能在不同方案之间做出不拧巴的选择。2. T3 核心选型逐个拆解为什么是它们而不是别人2.1 Next.js App Router前后端住在同一个进程T3 选择 Next.js 当宿主我认为最核心的理由是它让“前端页面”和“后端服务”不再割裂。Next.js 本身是一个 React 框架但它的 App Router 支持服务端组件、路由处理器、Server Actions。你可以在页面组件里直接查数据库也可以在同一项目里提供 API 端点前后端共用一套代码仓库、一套依赖、一套部署链路。在 T3 的组合里Next.js 主要承担三件事渲染页面、作为 tRPC 端点的宿主、托管 NextAuth 的认证逻辑。这套架构的一个显著好处是部署简单——你不需要单独维护一个 Node.js API 服务也不需要配置跨域规则因为前端资源和 API 接口在同源下。坦白讲如果你不需要独立扩容后端这个取舍非常合理。当然App Router 的学习曲线比以前 Pages Router 陡一点特别是服务端组件和客户端组件的边界问题。但 create-t3-app 生成的模板已经把常见的坑填平了大半比如“use client”该加在哪、tRPC Provider 挂在哪个层级模板里都是现成的。对新手来说先照着模板跑通再慢慢理解原理比从空项目硬啃要舒服得多。2.2 tRPC接口层从“协商文档”变成“直接调函数”tRPC 是整个 t3code 的灵魂。它的思路说穿了很简单既然前后端都是 TypeScript那为什么接口层不能直接共享类型还要靠 REST 规范、Swagger 注释、手写 SDK 来缝缝补补tRPC 做的事情就是把后端路由函数的参数和返回值类型直接推断给前端调用方。你在浏览器端写api.post.list.useQuery()它看起来就是一个普通 React hook不需要拼接 URL、不需要手动处理 fetch、不需要定义响应类型。这里给不熟悉的朋友打个比方传统 REST 调用像寄快递你得写清楚地址、包裹内容、收货确认tRPC 像两个人直接视频通话你刚开口对方就明白你要什么返回结果也是即时当面告诉你。整个过程由 TypeScript 编译器在职守类型错了当场报错而不是等到运行时才发现“寄错了包裹”。很多人第一次听 tRPC 会担心“把所有后端函数直接暴露给前端安全吗”。实际上 tRPC 只是暴露一个统一的/api/trpc端点所有路由逻辑都跑在服务端浏览器拿到的只是执行结果你完全控制哪些 procedure 是公开的、哪些需要登录才能调用。它并没有把服务端代码直接下载给客户端这个疑虑可以打消。2.3 Prisma数据库结构的“单一事实来源”Prisma 在 t3code 里扮演的是“数据库权威定义”的角色。它用一个 schema 文件描述数据模型、字段类型、表关系然后根据这个文件生成类型安全的数据库客户端。你在 TypeScript 里写ctx.db.post.findMany()得到的对象是强类型的字段名、类型、可选性全部由 schema 推导出来写错了 IDE 立刻标红。Prisma 和其他 ORM 最大的区别是 schema 优先。你不在代码里散落地定义表结构所有改动都从 schema 开始然后通过迁移脚本同步到数据库。这样的好处是代码里的类型、数据库里的表、迁移历史里的记录三方永远保持一致。你也不会再遇到“代码里的字段和数据库对不上”这种低级问题。不过要诚实说一句Prisma 在复杂查询和原生 SQL 场景下会有一些限制。如果你需要特别复杂的联表和聚合逻辑Prisma 的 API 会比较啰嗦。但 T3 本身提供了一条逃生通道——你可以在 tRPC 路由里直接写ctx.db.$queryRaw执行原生 SQL。这不是什么非黑即白的问题知道哪里该用工具、哪里该自己写才是工程能力。2.4 Tailwind CSS 和 NextAuth.js默认武器足够省心T3 里 Tailwind CSS 不是必须项它的角色是提供原子化的 CSS 工具类让你不需要在页面和样式文件之间来回切换。有些人觉得 Tailwind 的 class 名很长不够“优雅”但我实际用下来的感受是对于全栈快速迭代它确实省事。你不是在花时间给 class 命名而是在组件内部直接完成样式调整改起来也特别快。NextAuth.js 则承担认证方案。它默认支持各种 OAuth 提供商也支持 Credentials 登录。T3 模板里把 NextAuth 和 Prisma 的 Adapter 接好了你在 schema 里定义好 User、Account、Session 这些模型登录功能就能跑起来。对于绝大多数中小项目来说自己从零写一套 Session 管理不值得NextAuth 是经过验证的默认选择。2.5 和传统方案对比REST Swagger vs GraphQL codegen vs T3很多人会问为什么不用 REST 或者 GraphQL它们各有各的好但场景不一样。方案类型安全学习成本适合场景主要痛点REST Swagger弱靠手写或插件生成低公开 API、开放平台文档和实现容易脱节类型靠人维护GraphQL codegen强但有额外 schema 语言中数据聚合复杂的前端驱动需要维护 resolver 和 codegen 流程tRPC最强类型即契约低TS 开发者内部全栈应用、产品型项目不适合公开 API前后端需同仓库或共享类型从这个对比可以看出来tRPC 并不是要取代 REST 或 GraphQL而是找到了一个更适合“自己人用”的中间地带。如果你的产品是给内部用户或自己的前端用搞一套完整的接口文档体系确实是浪费。这个选型逻辑比单纯比较“谁更先进”要实用得多。3. 手把手搭一个 t3code 项目从初始化到线上3.1 初始化create-t3-app 的交互选项怎么选初始化 t3code 项目最无脑的方式就是官方脚手架。我在写这篇内容时create-t3-app 已经到 7.x命令依然是npx create-t3-applatest my-t3-app执行之后它会问你几个问题包括项目名、想启用哪些技术模块。我的建议是第一次先全选跑通之后再看哪些不需要就移除。重点提一下它会让你在 Prisma 和 Drizzle 之间二选一如果你没有特别的偏好或者刚接触先选 Prisma 会更稳文档和社区资源都更丰富。初始化完成后的目录结构长这样my-t3-app/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── app/ │ │ └── api/trpc/[trpc]/route.ts │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ ├── root.ts │ │ │ └── trpc.ts │ │ └── db.ts │ ├── utils/ │ │ └── api.ts │ └── env.mjs └── package.json看到这个结构不用慌它已经把核心的关注点划分得很清楚prisma管数据模型server/api/routers放后端逻辑utils/api是前端调用 tRPC 的入口env.mjs统一做环境变量校验。后面的操作都围绕这几个目录展开。3.2 定义数据模型从 Prisma Schema 开始假设我们要做一个极简的帖子应用用户登录后可以发帖游客可以看帖子列表。首先在prisma/schema.prisma里定义模型model Post { id String id default(cuid()) title String content String? createdAt DateTime default(now()) updatedAt DateTime updatedAt createdBy User relation(fields: [createdById], references: [id]) createdById String } model User { id String id default(cuid()) name String? email String unique posts Post[] accounts Account[] sessions Session[] }这里我故意把title设为必填、content设为可选这样后面可以直观地看到 tRPC 的输入校验怎么和类型对齐。关系方面一个用户有多个帖子帖子必须属于一个用户。如果开了 NextAuth还需要在 schema 里补上Account、Session、VerificationToken这三个模型模板默认会生成不用自己手敲。写完 schema 后执行npx prisma migrate dev --name init这条命令会创建数据库表、生成 Prisma Client、更新类型定义。注意它需要DATABASE_URL环境变量已经配置好本地最简单的方式是用 SQLite直接把连接串写成file:./db.sqlite零配置就能跑起来。真到了生产环境再换 PostgreSQL连接串一换代码基本不用动。3.3 创建 tRPC Router让业务逻辑可被前端调用接着进入src/server/api/routers/post.ts创建一个帖子路由。我用两类 procedure 分别演示公开接口和登录接口import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure .query(async ({ ctx }) { return ctx.db.post.findMany({ orderBy: { createdAt: desc }, include: { createdBy: { select: { name: true } } }, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1, 标题不能为空), content: z.string().optional(), }) ) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, createdById: ctx.session.user.id, }, }); }), });这段代码有几个值得注意的点。第一publicProcedure不需要登录protectedProcedure会自动检查 Session没登录直接抛UNAUTHORIZED你不需要在每个路由里重复判断。第二input用 zod 定义它既是运行时校验也是静态类型推断的来源前端传参时类型和校验规则完全共享。第三ctx.db是模板注入的 Prisma Clientctx.session是当前登录用户信息这些东西由 tRPC 的 context 统一组装。创建完路由之后记得回到src/server/api/root.ts注册export const appRouter createTRPCRouter({ post: postRouter, }); export type AppRouter typeof appRouter;AppRouter这个类型是整个前后端共享的关键。前端所有的 hooks 类型都从它推导后端每新增一段逻辑前端不需要手动同步任何类型定义。3.4 前端页面调用useQuery 和 useMutation打开src/app/page.tsx或者自己新建一个客户端组件就可以直接调用接口了use client; import { api } from ~/utils/api; export default function PostList() { const { data, isLoading } api.post.list.useQuery(); const createPost api.post.create.useMutation(); const handleSubmit async () { await createPost.mutateAsync({ title: 测试标题, content: 测试内容 }); }; if (isLoading) return div加载中.../div; return ( div button onClick{handleSubmit}新建帖子/button ul {data?.map((post) ( li key{post.id} {post.title} - {post.createdBy?.name} /li ))} /ul /div ); }这里有个新手特别容易踩的坑tRPC 的useQuery和useMutationhooks 只能在客户端组件里使用所以组件顶部必须加use client。如果你在服务端组件里调这个 hook会直接报错。服务端组件想读取数据应该用 tRPC 的服务端调用器caller而不是 React hooks。模板里没有直接展示这个用法我在实际项目中习惯用一个 helper 包一下但初期先把 hooks 用顺就够了。从这个调用代码能看出什么你不需要写fetch(/api/trpc/post.list)不需要手动处理 JSON 序列化不需要定义响应类型。data的类型直接从appRouter推导过来如果后端改了返回结构这里编译就红了。3.5 把认证接进来NextAuth 的正确打开方式T3 模板已经把 NextAuth 的初始化代码放在src/server/auth.ts里默认接好了 PrismaAdapter。你真正要做的只有两件事配置环境变量以及决定用哪种登录方式。.env里至少要配这些DATABASE_URLfile:./db.sqlite NEXTAUTH_SECRET随便一个足够长的随机字符串 NEXTAUTH_URLhttp://localhost:3000如果你要接入 GitHub、Google 这类 OAuth 提供商还要在 schema 里保证Account模型存在然后在auth.ts的 providers 数组里填入对应的 Client ID 和 Client Secret。如果你不想接第三方登录也可以用 CredentialsProvider 自己实现账号密码登录但密码哈希这类事情就得自己处理了。我的建议是能走 OAuth 就走 OAuth省心又安全。认证和 tRPC 是配合工作的NextAuth 会把 Session 放进 tRPC 的 contextprotectedProcedure内部先检查ctx.session没有就抛错。前端在调用protectedProcedure的接口时如果弹了UNAUTHORIZED你就知道当前用户没登录或者登录已过期直接引导去登录页。这套链路在 T3 里是天然打通的不需要额外写中间件。3.6 部署到生产Vercel 上最容易出问题的地方t3code 项目部署到 Vercel 很方便因为 Next.js 本来就是 Vercel 家的产品。但你如果以为 push 到 GitHub 就能一键上线那就太天真了。最容易出问题的地方永远是数据库和构建阶段。第一本地用的 SQLite 文件是存在本地磁盘的Vercel 的函数运行环境是临时文件系统每次重新部署都会清空。也就是说本地辛辛苦苦写的测试数据部署上去可能只剩一个空数据库。生产环境请务必换成托管 PostgreSQLNeon、Supabase、Railway 都行只需要改DATABASE_URL。第二不要在 Vercel 的构建命令里跑prisma migrate deploy。比较稳妥的做法是把迁移单独放到发布流程里执行比如本地先跑prisma migrate deploy再部署或者用 GitHub Actions 在跑完测试之后统一迁移。否则一旦某个迁移有问题构建和部署都会卡住排查起来很痛苦。第三Vercel 的环境变量配置页面和本地.env有点区别——值不要带引号粘贴进去就行了。我之前犯过一次错把.env里带引号的值直接复制到 Vercel结果连接串里多了两个引号字符数据库连接失败页面全是 500。这类问题看起来低级但确实会真实发生。4. 实操中我踩过的坑按故障现象速查4.1 改了 Prisma Schema但 tRPC 返回的类型没变这个场景几乎每个用 T3 的人都会遇到在schema.prisma里加了published Boolean字段migration 也跑完了但前端代码里post.published一直标红。原因不是 tRPC 的问题而是你没有重新生成 Prisma Client。Prisma 是根据生成的 client 文件提供类型的schema 变了不代表 client 会自动变。解决办法很简单npx prisma generate如果你是先改 schema 再跑prisma migrate dev它会自动调用 generate。但如果只改了数据库或者单独更新了依赖就容易漏这一步。我的习惯是把 generate 写进项目的 pretest 脚本里确保每次自动检查前都生成最新类型避免科室里出现“我明明改了为什么报错”的假象。4.2 开发环境数据库连接被占满 / 热重载崩溃Next.js 开发模式下每次保存文件都会触发热重载如果你在代码里直接new PrismaClient()每次重载都会创建一个新的实例连接数会肉眼可见地飙升最后报“Too many connections”。T3 模板其实已经在src/server/db.ts里处理了这个坑——它用 globalThis 做单例缓存开发模式下所有热重载共享同一个 PrismaClient。你只要记住不要自己到处new PrismaClient()要用模板提供的db对象。很多自定义代码翻车就是因为绕开了默认封装。// 推荐模板默认 import { db } from ~/server/db; // 不推荐会炸连接池 import { PrismaClient } from prisma/client; const prisma new PrismaClient();4.3 部署后接口全部 500日志显示环境变量缺失在本地跑得好好的一部署到 Vercel 就 500最典型的原因就是环境变量没配齐。Vercel 不会自动读取你本地.env文件你需要在项目设置里的 Environment Variables 手动填入关键配置DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL以及业务上用到的第三方密钥。这里有一个隐蔽的坑——T3 项目的src/env.mjs会在构建阶段校验环境变量缺失的变量会让整个构建失败而不是运行时才报错。这其实是好事它把问题前移了但你第一次接触时可能会觉得“怎么连构建都不过”。解决方式就是打开 Vercel 的构建日志看看哪一行校验报错缺哪个补哪个就好。4.4 登录回调地址不对OAuth 一直失败OAuth 登录配置好后在本地测试正常部署到线上就不行点登录按钮出来一个redirect_uri不匹配的错误。这个 90% 是NEXTAUTH_URL设错了。NextAuth 在生成回调地址时依赖NEXTAUTH_URL或生产环境下的部署域名。如果你忘了设置或者设置成了http://localhost:3000那回调地址自然对不上。去授权平台的回调白名单里把生产域名加上同时确保NEXTAUTH_URL写的是线上地址。这个配置是认证链路的基石值得在部署清单里单独打勾。4.5 问题速查表故障现象排查方向解决办法修改 Prisma 后类型没更新Prisma Client 未重新生成执行npx prisma generatetRPC 调用返回 401调用了 protectedProcedure 但未登录检查 Session 状态引导用户登录开发时连接数暴涨PrismaClient 被反复实例化使用src/server/db.ts的全局单例Vercel 部署后所有接口 500环境变量缺失或带引号补全DATABASE_URL、NEXTAUTH_SECRET等变量OAuth 登录报 redirect_uri 错误NEXTAUTH_URL与白名单不一致配置线上域名确保回调地址匹配Query 报 missing required inputzod 校验与传入参数不一致检查前端传参与后端 input schema 是否对齐部署后本地数据消失SQLite 文件在临时文件系统被清空生产环境换托管 PostgreSQL速查表里的每一行都是真实存在过的教训不是网上抄来的。前端传参和 zod 校验不一致那一条尤其隐蔽因为类型上可能没问题但运行时校验会拦下来。写 tRPC 路由时先想清楚“这个接口接受什么”再用 zod 把边界卡住能省掉大量联调问题。5. 用了一段时间之后我的一些个人体会5.1 什么时候该用什么时候别硬上t3code 用顺了确实舒服但它不是万能药。我自己的判断标准很简单如果这个项目的接口主要是给自家人用前端是 Next.js 或者 React后端的复杂度在单体应用范围内那 t3code 会非常趁手。反过来如果我要做一个开放平台接口要给别人调用、要计费、要兼容多语言 SDK那 REST 仍然是更通用的选择因为 tRPC 的优势在跨出 JavaScript 生态之后就消失了。团队的技术背景也要考虑。如果你们整个团队都是 TypeScript 开发者引入 t3code 的摩擦非常小。但如果有大量后端同学不熟 TypeScript突然让他们接受“数据库查询直接暴露给前端层”这套思路可能会有点别扭。技术选型永远是场景优先不是流行度优先。5.2 可以怎么继续扩展t3code 搭出来的项目不是玩具它就着这套基础可以继续往上盖楼。等业务复杂起来你可以把项目改造成 pnpm monorepo把packages/db、packages/api、packages/web拆开类型依然在包之间共享想加测试可以用 Vitest 给 tRPC 路由写单元测试因为 router 是纯函数逻辑mock 掉 context 里的 db 就可以跑非常方便想换数据访问层新的 T3 模板支持 Drizzle它比 Prisma 更轻量SQL 风格更直接适合喜欢原生 SQL 的开发者。还有一个方向值得花时间研究对比一下 tRPC 和 Next.js Server Actions 的适用场景。Server Actions 在表单提交场景效率惊人tRPC 在需要通用类型安全接口层的场景更稳。两者不完全冲突但你想清楚边界能避免很多架构上的纠结。我最近的几个项目里简单表单直接用 Server Actions复杂数据流走 tRPC体验反而比只用一种更好。5.3 几个零散心得如果非要用一句话概括我对 t3code 的态度那就是“工具真正能帮你省时间的前提是你先愿意花时间理解它为什么这么设计”。我见过太多人复制一段模板代码跑通就丢一边遇到类型报错第一反应是删掉类型最后用成了“带类型的普通全栈项目”那真的白瞎了这个技术栈。另一个心得是T3 虽然解决了接口层的类型断裂但数据库 Schema 设计依然是你最大的瓶颈。工具再强也不会替你把表关系设计好。把精力花在梳理业务模型上做成什么样都不会太差。最后分享一个调试小技巧遇到 tRPC 接口报错时不要只看浏览器控制台server 端日志和 tRPC 的错误格式里往往带着路由名和错误码先看是BAD_REQUEST还是UNAUTHORIZED还是INTERNAL_SERVER_ERROR再按图索骥。这个习惯能让你在排查问题时少走至少一半弯路。