1. 项目概述与设计思路拆解1.1 t3code 到底解决什么问题先说结论t3code 是我最近一直在用的一套全栈开发脚手架方案核心思路是把当前 TypeScript 生态里最能打的几个工具——Next.js、tRPC、Prisma、Tailwind CSS——按“端到端类型安全”的逻辑串起来形成一个从数据库到界面层全程类型推导、几乎不需要手工维护接口文档的闭环。很多同学第一次看到 t3code 这个名字可能会疑惑其实它源自 T3 Stack 的那套理念这里的“t3”指代类型安全Typesafe、Tailwind、tRPC 这三者为核心的技术路线code 就是落到代码生成与工程模板上的意思。我最早被这套方案吸引是因为一个非常现实的痛点前后端联调。以前做小项目前端定义一套请求函数后端写一套路由中间还得维护 swagger 文档、接口类型改个字段名可能要看半天代码。t3code 的做法很不一样它把服务端路由和前端调用函数收进同一个类型闭环里接口改动直接由 TypeScript 的类型系统暴露出错误不需要额外引入 codegen 脚本也不用手工同步类型定义这在中小型项目和快速原型阶段省下的时间是肉眼可见的。它适合谁我的判断是适合那些已经会用 TypeScript、但不想在工程化配置上花太多时间的团队也适合个人开发者想在周末快速把一个 idea 变成可运行的产品原型。当然如果你做的是电商秒杀那种超复杂分布式系统这套方案的定位就不太贴合了它更适合业务逻辑清晰、迭代速度快的场景。一句话概括t3code 是一套“让类型安全贯穿始终”的全栈工程模板省掉的是造轮子的时间换来的是改代码时的底气。1.2 为什么走 T3 这条技术路线说实话市面上全栈脚手架并不少像 Next.js 官方模板、create-react-app 加 Express 后端也是常见的组合。那 t3code 为什么偏要选 T3 这套组合关键在于它的取舍逻辑不追求大而全而是把“类型安全”这条主线做到极致。这里有个背景需要说明一下。传统前后端分离架构下前端跑在浏览器里后端跑在 Node.js 或服务器上两端通过 HTTP 请求交互天然存在一道语言边界。即便前后端都用 TypeScript只要没有共享类型这道边界上仍然会产生“类型断裂”——后端改了接口签名前端不一定立刻知道。t3code 的解法是用 tRPC 把函数调用直接暴露为 HTTP 端点前端 import 一个服务端函数就相当于调用接口参数和返回值的类型会自动推导到前端。Prisma 的作用则是给数据库层补上最后一块拼图数据表 schema 定义完成后查询结果类型会自动流向 tRPC再由 tRPC 流向页面组件示意图就是一条没有类型断点的直线数据库 - Prisma - tRPC - React.Tailwind 在这套体系里的角色反而没那么“高深”纯粹是为了开发体验。样式用原子化类名确实减少了很多起名字的纠结也避免了一堆 CSS 文件的碎片化问题。Tailwind 的 JIT 编译对样式类的扫描发生在编译阶段不会影响运行时类型安全但它确实让 UI 迭代速度跟上了 t3code 的前后端节奏。整体走完一圈后你会发现这套组合选型的第一性原则就是能少写的代码就少写能靠类型系统兜住的错误就不靠人肉测试去兜。2. 类型安全项目最核心的设计底座2.1 一个例子看懂端到端类型推导很多没接触过 tRPC 的人会问端到端类型安全具体是啥感觉我拿实际场景举个例子。假设我要做一个团队任务看板数据库里有一张任务表任务所属成员和状态字段要展现在看板卡片上。传统写法里前端常这么干interface TaskResponse { id: string; title: string; ownerName?: string; status: todo | doing | done; } async function getTasks(): PromiseTaskResponse[] { const res await fetch(/api/tasks); return res.json(); }问题在哪这个 TaskResponse 接口是前端手工定义的后端返回数据一旦变了比如 ownerName 改成了 ownerNickname这个接口文件不会自动更新。于是前端拿到的字段是 undefined整个页面可能直接渲染出一片空白而且没有任何编译期报错。用 t3code 的链路写任务查询就不一样。Prisma 的 schema 里定义了 Task 模型tRPC 的 query 函数直接返回 Prisma 查询结果前端的调用代码如下import { api } from ~/utils/api; export function useTasks() { return api.task.getAll.useQuery({ boardId: demo }); }你根本不需要自己声明 TaskResponse。task.getAll 这个函数的入参形状、返回值结构全部由 TypeScript 根据服务端路由自动推断出来。你要是真心想看看返回类型长什么样在编辑器里 hover 一下data变量就能看到完整类型树。这个体验带来的直接好处是重构成本下降。比如我要把 Task 模型里的 ownerName 改成 ownerNickname先改 Prisma schema再迁移数据库然后编译——前端代码里所有引用到 ownerName 的地方会立刻飘红。你不会带着错误上线而是被类型系统按在开发期修完。2.2 Prisma 与 tRPC 的分工逻辑要理解这套闭环得把 Prisma 和 tRPC 各自的分工搞清楚。Prisma 负责的层是“数据形态”它通过 schema.prisma 文件统一定义表、字段、关系、枚举。Prisma Client 生成后查询 Task 记录返回的类型就是 Task { owner?: User | null } 这样的结构化数据这个类型具有了“单一事实来源”地位数据库结构一改类型随之更新就是强制性的不容许出现数据库字段与代码模型脱节的情况。tRPC 负责的层是“传输形态”。它本质上是在服务端定义一组可调用函数每个函数通过 input 验证器定义入参通过 output 或返回值定义出参然后自动把函数调用转换成 HTTP 端点。前端调用 api.task.getAll 时tRPC 库会在底层发起请求但你对请求和响应的类型感知是在编译期完成的。这里有一个必须搞清楚的点tRPC 的类型安全不是“魔法”它是靠 TypeScript 的高级类型体操实现的。tRPC 的 Router 对象定义了每个 procedure 的输入输出类型然后在客户端通过类型推导把整个 Router 类型传递给 api 对象。所以你改动 Router 定义后客户端 api 对象的类型也会跟着变化这种推断是编译期的不会产生运行时开销。由此也可以看出 t3code 对工具角色的定位Prisma 管数据层的确定性tRPC 管传输层的确定性两者叠加就基本消除了接口层“文档与实现不一致”的经典问题。2.3 Prisma 模型定义与迁移实操理论说完直接看字段定义。在 t3code 项目的 prisma/schema.prisma 文件里我一般这样写任务模型model Task { id String id default(cuid()) title String content String? status TaskStatus default(TODO) boardId String board Board relation(fields: [boardId], references: [id]) ownerId String? owner User? relation(fields: [ownerId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt } enum TaskStatus { TODO DOING DONE }有几个细节是新人容易踩坑的。第一带默认值的字段要在 default 里写清楚不然创建记录时可能报缺字段错误第二枚举类型 TaskStatus 需要在同级定义Prisma 的枚举和 TypeScript 的字符串联合类型行为在不同版本里有点差异实际使用时多留意第三外键关系字段必须在同模型里显式声明才能真正产生数据库约束。模型写好后通过prisma migrate dev --name init_task命令生成迁移文件并同步到本地数据库。这一步会生成 Prisma Client后续所有查询都会严格校验字段。迁移完成后你就能在 tRPC 路由里拿到类型完整的查询结果了。3. 实操搭建从零跑通一个 t3code 项目3.1 项目初始化的两种路径t3code 区别于很多脚手架的体验之一就是初始化过程极其“透明”。我习惯先从官方 T3 脚手架开始跑通再按自己的团队规范做裁剪。初始化命令很简单npx create-t3-applatest my-t3-app交互式命令会让你选择要包含哪些模块我的勾选习惯是Next.jsApp Router为了更好的并发渲染能力、tRPC、Prisma、Tailwind CSS、NextAuth 如果涉及登录就选上ESLint 和 Prettier 建议保留别为了省事去掉后面团队协作时统一风格很有用。初始化完成后项目目录结构大概这样my-t3-app/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── server/ │ │ ├── api/ │ │ │ └── root.ts │ │ └── db.ts │ ├── pages/ │ │ └── index.tsx │ └── utils/ │ └── api.ts └── package.jsoncreate-t3-app 的默认结构相当干净但我要说明一点脚手架默认生成的代码只是最小骨架它演示了链路是怎么通的真正开发时你还需要按业务拆模块。我通常会额外创建src/server/api/routers/task.ts这类独立路由文件而不是全部塞在 root.ts 里使用 split-router 的方式组织后续路由一多可维护性会好很多。3.2 数据库连接配置与本地环境项目跑通的第一步是数据库。create-t3-app 默认把 DATABASE_URL 放在 .env 里注意这个文件默认不会进 git敏感信息全靠它隔离。我的本地环境用的 PostgreSQL连接串一般长这样DATABASE_URLpostgresql://postgres:postgreslocalhost:5432/t3code_dev?schemapublic开发初期要注意Prisma 要求连接串里的数据库必须存在。如果你本地没建t3code_dev这个库跑迁移命令会直接报错。我喜欢先手动建库再开始项目createdb t3code_dev然后执行npx prisma migrate dev这个命令会读取 schema.prisma生成迁移文件并应用到数据库同时生成 Prisma Client。注意如果首次运行报 P1001 之类的连接错误八成是数据库没起来或者连接串写错先检查端口和密码别急着怀疑 Prisma 配置有问题。数据库驱动这块新版本的 Prisma 推荐走prisma://协议但它也会自动回退本地开发用 PostgreSQL 连接串没有任何问题。3.3 用 Prisma Studio 检查数据模型数据模型定义完我最常用的一个动作是打开 Prisma Studio 看数据npx prisma studio这条命令会在浏览器里启动一个可视化面板直接以界面方式浏览和编辑数据库记录。它对联调阶段特别有价值因为你能秒看数据库里到底存了什么不用写一堆临时查询脚本。比如我定义了 Task 和 Board 模型后先在 Studio 里手动插入一条 Board 记录然后在 tRPC 的查询里直接按关联关系取数据就知道返回结果里 board 字段嵌套对不对。Studio 本身不生成任何代码它只是 Prisma 生态里的可视化管理工具但对排查关联查询问题很有用。3.4 接入 tRPC 路由的定义方式tRPC 在 t3code 里是传输层核心。以默认的 create-t3-app 模板为例src/server/api/root.ts已经帮你接好了 createTRPCRouter。在这里追加任务路由就非常快import { createTRPCRouter, publicProcedure } from ~/server/api/trpc; import { prisma } from ~/server/db; import { z } from zod; export const taskRouter createTRPCRouter({ getAll: publicProcedure .input(z.object({ boardId: z.string().min(1) })) .query(async ({ input }) { return prisma.task.findMany({ where: { boardId: input.boardId }, include: { owner: true }, orderBy: { createdAt: desc }, }); }), });然后需要把 taskRouter 挂到 root 路由下export const appRouter createTRPCRouter({ task: taskRouter, }); export type AppRouter typeof appRouter;这样设计每个领域的路由独立文件root 只做聚合我测试下来几千行代码的项目依然能保持清晰的模块边界。有人会问 publicProcedure 是什么意思在 tRPC 语境里procedure 是基础调用单元publicProcedure 表示不需要鉴权的开放接口。默认模板里还有一个 protectedProcedure它结合 NextAuth 会话拿到当前登录用户信息。实际业务里任务列表这类公开数据确实可以挂 publicProcedure但涉及写操作或用户私有数据时不要偷懒改成 protectedProcedure避免出现任何人都可以改别人数据的低级漏洞。3.5 前端页面调用完整链路服务端路由定义好了前端调用就近在咫尺。create-t3-app 会在src/utils/api.ts里帮你初始化一个api对象把 AppRouter 的类型注入进去。页面组件里的写法如下import { api } from ~/utils/api; export default function BoardPage({ boardId }: { boardId: string }) { const { data: tasks, isLoading, error } api.task.getAll.useQuery({ boardId, }); if (isLoading) return div正在加载.../div; if (error) return div请求失败{error.message}/div; return ( div classNamegrid gap-4 {tasks?.map((task) ( div key{task.id} classNamerounded border p-4 h3{task.title}/h3 p{task.owner?.name ?? 未分配}/p span{task.status}/span /div ))} /div ); }这里有个体验上的细节容易被忽略useQuery返回的数据天然带有undefined初始状态和异步加载状态因为 tRPC 是基于 react-query 封装的。这意味着组件必须处理 loading、error、success 三种状态避免直接在渲染函数里访问tasks[0].title这类可能为空的属性。我把这条规则当成前端联调阶段的铁律能有效减少白屏问题。做到这一步一个最小闭环就跑通了页面组件 - tRPC 客户端 - 服务端路由 - Prisma 查询 - 数据库再原路返回。整个流程没有手工定义接口类型、没有 mock 数据、没有复制粘贴的类型文件这是 t3code 最让人上瘾的地方。4. 常见问题与排查技巧实录4.1 类型推导不生效的三种情况t3code 链路最舒服的地方是类型推导但也不是没有失效的时候。我遇到最多的情况有三种整理成了一张速查表现象可能原因排查方法前端 api 对象上找不到自定义路由root.ts 没挂载 router打开src/server/api/root.ts确认task: taskRouter已加入前端调用方法提示参数类型错误input 校验器写法和实际参数不匹配检查 z.object 里的字段名、类型和 required 设置Prisma Client 类型和 schema 不符修改 schema 后没有重新生成执行npx prisma generate必要时重启 dev server第一类问题的本质是类型来源不对。t3code 的客户端类型完全依赖AppRouter类型导出root.ts 里漏挂路由前端 api 对象自然不会出现对应方法。这种情况下 TypeScript 不会报错因为 api 对象是普通对象缺少某个方法只会在调用时显示“不存在”查问题时要优先查 root 聚合层而不是业务代码。第二类问题最典型。tRPC 用 zod 作为输入校验器z.object 的定义就是服务端接口的“入参契约”。如果你在路由里定义了z.object({ boardId: z.string() })前端调用就一定要传 boardId类型错误会直接提示在编辑器的调用位置。想给参数默认值就用z.string().default(demo)不要在前端强行拼接字符串充数。第三类问题往往藏在 dev server 的缓存里。Prisma Client 生成在 node_modules/.prisma 目录有时编辑器没刷新导致类型停在旧版本。保险的做法是改完 schema 之后重新生成并重启 dev server避免看到“幽灵类型”。4.2 反向代理与跨域配置踩坑本地开发时我用 Next.js 自带的 dev server 同时处理页面和 API 请求没有遇到跨域问题。但项目一旦拆成前端、后端分开部署tRPC 的跨域配置就会暴露出来。最核心的问题是 tRPC 的 HTTP 请求默认带着content-type: application/json这会被浏览器判定为跨域非简单请求从而触发 preflight 请求。如果服务端没配好 CORS所有请求都会被拦截。常见错误示例服务端只允许了GET, POST方法但 preflight 的OPTIONS请求被拒。我在处理这个问题时在 tRPC 服务端挂了 cors 中间件import cors from cors; app.use( cors({ origin: [http://localhost:3000], methods: [GET, POST, OPTIONS], credentials: true, }) );注意 credentials 这里要跟 NextAuth 的 cookie 方案配合如果开了 cookies 就必须设置否则登录态会丢失。另外如果静态渲染页面请求 tRPC服务端渲染阶段是没有浏览器环境的cookie 不会自动带上需要自己处理 headers 转发这也是个容易让初次使用者困惑的点。4.3 数据库连接池的正确姿势Prisma 在多实例部署场景下有个经典坑默认连接数占用过高导致数据库拒绝连接。我早期的服务跑在 Serverless 平台每次请求都创建新连接高峰期直接把 PostgreSQL 的连接数打满。解决方式很简单在 PrismaClient 初始化时限制连接池大小const globalForPrisma globalThis as unknown as { prisma: PrismaClient }; export const prisma globalForPrisma.prisma ?? new PrismaClient({ log: [query, error, warn], datasources: { db: { url: process.env.DATABASE_URL, }, }, }); if (process.env.NODE_ENV ! production) globalForPrisma.prisma prisma;但如果你在 Serverless 环境跑还要把连接池参数写进连接串里DATABASE_URLpostgresql://postgres:postgreslocalhost:5432/t3code_dev?connection_limit5pool_timeout10这个参数限制单个实例的并发连接数同时设置排队超时避免无限等待。我之前没设置 pool_timeout在高并发时请求会堆积到超时反而让数据库负载更重。加了这个参数后服务端的表现稳定了很多。4.4 NextAuth 与 tRPC 的鉴权配合如果你的 t3code 项目启用了 NextAuthprotectedProcedure 的处理逻辑是先从 cookie 中解析 session再注入到 procedure 的 ctx 中。这里最容易出问题的坑是服务端渲染页面在首次请求时可能还没有 session导致 protectedProcedure 在 SSR 阶段直接抛错。我的处理思路是分场景。纯客户端请求tRPC 能从 cookie 中自动取到 session问题不大但在 getServerSideProps 里发起 tRPC 调用必须在代码层面手动创建带 cookie 的请求上下文否则调用直接失败。更稳妥的方案是让需要鉴权的数据尽量在客户端加载把 SSR 首屏数据限制在不敏感部分这样既能避免鉴权复杂度又能减少首屏阻塞。还有一个容易被忽略的点NextAuth 的 cookie 名在不同环境下会变比如 secure cookie 在 http 下不生效。如果你本地正常、部署到 HTTPS 环境后登录态丢失先查看浏览器的 cookie 设置确认 SameSite 和 Secure 标记是否符合预期这属于排查登录类问题的通用方法论。5. 我的实操总结与后续扩展思考做到这里t3code 的完整套路已经讲完了。就我个人实际体验而言这套方案的日常开发节奏不是“写接口、对文档、调联调”而是“改 schema、加路由、页面直接消费”改动集中在项目内几十个文件里思考重心被拽回到业务本身这是它最大的成就感来源。有几个我后来才意识到的小技巧专门补充一下。第一Prisma 的 include 关系查询里返回的记录如果包含大字段比如 Markdown 正文尽量用 select 按需挑字段避免把所有数据库内容一股脑丢给前端。第二tRPC 的 procedure 支持中间件可以把鉴权、日志、埋点做成 publicProcedure 上的通用中间件别在每个路由里重复写判断。第三Tailwind 的类名虽然方便但稍大的项目一定要约定类名顺序和组件拆分规则否则 JSX 里堆几十个类名依然不可维护。如果项目继续长大t3code 这套骨架可以直接演进的方向有两条一是引入 tRPC 的 subscription 支持把实时看板的更新推给前端二是把路由拆得更细按 feature 为单位组织领域模块而不是继续堆在单一路由文件里。但这些都是后话先把类型安全这条主线跑顺了后续自然会有路可走。最后说一点心态上的建议别指望一套脚手架解决所有工程问题t3code 的真正价值是帮你砍掉大量重复劳动让你把跟类型系统搏斗的时间拿回来提升业务代码质量。踩过的坑都在上面希望你能少走几步弯路。 
长河君 · 2026/10/28 15:25:08 · 阅读 1.2k t3code全栈脚手架：从数据库到前端的端到端类型安全实战
1. 项目概述与设计思路拆解1.1 t3code 到底解决什么问题先说结论t3code 是我最近一直在用的一套全栈开发脚手架方案核心思路是把当前 TypeScript 生态里最能打的几个工具——Next.js、tRPC、Prisma、Tailwind CSS——按“端到端类型安全”的逻辑串起来形成一个从数据库到界面层全程类型推导、几乎不需要手工维护接口文档的闭环。很多同学第一次看到 t3code 这个名字可能会疑惑其实它源自 T3 Stack 的那套理念这里的“t3”指代类型安全Typesafe、Tailwind、tRPC 这三者为核心的技术路线code 就是落到代码生成与工程模板上的意思。我最早被这套方案吸引是因为一个非常现实的痛点前后端联调。以前做小项目前端定义一套请求函数后端写一套路由中间还得维护 swagger 文档、接口类型改个字段名可能要看半天代码。t3code 的做法很不一样它把服务端路由和前端调用函数收进同一个类型闭环里接口改动直接由 TypeScript 的类型系统暴露出错误不需要额外引入 codegen 脚本也不用手工同步类型定义这在中小型项目和快速原型阶段省下的时间是肉眼可见的。它适合谁我的判断是适合那些已经会用 TypeScript、但不想在工程化配置上花太多时间的团队也适合个人开发者想在周末快速把一个 idea 变成可运行的产品原型。当然如果你做的是电商秒杀那种超复杂分布式系统这套方案的定位就不太贴合了它更适合业务逻辑清晰、迭代速度快的场景。一句话概括t3code 是一套“让类型安全贯穿始终”的全栈工程模板省掉的是造轮子的时间换来的是改代码时的底气。1.2 为什么走 T3 这条技术路线说实话市面上全栈脚手架并不少像 Next.js 官方模板、create-react-app 加 Express 后端也是常见的组合。那 t3code 为什么偏要选 T3 这套组合关键在于它的取舍逻辑不追求大而全而是把“类型安全”这条主线做到极致。这里有个背景需要说明一下。传统前后端分离架构下前端跑在浏览器里后端跑在 Node.js 或服务器上两端通过 HTTP 请求交互天然存在一道语言边界。即便前后端都用 TypeScript只要没有共享类型这道边界上仍然会产生“类型断裂”——后端改了接口签名前端不一定立刻知道。t3code 的解法是用 tRPC 把函数调用直接暴露为 HTTP 端点前端 import 一个服务端函数就相当于调用接口参数和返回值的类型会自动推导到前端。Prisma 的作用则是给数据库层补上最后一块拼图数据表 schema 定义完成后查询结果类型会自动流向 tRPC再由 tRPC 流向页面组件示意图就是一条没有类型断点的直线数据库 - Prisma - tRPC - React.Tailwind 在这套体系里的角色反而没那么“高深”纯粹是为了开发体验。样式用原子化类名确实减少了很多起名字的纠结也避免了一堆 CSS 文件的碎片化问题。Tailwind 的 JIT 编译对样式类的扫描发生在编译阶段不会影响运行时类型安全但它确实让 UI 迭代速度跟上了 t3code 的前后端节奏。整体走完一圈后你会发现这套组合选型的第一性原则就是能少写的代码就少写能靠类型系统兜住的错误就不靠人肉测试去兜。2. 类型安全项目最核心的设计底座2.1 一个例子看懂端到端类型推导很多没接触过 tRPC 的人会问端到端类型安全具体是啥感觉我拿实际场景举个例子。假设我要做一个团队任务看板数据库里有一张任务表任务所属成员和状态字段要展现在看板卡片上。传统写法里前端常这么干interface TaskResponse { id: string; title: string; ownerName?: string; status: todo | doing | done; } async function getTasks(): PromiseTaskResponse[] { const res await fetch(/api/tasks); return res.json(); }问题在哪这个 TaskResponse 接口是前端手工定义的后端返回数据一旦变了比如 ownerName 改成了 ownerNickname这个接口文件不会自动更新。于是前端拿到的字段是 undefined整个页面可能直接渲染出一片空白而且没有任何编译期报错。用 t3code 的链路写任务查询就不一样。Prisma 的 schema 里定义了 Task 模型tRPC 的 query 函数直接返回 Prisma 查询结果前端的调用代码如下import { api } from ~/utils/api; export function useTasks() { return api.task.getAll.useQuery({ boardId: demo }); }你根本不需要自己声明 TaskResponse。task.getAll 这个函数的入参形状、返回值结构全部由 TypeScript 根据服务端路由自动推断出来。你要是真心想看看返回类型长什么样在编辑器里 hover 一下data变量就能看到完整类型树。这个体验带来的直接好处是重构成本下降。比如我要把 Task 模型里的 ownerName 改成 ownerNickname先改 Prisma schema再迁移数据库然后编译——前端代码里所有引用到 ownerName 的地方会立刻飘红。你不会带着错误上线而是被类型系统按在开发期修完。2.2 Prisma 与 tRPC 的分工逻辑要理解这套闭环得把 Prisma 和 tRPC 各自的分工搞清楚。Prisma 负责的层是“数据形态”它通过 schema.prisma 文件统一定义表、字段、关系、枚举。Prisma Client 生成后查询 Task 记录返回的类型就是 Task { owner?: User | null } 这样的结构化数据这个类型具有了“单一事实来源”地位数据库结构一改类型随之更新就是强制性的不容许出现数据库字段与代码模型脱节的情况。tRPC 负责的层是“传输形态”。它本质上是在服务端定义一组可调用函数每个函数通过 input 验证器定义入参通过 output 或返回值定义出参然后自动把函数调用转换成 HTTP 端点。前端调用 api.task.getAll 时tRPC 库会在底层发起请求但你对请求和响应的类型感知是在编译期完成的。这里有一个必须搞清楚的点tRPC 的类型安全不是“魔法”它是靠 TypeScript 的高级类型体操实现的。tRPC 的 Router 对象定义了每个 procedure 的输入输出类型然后在客户端通过类型推导把整个 Router 类型传递给 api 对象。所以你改动 Router 定义后客户端 api 对象的类型也会跟着变化这种推断是编译期的不会产生运行时开销。由此也可以看出 t3code 对工具角色的定位Prisma 管数据层的确定性tRPC 管传输层的确定性两者叠加就基本消除了接口层“文档与实现不一致”的经典问题。2.3 Prisma 模型定义与迁移实操理论说完直接看字段定义。在 t3code 项目的 prisma/schema.prisma 文件里我一般这样写任务模型model Task { id String id default(cuid()) title String content String? status TaskStatus default(TODO) boardId String board Board relation(fields: [boardId], references: [id]) ownerId String? owner User? relation(fields: [ownerId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt } enum TaskStatus { TODO DOING DONE }有几个细节是新人容易踩坑的。第一带默认值的字段要在 default 里写清楚不然创建记录时可能报缺字段错误第二枚举类型 TaskStatus 需要在同级定义Prisma 的枚举和 TypeScript 的字符串联合类型行为在不同版本里有点差异实际使用时多留意第三外键关系字段必须在同模型里显式声明才能真正产生数据库约束。模型写好后通过prisma migrate dev --name init_task命令生成迁移文件并同步到本地数据库。这一步会生成 Prisma Client后续所有查询都会严格校验字段。迁移完成后你就能在 tRPC 路由里拿到类型完整的查询结果了。3. 实操搭建从零跑通一个 t3code 项目3.1 项目初始化的两种路径t3code 区别于很多脚手架的体验之一就是初始化过程极其“透明”。我习惯先从官方 T3 脚手架开始跑通再按自己的团队规范做裁剪。初始化命令很简单npx create-t3-applatest my-t3-app交互式命令会让你选择要包含哪些模块我的勾选习惯是Next.jsApp Router为了更好的并发渲染能力、tRPC、Prisma、Tailwind CSS、NextAuth 如果涉及登录就选上ESLint 和 Prettier 建议保留别为了省事去掉后面团队协作时统一风格很有用。初始化完成后项目目录结构大概这样my-t3-app/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── server/ │ │ ├── api/ │ │ │ └── root.ts │ │ └── db.ts │ ├── pages/ │ │ └── index.tsx │ └── utils/ │ └── api.ts └── package.jsoncreate-t3-app 的默认结构相当干净但我要说明一点脚手架默认生成的代码只是最小骨架它演示了链路是怎么通的真正开发时你还需要按业务拆模块。我通常会额外创建src/server/api/routers/task.ts这类独立路由文件而不是全部塞在 root.ts 里使用 split-router 的方式组织后续路由一多可维护性会好很多。3.2 数据库连接配置与本地环境项目跑通的第一步是数据库。create-t3-app 默认把 DATABASE_URL 放在 .env 里注意这个文件默认不会进 git敏感信息全靠它隔离。我的本地环境用的 PostgreSQL连接串一般长这样DATABASE_URLpostgresql://postgres:postgreslocalhost:5432/t3code_dev?schemapublic开发初期要注意Prisma 要求连接串里的数据库必须存在。如果你本地没建t3code_dev这个库跑迁移命令会直接报错。我喜欢先手动建库再开始项目createdb t3code_dev然后执行npx prisma migrate dev这个命令会读取 schema.prisma生成迁移文件并应用到数据库同时生成 Prisma Client。注意如果首次运行报 P1001 之类的连接错误八成是数据库没起来或者连接串写错先检查端口和密码别急着怀疑 Prisma 配置有问题。数据库驱动这块新版本的 Prisma 推荐走prisma://协议但它也会自动回退本地开发用 PostgreSQL 连接串没有任何问题。3.3 用 Prisma Studio 检查数据模型数据模型定义完我最常用的一个动作是打开 Prisma Studio 看数据npx prisma studio这条命令会在浏览器里启动一个可视化面板直接以界面方式浏览和编辑数据库记录。它对联调阶段特别有价值因为你能秒看数据库里到底存了什么不用写一堆临时查询脚本。比如我定义了 Task 和 Board 模型后先在 Studio 里手动插入一条 Board 记录然后在 tRPC 的查询里直接按关联关系取数据就知道返回结果里 board 字段嵌套对不对。Studio 本身不生成任何代码它只是 Prisma 生态里的可视化管理工具但对排查关联查询问题很有用。3.4 接入 tRPC 路由的定义方式tRPC 在 t3code 里是传输层核心。以默认的 create-t3-app 模板为例src/server/api/root.ts已经帮你接好了 createTRPCRouter。在这里追加任务路由就非常快import { createTRPCRouter, publicProcedure } from ~/server/api/trpc; import { prisma } from ~/server/db; import { z } from zod; export const taskRouter createTRPCRouter({ getAll: publicProcedure .input(z.object({ boardId: z.string().min(1) })) .query(async ({ input }) { return prisma.task.findMany({ where: { boardId: input.boardId }, include: { owner: true }, orderBy: { createdAt: desc }, }); }), });然后需要把 taskRouter 挂到 root 路由下export const appRouter createTRPCRouter({ task: taskRouter, }); export type AppRouter typeof appRouter;这样设计每个领域的路由独立文件root 只做聚合我测试下来几千行代码的项目依然能保持清晰的模块边界。有人会问 publicProcedure 是什么意思在 tRPC 语境里procedure 是基础调用单元publicProcedure 表示不需要鉴权的开放接口。默认模板里还有一个 protectedProcedure它结合 NextAuth 会话拿到当前登录用户信息。实际业务里任务列表这类公开数据确实可以挂 publicProcedure但涉及写操作或用户私有数据时不要偷懒改成 protectedProcedure避免出现任何人都可以改别人数据的低级漏洞。3.5 前端页面调用完整链路服务端路由定义好了前端调用就近在咫尺。create-t3-app 会在src/utils/api.ts里帮你初始化一个api对象把 AppRouter 的类型注入进去。页面组件里的写法如下import { api } from ~/utils/api; export default function BoardPage({ boardId }: { boardId: string }) { const { data: tasks, isLoading, error } api.task.getAll.useQuery({ boardId, }); if (isLoading) return div正在加载.../div; if (error) return div请求失败{error.message}/div; return ( div classNamegrid gap-4 {tasks?.map((task) ( div key{task.id} classNamerounded border p-4 h3{task.title}/h3 p{task.owner?.name ?? 未分配}/p span{task.status}/span /div ))} /div ); }这里有个体验上的细节容易被忽略useQuery返回的数据天然带有undefined初始状态和异步加载状态因为 tRPC 是基于 react-query 封装的。这意味着组件必须处理 loading、error、success 三种状态避免直接在渲染函数里访问tasks[0].title这类可能为空的属性。我把这条规则当成前端联调阶段的铁律能有效减少白屏问题。做到这一步一个最小闭环就跑通了页面组件 - tRPC 客户端 - 服务端路由 - Prisma 查询 - 数据库再原路返回。整个流程没有手工定义接口类型、没有 mock 数据、没有复制粘贴的类型文件这是 t3code 最让人上瘾的地方。4. 常见问题与排查技巧实录4.1 类型推导不生效的三种情况t3code 链路最舒服的地方是类型推导但也不是没有失效的时候。我遇到最多的情况有三种整理成了一张速查表现象可能原因排查方法前端 api 对象上找不到自定义路由root.ts 没挂载 router打开src/server/api/root.ts确认task: taskRouter已加入前端调用方法提示参数类型错误input 校验器写法和实际参数不匹配检查 z.object 里的字段名、类型和 required 设置Prisma Client 类型和 schema 不符修改 schema 后没有重新生成执行npx prisma generate必要时重启 dev server第一类问题的本质是类型来源不对。t3code 的客户端类型完全依赖AppRouter类型导出root.ts 里漏挂路由前端 api 对象自然不会出现对应方法。这种情况下 TypeScript 不会报错因为 api 对象是普通对象缺少某个方法只会在调用时显示“不存在”查问题时要优先查 root 聚合层而不是业务代码。第二类问题最典型。tRPC 用 zod 作为输入校验器z.object 的定义就是服务端接口的“入参契约”。如果你在路由里定义了z.object({ boardId: z.string() })前端调用就一定要传 boardId类型错误会直接提示在编辑器的调用位置。想给参数默认值就用z.string().default(demo)不要在前端强行拼接字符串充数。第三类问题往往藏在 dev server 的缓存里。Prisma Client 生成在 node_modules/.prisma 目录有时编辑器没刷新导致类型停在旧版本。保险的做法是改完 schema 之后重新生成并重启 dev server避免看到“幽灵类型”。4.2 反向代理与跨域配置踩坑本地开发时我用 Next.js 自带的 dev server 同时处理页面和 API 请求没有遇到跨域问题。但项目一旦拆成前端、后端分开部署tRPC 的跨域配置就会暴露出来。最核心的问题是 tRPC 的 HTTP 请求默认带着content-type: application/json这会被浏览器判定为跨域非简单请求从而触发 preflight 请求。如果服务端没配好 CORS所有请求都会被拦截。常见错误示例服务端只允许了GET, POST方法但 preflight 的OPTIONS请求被拒。我在处理这个问题时在 tRPC 服务端挂了 cors 中间件import cors from cors; app.use( cors({ origin: [http://localhost:3000], methods: [GET, POST, OPTIONS], credentials: true, }) );注意 credentials 这里要跟 NextAuth 的 cookie 方案配合如果开了 cookies 就必须设置否则登录态会丢失。另外如果静态渲染页面请求 tRPC服务端渲染阶段是没有浏览器环境的cookie 不会自动带上需要自己处理 headers 转发这也是个容易让初次使用者困惑的点。4.3 数据库连接池的正确姿势Prisma 在多实例部署场景下有个经典坑默认连接数占用过高导致数据库拒绝连接。我早期的服务跑在 Serverless 平台每次请求都创建新连接高峰期直接把 PostgreSQL 的连接数打满。解决方式很简单在 PrismaClient 初始化时限制连接池大小const globalForPrisma globalThis as unknown as { prisma: PrismaClient }; export const prisma globalForPrisma.prisma ?? new PrismaClient({ log: [query, error, warn], datasources: { db: { url: process.env.DATABASE_URL, }, }, }); if (process.env.NODE_ENV ! production) globalForPrisma.prisma prisma;但如果你在 Serverless 环境跑还要把连接池参数写进连接串里DATABASE_URLpostgresql://postgres:postgreslocalhost:5432/t3code_dev?connection_limit5pool_timeout10这个参数限制单个实例的并发连接数同时设置排队超时避免无限等待。我之前没设置 pool_timeout在高并发时请求会堆积到超时反而让数据库负载更重。加了这个参数后服务端的表现稳定了很多。4.4 NextAuth 与 tRPC 的鉴权配合如果你的 t3code 项目启用了 NextAuthprotectedProcedure 的处理逻辑是先从 cookie 中解析 session再注入到 procedure 的 ctx 中。这里最容易出问题的坑是服务端渲染页面在首次请求时可能还没有 session导致 protectedProcedure 在 SSR 阶段直接抛错。我的处理思路是分场景。纯客户端请求tRPC 能从 cookie 中自动取到 session问题不大但在 getServerSideProps 里发起 tRPC 调用必须在代码层面手动创建带 cookie 的请求上下文否则调用直接失败。更稳妥的方案是让需要鉴权的数据尽量在客户端加载把 SSR 首屏数据限制在不敏感部分这样既能避免鉴权复杂度又能减少首屏阻塞。还有一个容易被忽略的点NextAuth 的 cookie 名在不同环境下会变比如 secure cookie 在 http 下不生效。如果你本地正常、部署到 HTTPS 环境后登录态丢失先查看浏览器的 cookie 设置确认 SameSite 和 Secure 标记是否符合预期这属于排查登录类问题的通用方法论。5. 我的实操总结与后续扩展思考做到这里t3code 的完整套路已经讲完了。就我个人实际体验而言这套方案的日常开发节奏不是“写接口、对文档、调联调”而是“改 schema、加路由、页面直接消费”改动集中在项目内几十个文件里思考重心被拽回到业务本身这是它最大的成就感来源。有几个我后来才意识到的小技巧专门补充一下。第一Prisma 的 include 关系查询里返回的记录如果包含大字段比如 Markdown 正文尽量用 select 按需挑字段避免把所有数据库内容一股脑丢给前端。第二tRPC 的 procedure 支持中间件可以把鉴权、日志、埋点做成 publicProcedure 上的通用中间件别在每个路由里重复写判断。第三Tailwind 的类名虽然方便但稍大的项目一定要约定类名顺序和组件拆分规则否则 JSX 里堆几十个类名依然不可维护。如果项目继续长大t3code 这套骨架可以直接演进的方向有两条一是引入 tRPC 的 subscription 支持把实时看板的更新推给前端二是把路由拆得更细按 feature 为单位组织领域模块而不是继续堆在单一路由文件里。但这些都是后话先把类型安全这条主线跑顺了后续自然会有路可走。最后说一点心态上的建议别指望一套脚手架解决所有工程问题t3code 的真正价值是帮你砍掉大量重复劳动让你把跟类型系统搏斗的时间拿回来提升业务代码质量。踩过的坑都在上面希望你能少走几步弯路。