前两个月我准备把团队内部那个知识管理工具重写一遍需求本身不复杂列表、详情、搜索、成员权限撑死再加一个评论功能。可真动手的时候我发现自己最头疼的不是业务逻辑而是前后端联调——接口文档永远赶不上代码变化字段名在中途改一次前端就要跟着猜半天。后来我决定换一种思路直接拿 T3 Stack 从零搭了个项目代号就叫 t3code。现在这个项目已经跑在测试环境里前后端类型完全共享改一个字段全链路报错提醒体验和之前完全是两个世界。这篇文章不是框架官网的文档翻译而是 t3code 这个项目从选型、初始化、业务实现到部署上线的完整记录。重点会放在 tRPC 端到端类型安全是怎么一回事、我在实测里踩过的几个坑以及把项目推到生产环境前必须想清楚的优化点。如果你正打算用 create-t3-app 起一个新项目或者想知道全栈 TypeScript 到底能把开发体验提升到什么程度这篇应该对你有用。1. T3 Stack 选型前的判断t3code 的定位与边界先解释一下 T3 Stack 到底是什么避免有朋友上来就当成了某个具体框架。T3 这个名字来自社区里经常说的 Trifecta特指一组以 TypeScript 为核心的全栈开发组合Next.js 负责应用框架和渲染tRPC 负责前后端 API 调用Prisma 负责数据库建模和访问再加上 Tailwind CSS 做样式。create-t3-app 是社区里非常流行的脚手架工具一条命令就能把这些东西集成到一个项目里。t3code 这个项目里我为什么选了这套组合而不是传统的 Next.js 单独配一个 REST API核心原因只有一个我不想维护两端各自独立的类型定义。以前用 REST 接口前端工程师看一眼接口文档手写一个 interface后端改了字段前端如果不主动去翻文档根本不会发现类型已经对不上了。这种问题在协作里叫信息衰减每经过一层人手协议就失真一点点。T3 Stack 的思路是让 TypeScript 编译器替你把类型从数据库一路推到浏览器组件里数据结构的任何变化都能在编译期暴露出来。但我要先泼一盆冷水T3 Stack 不是万能的。如果你的项目是纯后端服务要暴露给第三方 App 调用那显然是 REST 或 GraphQL 更合适tRPC 要求调用方也在同一个 TypeScript 类型体系里跨语言就玩不转了。如果你的团队只有两三个人写过 TypeScript其他成员全是后端转岗那 T3 Stack 的学习曲线也够喝一壶。它最大的收益场景是前端和后端都在同一个代码仓库里且团队愿意接受类型驱动开发。t3code 能成立靠的正是这个前提。1.1 tRPC 和 GraphQL 的区别以及为什么要选它很多人会把 tRPC 和 GraphQL 放在一起比它们确实都在解决客户端不知道服务端数据结构的问题但思路完全不同。GraphQL 本质上是一份契约语言客户端通过查询字符串声明要什么服务端解析后返回对应结构两端各自维护 schema 文件类型要靠 codegen 生成。tRPC 没有独立 schema服务端 router 本身的 TypeScript 类型直接通过 import type 透传给客户端连 codegen 这步都省了。我用一个比较俗的类比GraphQL 像两个部门之间签正式合同合同内容用专门的语法写两边各拿一份模板对接tRPC 像两个共享同一个大脑的开发者在聊天你说把这个对象给我类型系统自动把你的手递过去拿到的东西和认知里一模一样。t3code 里选 tRPC 的直接理由很现实项目体量不到二十个 API为一个内部系统上 GraphQL 那套分层生态成本明显偏高而 tRPC 的接入成本几乎为零。1.2 什么情况不建议抄这份作业写这篇文章的时候我得把边界说清楚否则很多人照着网上的博客把 T3 Stack 塞进自己的项目里会发现完全使不上劲。除了前面说的跨语言场景还有几种情况不太适合项目需要复杂的开放 API 网关、有重缓存和聚合层需求、团队前端是 Vue 或 Svelte。t3code 是典型的前后端同构应用所有调用方都是我们自己写的 Next.js 组件所以 tRPC 才能发挥最大价值。如果你做的是一款给外部开发者用的 SDK或者需要长期对外提供版本化 API老老实实走 OpenAPI 加 codegen 更稳。2. 初始化一个 t3code环境搭建与目录结构实测我在 t3code 上使用的初始化命令非常直接pnpm create t3-applatest t3code这里我推荐用 pnpm 而不是 npm原因不是玄学是实际安装依赖的磁盘占用和速度差距摆在那里。执行命令之后脚手架会问一串交互式问题很多人在这里就开始犯选择困难症。我根据 t3code 的经验把当时的选择和理由列在下面供你参考。选项我的选择理由Next.js Router 模式App Router新项目没必要守着旧模式服务端组件是 Next 14 之后的主流方向数据库 ORMPrisma文档全、社区大、模型定义直观适合正式项目长期维护样式方案Tailwind CSS默认就是它样式作用域清晰组件库也好接tRPC启用本项目核心不解释认证方案NextAuth.js内部工具需要账号体系先用 Email Provider 跑通后续再换src 目录启用代码结构更干净推荐import alias/默认别名后面在 tsconfig 里配置一个容易忽略的细节是脚手架会问你是否需要 git 初始化我建议选是。t3code 后续改配置的时候能随时 diff 出改动了哪些文件心里踏实。2.1 目录结构以及每个文件是在干嘛的初始化完成后t3code 的目录基本是这个骨架t3code/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── app/ │ │ ├── api/ │ │ │ └── auth/ │ │ ├── layout.tsx │ │ ├── page.tsx │ │ └── posts/ │ ├── pages/ │ │ └── api/ │ │ └── trpc/ │ │ └── [trpc].ts │ ├── server/ │ │ ├── api/ │ │ │ ├── root.ts │ │ │ ├── trpc.ts │ │ │ └── routers/ │ │ ├── auth.ts │ │ └── db.ts │ ├── styles/ │ ├── trpc/ │ │ ├── client.ts │ │ ├── react.tsx │ │ └── server.ts │ └── utils/ │ └── api.ts ├── .env ├── tailwind.config.ts └── tsconfig.json刚接触 tRPC 的人最容易被这里的嵌套绕晕src/pages/api/trpc/[trpc].ts 是 HTTP 入口所有 /api/trpc 的请求都会打到这个文件src/server/api/root.ts 定义 appRouter它是一个聚合根把 postRouter、userRouter 这些子路由合并进去src/server/api/trpc.ts 是每个 tRPC 路由的基础设施里面初始化了 tRPC 实例和上下文src/utils/api.ts 则是客户端用的 API 代理对象里面绑定了 AppRouter 类型。2.2 数据库配置开发用 SQLite上线前再切 Postgrest3code 在开发初期我直接用 SQLite 起步。create-t3-app 默认 DATABASE_URL 就是 sqlite 文件路径零配置就能跑这对快速验证业务逻辑特别友好。.env 文件里大概是这样的DATABASE_URLfile:./db.sqlite如果你一上来就猜生产也要用 SQLite那就错了。SQLite 是文件型数据库部署到无服务环境会遇到磁盘读写和并发写入的麻烦。我的建议是前期开发图快用 SQLite真正上线前把 provider 换到 Postgres。切换方式也不复杂改 schema.prisma 的 provider 字段把 DATABASE_URL 换成 Postgres 连接串然后重新跑 migrate 和 generate。prisma/schema.prisma 里我建了一张最基础的文章表generator client { provider prisma-client-js } datasource db { provider sqlite url env(DATABASE_URL) } model Post { id String id default(cuid()) title String content String? createdAt DateTime default(now()) updatedAt DateTime updatedAt authorId String author User relation(fields: [authorId], references: [id]) }这里要特别说明一个容易踩的坑Prisma 修改 schema 后不能直接重启服务就完事必须运行pnpm prisma generate否则客户端代码引用的类型还是旧的。t3code 前期我至少在这上面浪费了二十分钟后来养成习惯每次改完 schema 立刻跑一次pnpm prisma migrate dev让数据库结构也跟着同步。3. tRPC 的端到端类型安全是如何穿透全栈的t3code 项目里最能体现开发体验提升的就是 tRPC 这套类型穿透机制。服务端写好的 router客户端组件里直接拿类型化方法调用不需要任何手写类型声明。这一节我把从服务端定义到客户端使用的完整链路梳理清楚。3.1 服务端router、procedure 和 zod 输入校验先看一个最简的 postRoutert3code 里主要负责文章列表和创建// src/server/api/routers/post.ts import { z } from zod; import { createTRPCRouter, publicProcedure } from ~/server/api/trpc; export const postRouter createTRPCRouter({ list: publicProcedure .query(async ({ ctx }) { return ctx.db.post.findMany({ orderBy: { createdAt: desc }, }); }), create: publicProcedure .input( z.object({ title: z.string().min(1, 标题不能为空), content: z.string().optional(), }) ) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: input, }); }), });注意这里的细节publicProcedure表示这个接口不需要登录就能访问后期加权限时换成protectedProcedure即可。.input()接收的是一个 zod schema这一步很多人不理解为什么需要我解释一下。TypeScript 的类型系统在编译期很强大但它在运行时完全不做事。数据通过网络传进来的时候服务端拿到的是一堆字符串和对象如果不校验一个错误字段可能导致数据库写入失败或者更糟写入脏数据。zod 的作用就是在服务端入口对输入做真实运行时校验校验通过后的类型能自动推导给后续代码。t3code 里我把所有输入都写成 zod schema相当于给 API 装了一个运行时保险丝。3.2 客户端一行引用类型自动到达服务端定义好之后客户端组件里就可以这样用了use client; import { api } from ~/utils/api; export function PostList() { const { data, isLoading, error } api.post.list.useQuery(); if (isLoading) return p加载中.../p; if (error) return p出错了{error.message}/p; return ( ul {data?.map((post) ( li key{post.id}{post.title}/li ))} /ul ); }这段代码里没有接口路径、没有手动类型注解data的类型会自动成为 Prisma 查询返回的类型包含 Post 表的所有字段。当你把鼠标悬停在data上编辑器的智能提示会直接显示完整结构。这就是 tRPC 的魔力服务端 router 的类型通过 src/utils/api.ts 注入到 React Hooks 泛型里链路完全透明。创建文章也是一样mutation 之后还有缓存刷新逻辑const utils api.useUtils(); const createMutation api.post.create.useMutation({ onSuccess: () { utils.post.list.invalidate(); }, });invalidate是 React Query 提供的缓存失效机制mutation 成功后会主动让列表重新请求数据立刻新鲜。这套写法和传统 REST axios 的区别是后端返回的字段名如果从title改成heading你的前端组件根本编译不过去错误会精准指向哪一行有问题而不是等用户点开页面才发现内容丢了。3.3 跨组件类型引用RouterOutputs 的实际用法等 t3code 的业务越来越复杂你可能会遇到一个情况列表页里已经查到了 Post 数据详情页还需要复用同样的类型定义。这时候不要靠手写 interface 复制一份直接这样引用import type { RouterOutputs } from ~/utils/api; type PostListOutput RouterOutputs[post][list]; type PostItem PostListOutput[number];RouterOutputs是 tRPC 提供的一个类型工具把整个 AppRouter 的输出类型暴露出来。我用这种方式在 t3code 的组件之间共享了大量类型改动 Post 模型时所有用到PostItem的地方都会同步更新真正实现了改一处、全站感知。4. 实跑 t3code 时踩过的四个坑完整排查链路任何框架宣传片都不会告诉你的是真实环境里那些让人抓狂的边角问题。t3code 从开发到部署我完整踩了四个坑每一个都花了不少时间定位这里把排查思路和最终解法一并记录下来希望你不用再走一遍。4.1 坑一App Router 的 Server Component 没法直接调用 React Query Hooks现象是 t3code 的详情页想用服务端渲染我在一个 Server Component 里直接写了api.post.list.useQuery()结果页面一加载就报错浏览器控制台提示大概意思是这个 hook 只能在 Client Component 里使用。我第一反应是去查 React Query 的文档发现确实如此React Query 依赖客户端状态管理Server Component 里不允许调用 hooks。排查链路再往前走一步为什么 t3code 的初始模板里src/trpc/server.ts明明提供了serverClient原因是服务端渲染的数据获取正确姿势不是用 hooks而是用 tRPC 的createCaller直接调用 router。我在详情页里改成这样// 服务端组件里 import { createCaller } from ~/trpc/server; export default async function PostPage({ params }: { params: { id: string } }) { const caller await createCaller(); const post await caller.post.getById({ id: params.id }); return PostContent post{post} /; }这样页面在服务端就把数据拿齐了再把纯展示组件作为 Client Component 传下去。如果你图省事把整个页面都标成use client那也是一种解法但会丢掉服务端渲染带来的首屏收益。t3code 的做法是默认让页面组件保持服务端只有真正需要交互的子组件才标记 client这样首屏 HTML 已经包含数据用户体验更好。4.2 坑二SQLite 在部署环境里频繁报 SQLITE_BUSYt3code 开发期一切正常但在我把 API 路由部署到云端测试环境之后日志里开始频繁出现SQLITE_BUSY: database is locked。刚开始我以为是并发请求太密集后来发现几个实例同时读写同一个 SQLite 文件文件锁机制自然扛不住。排查过程分三步走第一步确认日志里报错的时间点是不是都在请求高峰期第二步检查 Prisma 连接池配置是不是没设置好第三步终于意识到 SQLite 本身的架构就不适合多实例并发。这是个根因层面的问题再怎么调 busy_timeout 也只是缓解不是解决。最后我直接把 datasource 从 sqlite 切换到了 Postgres在云数据库上建了一个最小实例连接串放进环境变量。切换之后 SQLITE_BUSY 彻底消失Prisma 连接池在 Postgres 下也发挥出了正常水平。复盘这个坑我不后悔开发期用 SQLite它确实让 t3code 前期进展飞快只后悔没有更早规划生产环境导致部署阶段额外花了两小时排查。4.3 坑三权限校验写在了 middleware 里却管不住 tRPCt3code 需要登录才能访问某些接口我在 Next.js 的 middleware.ts 里写了权限校验逻辑拦截所有/api/trpc/*路径要求必须带 session。本地测试的时候一切正常部署上去后发现有个接口裸奔了没登录也能访问。排查链路很有意思。我先看 Next.js 的中间件日志发现它确实拦截了请求但显然没有生效。进一步追踪后发现create-t3-app 生成的 tRPC 适配器挂在src/pages/api/trpc/[trpc].ts这个动态路由下而 Next.js 的 middleware 对 API Routes 的执行顺序和 App Router 页面路径并不完全一致某些情况下中间件不会参与。这个行为在不同 Next 版本里表现还不稳定。最终我把权限校验彻底放到了 tRPC 的 context 和 procedure 里这才是 tRPC 推荐的鉴权方式。具体做法是在 createTRPCContext 中读取 session然后定义protectedProcedureexport const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: ctx.session }, }); });这个坑给我的教训很深刻框架的中间件机制再好也不要依赖它做业务鉴权尤其是和 tRPC 这种自带上下文管道的方案一起用应该把安全边界放在最靠近数据访问的地方。4.4 坑四Tailwind 版本更新导致样式全部失效t3code 某次依赖升级之后重新构建发现所有页面的样式都没了浏览器里只有光秃秃的 HTML。查了一圈不是 class 名没生效而是 Tailwind 新版的前置指令变了。以往 Tailwind v3 的样式入口是这三个指令tailwind base; tailwind components; tailwind utilities;到了 Tailwind v4入口改成了import tailwindcss;create-t3-app 在某个时间节点以后生成的新项目默认就是 v4但我这种老项目升级上去postcss 插件和配置文件的兼容会出问题。排查的时候我先用浏览器开发者工具检查了样式表内容发现 CSS 文件几乎是空的再对比官方迁移文档才定位到是入口指令的问题。如果你正在用 create-t3-app 初始化项目我的建议是生成之后先确认 package.json 里 Tailwind 的版本再决定你参考的教程是按 v3 还是 v4 写的。这个版本差异很隐蔽因为项目能编译通过只是样式静默丢失浪费排查时间。5. 优化与部署把 t3code 推到生产环境的收尾工作t3code 功能完成后我在上线前做了一轮性能和数据层优化。很多人觉得全栈模板项目跑起来就行但真实流量进来后响应速度和数据库查询效率才是用户体验的分水岭。5.1 数据层优化Prisma 查询的 N1 问题和预加载t3code 的文章列表需要连同作者信息一起展示一开始我在后端的 router 里只查了 Post 列表然后在组件里逐条通过另一个 API 查作者列表一长请求数量成倍上涨这就是典型的 N1 问题。正确做法是在 Prisma 查询时用 include 或 select 一次性把关联数据带上list: publicProcedure .query(async ({ ctx }) { return ctx.db.post.findMany({ orderBy: { createdAt: desc }, include: { author: { select: { name: true, image: true }, }, }, }); })t3code 里这个改动让列表页的 API 耗时从接近 1 秒降到了 150 毫秒左右。另一个经验是不要用findMany无脑查全表业务上需要分页就分页t3code 后续计划里还有一个游标分页的功能要加面对数据量增长这是迟早的事。5.2 React Query 缓存策略调优默认情况下React Query 的缓存刷新策略偏向始终新鲜会导致每次进入页面都发请求。t3code 这类内部工具数据变化频率不高我调整了全局 QueryClient 配置const queryClient new QueryClient({ defaultOptions: { queries: { staleTime: 60_000, gcTime: 10 * 60 * 1000, refetchOnWindowFocus: false, }, }, });staleTime设置成 60 秒表示数据在 60 秒内不会被重新请求足够覆盖内部工具的日常使用refetchOnWindowFocus: false避免切窗口回来就触发一堆请求。这段配置看似简单实际对前端请求量影响巨大尤其是在多人同时在线的场景下。5.3 部署选型Vercel 加云数据库的组合t3code 最终部署在 Vercel 上原因是 Next.js 应用在 Vercel 上的适配近乎零成本构建、环境变量、日志都现成。数据库我在 Neon 和 Supabase 之间选了 Postgres连接串直接放进 Vercel 的环境变量里。这里要强调一个容易漏的步骤环境变量不要一股脑写进代码仓库更不能提交到前端包。CI 构建时我固定了一条流水线命令pnpm prisma generate pnpm buildprisma generate一定要在build之前执行否则生成的 Prisma Client 版本不对构建阶段就会报错。这个坑我在第一次配置 CI 时就踩过一次后来直接在 package.json 的 build script 里拼上了。5.4 实测数据优化前后的直观对比给一个 t3code 在测试环境里的大概数据方便你感受优化收益指标优化前优化后文章列表 API 耗时约 900ms约 150ms首屏请求数124页面 JS 体积约 320KB约 260KBJS 体积的下降主要来自剔除了几个不小心被打进客户端 bundle 的纯服务端依赖排查方法是用 Next 自带的构建分析工具看包体积报告。最后说一点我个人在 t3code 这个项目里的真实体会。T3 Stack 不是银弹它没法替你解决所有工程问题数据库设计、鉴权边界、缓存策略这些基本功一个都不能省。但它确实把类型安全从一个口号变成了日常开发中的肌肉记忆我改一个 Prisma 模型字段编译器的红色波浪线会精准告诉我每个受影响的地方这在以前的前后端分离开发里是无法想象的。如果你也受够了接口文档同步的苦或者想体验一把全套 TypeScript 协作的顺畅感拿 create-t3-app 起个内部小工具试试应该会让你对全栈开发有个全新的认识。