t3code 这个代号算是我今年亲手从零搭起来的一个全栈项目。说白了它不是一个 Murmur 出来的新框架也不是什么花哨工具链而是一套以 TypeScript 类型安全为轴心的完整开发模板前端用 Next.js后端逻辑收进 tRPC 路由数据库走 Prisma样式用 Tailwind认证交给 NextAuth。这一套组合在圈子里常被叫 T3 Stack而 t3code 就是我在这个技术选型下沉淀出来的项目骨架和踩坑实录。这篇文章想把我在搭建过程中真正有价值的决策、踩过的坑、以及最后留下的工程实践写清楚给那些准备拿起 T3 Stack 做全栈项目的人一个可以参考的真实样本也聊聊为什么“类型安全”这三个字能省掉那么多破事。这个项目适合谁看如果你已经在用 TypeScript 写 React又对 Next.js 的 API Routes 感到似懂非懂或者你想知道数据库、API、前端类型到底能不能共用一份那这篇文章应该能给你一个很具体的答案。1. 为什么 t3code 会把项目压在 T3 Stack 上1.1 先理清“类型安全全栈”到底省了什么我先说结论类型安全全栈不是一个锦上添花的特性它会直接改变你写代码的顺序和沟通成本。传统的前后端分离项目里前端要依赖后端开放的 REST 文档或者一个手写的类型声明文件接口一变前端大部分情况是不知道的——等编译报错已经是在联调时了。T3 Stack 的核心思路是把类型本身当作前后端之间的接口协议数据库字段类型由 Prisma Schema 定义tRPC 路由的输入输出类型由 TypeScript 自动推导前端组件 import 一个被推导好的 hook直接就能拿到带类型的返回值。我在 t3code 里第一次明显感觉到这个优势是写一个用户列表页面。后端有一个getAllUsers的 query返回结构里带有profile关联表的数据。我在 Prisma 里给Profile模型加了个字段前端页面代码完全没动再看浏览器页面上的字段已经自动被 TypeScript 识别到了。没有联调群没有“后端接口改了前端记得跟上”这种需求因为两者本来就在同一个类型系统里。1.2 tRPC 和 API Routes 的取舍像函数调用一样调后端有人会问Next.js 自带 API Routes为什么还要再加一层 tRPC我的答案是API Routes 是 HTTP 层面的解决方案而 tRPC 是类型层面的解决方案。API Routes 要求你手动管理请求路径、校验参数、序列化响应、处理错误每个环节都是手写的也因此每个环节都可能跟类型脱节。tRPC 则把这一层包装成类型安全的函数调用你写的是api.user.getAll.query()但它在浏览器环境会自动通过 HTTP 请求把参数发到服务端路由再把返回值序列化回来全程类型都是推导的不需要你维护任何路由字符串。当然这不是说 REST 就一无是处。如果你的项目有公共 API、有大量第三方调用REST 和 OpenAPI 可能更合适。但对于 t3code 这种前后端同仓库、同语言的内部业务系统tRPC 的性价比非常高。它省掉的不只是写接口文档的时间更省掉了“前端猜后端字段含义”这种沟通摩擦。1.3 三个关键依赖的边界Next.js 只是宿主tRPC 是骨Prisma 是丹田很多初学者会把这几个概念混在一起我建议把它们拆开理解。Next.js 在这里只承担框架宿主角色负责页面渲染、路由处理和 Server Component 的调度。tRPC 是连接层它不负责渲染也不负责数据库只负责“让函数调用变为远程调用”这件事。Prisma 才是数据世界真正的源头你的模型字段、枚举、关系都在这里定义。Tailwind 是纯表现层它跟业务逻辑没有耦合爱用不用。我在 t3code 的架构设计里非常刻意地让这三者保持单方向依赖Prisma Schema 是真理之源tRPC Router 消费 Prisma 的输出Next.js 页面消费 tRPC 的输出。方向一旦反过来代码就会开始乱。比如有人会把 tRPC 调用写到 Prisma 的 seed 脚本里我看了就脑仁疼——那个脚本应该直接用 Prisma Client没必要经过 tRPC 这层 HTTP 逻辑。2. 脚手架跑通之后目录里真正值得警惕的东西2.1 create-t3-app 到底生成了什么先别急着删用npm create t3-applatest t3code初始化项目非常快几分钟就能跑起来。但跑起来之后最容易犯的错是看多了网上那些“精简目录”的教程手痒把默认结构改了。我建议你在项目初期至少保留这几个文件src/server/db.tsPrisma Client 的单例封装开发环境避免热更新创建太多连接。src/server/api/trpc.tstRPC 的初始化文件和上下文类型定义几乎所有路由都依赖它。src/trpc/server.ts/src/trpc/react.tsx服务端调用器和客户端 React Hooks 的桥接层。这些文件不是说不能改而是你会频繁用到它们不如先保持默认等理解透了再优化。我在 t3code 的前两周就是这么干的只新增业务文件不重构脚手架把精力放在熟悉结构上。这里还要提一个细节默认模板会生成app/api/trpc/[trpc]/route.ts这是 tRPC HTTP 网关在 Next.js App Router 下的标准入口。初次看这个文件的人可能会觉得它很“魔法”但展开看它其实就是把收到的 HTTP 请求交给fetchRequestHandler再传一个createContext函数进去而已。理解它之后你调试 tRPC 的报错会方便很多。2.2 App Router 还是 Pages Routert3code 的选择与理由create-t3-app 在很长一段时间里默认使用 Next.js App Router我直接沿用没有切回 Pages Router。原因不复杂App Router 的 Server Component 可以让我在服务端直接调用 tRPC Procedure避免很多组件变成 Client Component页面也更容易拿搜索引擎的分数。但我也必须诚实提醒App Router 的学习曲线明显更陡如果你是第一次接触建议先花半天把一个 React Server Component 和 Client Component 的边界理清楚再来用 tRPC。在 App Router 下t3code 的做法是页面主体逻辑尽量放 Server Component只有需要交互的局部区域比如搜索框、表格操作按钮、筛选器用use client。数据获取统一走服务端调用 tRPC 的createCaller而不是在客户端useQuery。这样首屏 HTML 里已经有数据浏览器端不需要先发一堆请求再渲染骨架屏体验好很多。2.3 补齐 tRPC 客户端 Context否则浏览器里全是 404这里我要说一个特别容易踩、但又特别隐蔽的坑。如果你在非 Server Component 环境调用api.user.getAll.useQuery()而项目里没有在根布局或者TRPCReactProvider里挂载 Context Provider浏览器控制台只会给你一片 404。原因很简单tRPC 客户端的 hooks 需要 Provider 才能拿到正确的 URL 和请求方法Provider 没挂请求路径不会自动注册到 Next.js 的 route handler 上。t3code 的写法是在app/layout.tsx里用TRPCReactProvider包住整个页面Provider 内部再包一层headers()读取服务端返回的 cookies确保服务端渲染和客户端渲染两边拿到的请求头一致。这个细节如果不做部分页面在 SSR 下可能正常一旦客户端导航就出问题Debug 起来非常费劲因为报错不一定指向 Provider。3. Prisma 从 SQLite 迁到 PostgreSQL 时我踩过的三个数据坑3.1 第一个坑SQLite 习惯写进 schemaPostgres 直接给你颜色t3code 开发早期为了零配置我直接用 SQLite 当数据库。本地跑得很爽直到我决定把数据库换成 PostgreSQL准备上生产环境的时候才发现 schema 里有好几个字段是为 SQLite 量身定做的。最典型的是String default()这种写法。SQLite 对空串处理很佛系但 PostgreSQL 里有些字段类型会在空串和空值之间产生语义冲突比如Decimal类型存储空串会直接报错。另一个坑是枚举类型SQLite 不原生支持enumPrisma 会退化成字符串检查一换到 PostgreSQL模型定义就必须显式声明枚举旧数据里如果有枚举外的值迁移会失败。我的建议是从第一天就用 PostgreSQL 或者 MySQL 来开发哪怕本地跑 Docker 也要用生产同款数据库。现在 Docker 起一个 Postgres 只要一分钟不要在“反正后面会换”上面省时间。3.2 第二个坑BigInt 与 Date 在 tRPC 传输层的序列化问题Prisma 里有几个字段类型会在 JSON 序列化时产生意外。最典型的是BigInt。PostgreSQL 的某些计数 ID 用了BigIntPrisma 返回的是一个 JavaScript BigInt 对象可 JSON.stringify 根本不支持 BigInt默认直接抛TypeError: Do not know how to serialize a BigInt。这个问题在没有 tRPC 的时候也存在但因为 tRPC 会自动做序列化报错信息会出现在运行时更隐蔽。t3code 的处理方式是给这些字段定义明确的数据传输对象DTO在 tRPC Router 的返回处就把BigInt转成字符串或者 Number。另外一个常见问题是 Date 对象Prisma 返回的 Date 在 tRPC 里会变成 ISO 字符串前端做时间格式化的时候如果直接new Date(value)还能用但如果拿它做value instanceof Date的判断就会出问题。所以我的原则是跨 tRPC 边界的日期统一用字符串传递显示格式统一在展示层处理绝不把 Date 对象直接往 client 丢。3.3 第三个坑connection pool 和事务隔离级别少一次压测都不知道本地 SQLite 是一次连接一个文件几乎没有并发问题。但 PostgreSQL 在 Serverless 环境下的连接数是非常稀缺的资源尤其是部署到 Vercel 或 Netlify 这类无服务器平台时Prisma Client 如果不做连接池管理每个 Lambda 实例可能都会去抢数据库连接稍微有点流量连接数就爆了。t3code 后面部署到一台小云主机上用常驻 Node 进程跑遇到的情况是Prisma 默认的事务隔离级别在并发写多的时候会产生大量重试异常看起来像是“偶发报错”但压测一上就原形毕露。我建议你在写涉及多表更新的 mutation 时提前想清楚这个事务的隔离级别并且使用 Prisma 的连接池配置比如?connection_limit5pool_timeout2这类参数。平时看起来无关紧要到了并发场景就是能不能扛住压测的分水岭。4. tRPC 路由不是简单拆文件中间件、上下文与错误码设计4.1 从 createTRPCRouter 到隐式依赖先说说 tRPC 路由的组织方式。很多人第一次接触 tRPC会以为它就是把 API Routes 换个写法路由文件拆得多了自然就有结构。但实际上 tRPC 有一个更重要的隐式依赖路由会携带一个共享的 Context。这个 Context 是你每次请求的“环境快照”里面可以放数据库实例、当前登录用户、请求头信息等。所有 Procedure 都能访问这份 Context所以路由设计得好不好很大程度取决于 Context 设计得好不好。t3code 的 Context 里我放了三样东西Prisma Client 实例、session对象可能为 null、以及一个表示“当前请求是否来自客户端”的isClient布尔值。中间件再根据 Context 里的 session 状态决定放行还是拒绝。如果想把 Context 设计好一个习惯是永远不要在生产路由里直接读文件或者请求体所有依赖都通过 Context 注入后续测试会轻松很多。4.2 一个全局 middleware 能省掉多少 if这里的核心是避免在每一个 mutation 里写一大段“如果是管理员就怎么样”的逻辑。t3code 里我套了两层中间件第一层是全局的只做基本日志和耗时记录第二层是“需要登录”的中间件挂在所有需要身份校验的路由组上。这个中间件的写法非常直白const protectedProcedure tRPC.procedure.use(async ({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED, message: 登录后才能执行这个操作, }); } return next({ ctx: { ...ctx, user: ctx.session.user, }, }); });之后任何需要登录的接口都直接用protectedProcedure不需要在业务代码里再判断session。如果你有十几个查询都要做登录校验这一个中间件就能删掉十几遍重复逻辑。更关键的是后面加权限系统也只需要在中间件里多套一层业务代码一行都不用改。4.3 错误码与错误信息的结构约定tRPC 自带的错误码体系已经覆盖了常见情况比如BAD_REQUEST、UNAUTHORIZED、FORBIDDEN、NOT_FOUND、INTERNAL_SERVER_ERROR。但这里有个容易忽略的点默认的message是字面量英文而前端用户根本看不到也不应该看到。我的做法是在前端统一封装一个errorMapper函数把 tRPC 的 error shape 映射成用户可读的中文文案同时把code传给日志系统。另外不要把业务错误全抛成INTERNAL_SERVER_ERROR否则你查日志会疯掉。比如用户传了一个不存在的 ID就应该抛NOT_FOUND权限不够就抛FORBIDDEN。我见过很多半路出家的项目不管什么错误都是BAD_REQUEST排查起来完全靠猜。错误码的语义化是工程成熟度非常显性的信号。5. NextAuth 接入 tRPC 受保护路由的完整链路5.1 为什么在 App Router 下不能直接用旧版 session 写法NextAuth 在 Pages Router 时代最常用的拿 session 方式是getSession()在服务端getServerSideProps里每次请求调用一次。但在 App Router 下推荐的做法是getServerSession()配合authOptions从请求头里恢复 session。t3code 一开始没注意这个区别我照旧用getSession()在 Server Component 里取数据某天突然发现部分页面在刷新时会拿到 null而客户端导航时又是正常的。最后定位下来是因为getSession()依赖的请求上下文在 App Router 的 Server Component 里不一定能拿到完整的 cookies 和 headers导致 session 读取不稳定。换成getServerSession后这个问题就消失了。如果你用 NextAuth v5现在是 Auth.js那一套 API 又会变所以我的建议是不要凭记忆写每次都要确认当前版本对应的官方示例这种基础链路不值得省那两分钟。5.2 Auth.ts 与 tRPC context 的桥接t3code 里最关键的桥接文件是把 tRPC 的 Context 和 NextAuth 的 Session 连起来。基本做法是在createContext里并行调用getServerSession把返回的 session 塞给 tRPC。这里有个实操细节第一次请求时Prisma Client、session 这些对象都会被初始化如果你的选择器频繁创建 PrismaClient热更新阶段会有大量连接残留所以一定记得用全局单例模式。而生成了 session 之后要记得把 session 放到 Context 里而不是每次在路由里重新getServerSession否则你的 query 函数会变得很啰嗦而且没法统一做缓存。5.3 Credentials Provider 的 JWT 坑t3code 早期为了简单用 NextAuth 的 Credentials Provider 实现邮箱密码登录。这个 Provider 默认不会把用户 ID 写进 session而是把整个登录请求交给 JWT 策略。这里有个坑如果你在signIn回调里没有做足够校验或者jwt回调里没有把 userId 赋到 token 上前端拿到 session 时没有 user.id然后 tRPC 中间件就会把明明已经登录的人当成游客。正确做法是在jwt回调里手动写入callbacks: { jwt({ token, user }) { if (user) { token.userId user.id; } return token; }, session({ session, token }) { if (session.user) { session.user.id token.userId as string; } return session; }, }这个看着不复杂但网上能搜到的案例大多只写 GitHub 登录没有注意 Credentials Provider 的特殊性。如果你用第三方 OAuth 登录可能不会触发这个场景但一旦切到账密登录就非常容易卡在这里。6. 部署到生产环境后类型安全救不了你的那些时刻6.1 Vercel Serverless 环境下的 Prisma 连接池坦白说t3code 部署到 Vercel 的第一版是在流量稍大时直接崩掉的。原因跟前面说的数据库连接池高度相关Vercel 的 Lambda 是短生命周期进程每个实例启动时都会初始化 Prisma Client如果数据库连接池的上限配置得太小一有流量波动Prisma 就只能排队等待。而排队时间一旦超过 Lambda 超时阈值用户就会看到 504。我的解决方式其实很“土”在云厂商的数据库参数里提高了最大连接数同时在 Prisma 的连接串上显式设置了connection_limit和pool_timeout让连接等待有上限。如果你用的是 Prisma 官方加速服务那又是另一套配置。总之记住一点本地跑得好不代表生产不会死连接池这个东西一定要在部署前想清楚。6.2 WebSocket 适配器在无状态环境里的噩梦如果想做实时更新很多人第一反应是上 tRPC subscription。但请注意tRPC subscription 默认依赖 WebSocket而 Vercel 这类 Serverless 平台对 WebSocket 的支持非常有限如果你部署到边缘函数WebSocket 长连接更是直接不可用。t3code 后来放弃在 Vercel 上做实时订阅改到了常驻 Node 进程的服务器上WebSocket 才稳定下来。如果你一定要在 Serverless 环境用 subscription建议了解trpc/server的subscription适配器和平台限制。很多项目的实时功能用轮询就足够了不一定非要长连接。千万不要因为“实时”两个字就把架构搞得复杂轮询 短缓存往往在 90% 的场景里都够用。6.3 环境变量与多环境配置zod 校验写在最前面环境变量是部署出错的高发区。t3code 的做法是用一个 zod schema 在启动时校验所有关键环境变量缺哪个直接给你一个清晰的中文报错而不是等你运行到某个接口才炸。比如DATABASE_URL、NEXTAUTH_SECRET、S3_BUCKET这些变量在 config 文件里统一读取并校验。这样做的另一个好处是如果把环境变量集中到一个 TypeScript 文件IDE 提示会非常舒服而且新同事上手时看到这个文件就大概知道项目依赖哪些外部资源。这也是我从很多生产事故里学到的教训说句实话类型安全能保证代码内部不出错但保证不了你部署环境的外部配置不出错多一道启动时校验比什么都强。7. t3code 下一步实时订阅、文件上传、可观测性7.1 用 tRPC subscription 替换定时轮询t3code 现在的消息列表已经改成真实时更新了因为服务端不再受限于无状态环境。tRPC subscription 的写法跟 query 非常接近核心还是在 router 里注册subscription然后通过发布订阅源把更新推给客户端。这里有一个值得注意的设计不要在前端直接调用 subscription 的发布函数所有发布动作都应该由服务端业务触发客户端只能监听。我在实际使用中的体会是tRPC subscription 的代码量比 WebSocket 原生实现少得多可读性也好适合中小型项目。但它对连接状态的恢复处理不如成熟的消息队列所以 websocket 断线重连时的消息补偿还得自己在业务层处理。这部分如果做得不好用户可能错过重要通知。7.2 文件上传不留服务器直接走后端签名 URL很多初学者会把文件上传写成POST /api/upload然后把文件写进服务器磁盘。这在本地开发没事上了生产要么磁盘不够要么负载均衡多个实例之间文件不同步。t3code 的做法是走 Object Storage比如 S3 兼容存储上传逻辑用预签名 URL 实现前端先调用 tRPC 的getUploadUrlmutation传入文件名和类型。后端返回一个短时有效的上传 URL。前端直接用 PUT 或 POST 把文件流推到存储服务不走应用服务器。这个方案既减少服务器带宽压力又能避免接口被恶意塞大文件。我之前踩过一个坑是没有限制上传大小结果被一个同事传了个 2GB 的视频桶直接吃到告警。后来我加上了文件大小和后缀名校验总算没再出事。7.3 加一层可观测性把每次 query 的耗时暴露出来最后我想聊一个没那么炫酷但非常重要的部分可观测性。t3code 在中间件里给每个 tRPC procedure 记录了一条日志包含路径、耗时、状态码、用户 ID。这样一旦线上有问题我可以从日志里很快定位到具体是哪个查询慢而不是等到用户反馈。具体实现也很简单就是给 tRPC 加一个onError处理器和一个耗时中间件。日志不一定要上分布式链路追踪刚开始用控制台输出加一个结构化日志文件就够用。等哪天流量大了再引入 OpenTelemetry 也不迟。这个过程中最有价值的不是某个工具而是“把每一次请求都当成可观测事件”的工程习惯。t3code 这套搭建过程里我印象最深的反而不是某个具体 API而是类型安全带来的正反馈循环数据库结构一变类型跟着变编译就报错修复的速度远快于肉眼排查接口文档。但也正因为它把开发体验拉得很高部署和运维阶段的坑反而容易被忽略。如果你打算用 T3 Stack 做自己的项目我建议不要只盯着框架的花哨功能先把 Context、中间件、错误码、连接池这些基建打扎实很多线上问题是可以提前避免的。