最近一个多月我一直在折腾 t3code 这个全栈项目。很多人第一次看到这个名字以为是个新框架或者某个开源库的代号其实它是我基于 T3 Stack 技术栈思想也就是 TypeScript Next.js tRPC Tailwind CSS 这套组合搭建的一个完整编码实践项目。这个项目要解决的核心痛点是前后端类型割裂、接口文档维护成本高、样式方案各写各的。如果你正在做中小型 Web 应用或者想体验一把“全栈类型安全”到底能带来多少收益那这篇文章应该能给你一些参考。我最早接触 T3 Stack 是被它的理念吸引不搞花哨的微前端、不引入一大堆中间层框架而是用最少的技术把一条数据从数据库到页面全部串起来全程类型不丢失。t3code 这个名字是从 create-t3-app 创建出来的项目但我在基础上做了一些针对业务场景的定制加入了自己维护的规范目录结构、统一错误处理和数据校验逻辑。说白了它不是一个开箱即用的框架而是一套可以复制的工程实践。这篇文章我会从整体设计思路、核心细节、实际操作过程和踩坑实录四个方向展开尽量把我这个月遇到的关键问题都说清楚。不管你是刚听说 T3 Stack 的初学者还是已经在用 Next.js 做项目的老手都可以对照着看看有些内容可能正是你现在缺的那块拼图。1. 项目整体设计与思路拆解1.1 t3code 的核心设计理念T3 Stack 的全称差不多可以理解为“TypeScript 优先的全栈开发模板”而 t3code 在这个基础上更进一步把“类型安全”从代码层延伸到业务边界上。传统的前后端分离开发流程里后端定接口、前端联调中间总有一个对字段、看文档、调参数的环节。t3code 的做法是后端用 tRPC 暴露函数前端直接调用这些函数函数的入参和返回值类型都是 TypeScript 自动推断出来的接口文档几乎不需要手写。这种设计理念最大的好处是改动数据结构的时候编译期就能发现哪些调用的地方没跟上。我举个实际例子项目里有个用户状态字段原来叫status后来想改成state。在传统模式下我要先去后端接口文档里搜status再全局搜前端代码里的status然后逐个替换运气不好还会漏掉。在 t3code 里我只要改了数据库模型和 Zod 校验规则再跑一次tsc --noEmit所有需要修改的地方会精准地列出改完基本不会留坑。当然这套方案的局限我也得说清楚。tRPC 本质上更适合前后端代码存放在同一个仓库的项目如果你的团队是严格的前后端分离甚至后端用 Go、Java 写微服务那 t3code 这套实践就不太合适。它解决的问题域是中小型全栈项目、内部工具、独立开发者做产品这种场景。1.2 技术栈选型背后的取舍决定用 T3 Stack 之前我对比过几套方案。一套是 Next.js REST API React Query另一套是 Nuxt Nitro还有一套就是现在的 T3 组合。三套方案我都写过 demo最后选 T3 不是因为它最先进而是因为它最匹配我的项目特征。Next.js 负责页面渲染和路由App Router 的布局嵌套和 Server Component 让大多数页面不需要额外请求接口首屏性能自然好。tRPC 取代了传统的 REST API函数式调用风格贴近日常开发习惯不需要定义 URL 路由也不用维护 OpenAPI 规范。Tailwind CSS 负责样式我用它的 Utility First 方式写界面基本不写自定义 CSS 文件改样式时直接在 HTML 类名里调整效率高很多。Prisma 作为 ORM 层把数据库表映射成 TypeScript 类型配合迁移工具管理表结构变更。这套组合的代价是Next.js 和 tRPC 的版本升级比较频繁API 偶尔变动Tailwind 写复杂动效不如 CSS Modules 直观Prisma 在某些复杂查询上不如手写 SQL 灵活。但对我这个项目来说开发速度、类型安全、可维护性这三项收益远大于代价。1.3 项目目录结构与业务边界划分t3code 的目录结构我做了明确划分。src/server下放所有服务端逻辑包括数据库访问、业务校验、第三方接口调用src/trpc放 tRPC 路由器实例和上下文创建逻辑src/app放 Next.js 页面组件src/components放可复用的 UI 组件。一个最容易踩坑的点是不要把取数逻辑散落在组件里。我在项目初期犯过错误直接在ProductList /组件里调trpc.product.list.useQuery()结果页面变大后数据请求分散在各处很难追踪数据来源。重构后我让页面 Server Component 负责取数Client Component 只接收数据并渲染。如果某处确实需要在客户端动态取数就单独封装一个 Hook保持数据逻辑的可观测性。提示t3code 里我遵守一条硬规则——页面组件不做数据请求数据请求要么在 Server Component 里要么在自定义 Hook 里组件只负责接收 props。这条规则让整个项目的数据流非常清晰排查问题的时候省了很多时间。2. 核心细节解析与实操要点2.1 TypeScript 严格模式与类型收窄整个 t3code 项目跑在 TypeScript 严格模式之下strict: true是硬性要求。严格模式会强制你处理null和undefined一开始写起来确实有点烦但长期看是保护伞。比如从数据库查出一个用户时user可能是null严格模式会逼你写判断而不是直接user.name报运行时错误。我常用的技巧是使用zod来做运行时校验。tRPC 的输入校验默认支持 Zod在路由定义里给input设置一个 Schema前端传参不对会直接提示。这个做法替代了传统后端手动做参数校验的过程非常实用。下面这段代码是 t3code 里一个典型注册接口的输入校验import { z } from zod; import { createTRPCRouter, publicProcedure } from /trpc/trpc; const registerSchema z.object({ email: z.string().email(邮箱格式不正确), password: z.string().min(8, 密码至少8位), nickname: z.string().min(2, 昵称至少2个字符).max(20, 昵称不能超过20个字符), }); export const authRouter createTRPCRouter({ register: publicProcedure .input(registerSchema) .mutation(async ({ ctx, input }) { const existing await ctx.db.user.findUnique({ where: { email: input.email }, }); if (existing) { throw new TRPCError({ code: CONFLICT, message: 该邮箱已被注册, }); } // 创建用户逻辑 return ctx.db.user.create({ data: { email: input.email, passwordHash: await hashPassword(input.password), nickname: input.nickname, }, }); }), });这里的input字段自带类型前端调用时不用写任何类型标注就能拿到完整的推论类型。如果你发现编辑器里没有给出类型提示通常是因为tsconfig.json里没有开启strict或者 tRPC 的泛型推断链路断了。2.2 数据库模型设计与 Prisma 迁移策略t3code 的数据库模型用 Prisma Schema 定义。设计模型时我遵循几条原则尽量用语义化的字段名关联关系明确指定外键所有表都带上createdAt和updatedAt。Prisma 的迁移命令prisma migrate dev会在本地生成 SQL 迁移文件代码入库后团队其他成员用prisma migrate deploy同步。有一点我想提醒的是Prisma 的updatedAt字段只在 Prisma Client 的update操作里自动更新如果直接用原始 SQL 改数据库这个字段不会变。我在排查一个 bug 时就遇到过某条记录的updatedAt一直没更新原因是我写了一个原生查询。后来我尽量避免在应用代码里混用 Prisma Client 和原生 SQL特殊场景才单独写查询文件。模型设计示例model User { id String id default(cuid()) email String unique passwordHash String nickname String createdAt DateTime default(now()) updatedAt DateTime updatedAt posts Post[] projects Project[] } model Project { id String id default(cuid()) name String description String? authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt }注意authorId和author成对出现relation里要同时指定fields和references否则 Prisma 会报错。这个配置我一开始漏掉了references结果迁移一直失败花了不少时间才看明白报错信息。2.3 tRPC 路由组织与中间件机制t3code 的 tRPC 路由按业务模块拆分每个模块一个文件比如auth.ts、project.ts、post.ts。模块里包含若干 ProcedureProcedure 分为query查和mutation写。这种做法类似传统后端的 Controller但不用定义 URL也不用注册全局路由前缀。中间件是 tRPC 一个很容易被忽视但非常强大的能力。我写了一个protectedProcedure它会在执行正式逻辑前先验证用户登录状态。实现上我在创建 tRPC Context 时把当前会话用户塞进去然后在中间件里检查import { TRPCError, initTRPC } from trpc/server; import { type Context } from /trpc/context; const t initTRPC.contextContext().create(); const isAuthed t.middleware(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: ctx.session, user: ctx.session.user, }, }); }); export const protectedProcedure t.procedure.use(isAuthed);这里有个细节值得注意中间件里判断ctx.session?.user而不是直接用ctx.user因为有些页面是没有登录态的。所有需要登录才能操作的接口统一用protectedProcedure定义代码安全很多。中间件里可以继续往 context 塞数据后续 Procedure 的ctx就能拿到这些数据类型也会自动变化。2.4 认证与会话管理方案t3code 的认证我采用的方案是 NextAuth.js。NextAuth.js 和 Next.js 的 App Router 配合得还算顺畅但有几个地方需要特别注意。首先是 Session 的回传策略。NextAuth.js 提供了JWT和Database两种 Session 策略。内部工具类项目我推荐 JWT 策略因为它不占数据库存储而且天然适配 Serverless 环境。如果你的应用需要主动失效某个用户的会话那得用 Database 策略或者额外维护黑名单。其次是回调函数的类型问题。在[...nextauth].ts里写session回调时TypeScript 默认不会把自定义字段带进客户端需要手动声明模块类型declare module next-auth { interface Session { user: { id: string; nickname: string; }; } }这个声明文件我放在src/types/next-auth.d.ts不写的话前端访问session.user.id会直接报类型错误。2.5 全局错误处理与日志记录全栈项目最怕的错误是前端报错了但后端没有任何日志或者后端抛异常前端只看到“网络错误”四个字毫无排查线索。t3code 里我做了全局错误处理。tRPC 的错误会通过TRPCError传递到前端前端用react-query的error对象可以拿到具体信息。我封装了一个apiErrorHandler工具函数统一处理认证失败、参数错误、资源不存在的场景export function getApiErrorMessage(error: unknown): string { if (error instanceof TRPCClientError) { switch (error.data?.code) { case UNAUTHORIZED: return 请先登录; case NOT_FOUND: return 请求的资源不存在; case VALIDATION_ERROR: return 参数校验失败请检查输入; default: return error.message || 请求失败; } } return 网络异常请稍后重试; }服务端这边我在创建 tRPC Router 的时候挂了一个全局 errorFormatter把TRPCError之外的未知异常统一包装并输出详细的req.url和req.method日志。这样生产环境出现 500 时搜索引擎一下就能定位到是哪个接口和哪条路径出了问题。3. 实操过程与核心环节实现3.1 项目初始化与实际配置过程如果你要从零搭一个 t3code 类似的项目最省事的方式是用 create-t3-app 脚手架。我用的是 pnpm命令如下pnpm create t3-applatest my-app执行后交互式选择配置我建议选择 TypeScript、Next.js、Tailwind CSS、tRPC、Prisma、NextAuth.js。第一次使用的人可能会纠结要不要全选我的建议是初期全选因为后面都会用得上。如果不想要某个部分后面再移除也不难但刚开始少选了再添加就得手动改很多文件反而麻烦。我在初始化后做了一步额外配置调整tsconfig.json的路径别名。默认配置是指向项目根目录的src但 tRPC 文件和页面文件引用时容易产生循环依赖所以我拆成了/app、/components、/server三条别名路径。这个改动让引用关系一眼清晰。安装依赖后第一件事不是写代码而是跑一次prisma migrate dev。因为初始的 Prisma Schema 已经创建了一系列基础模型比如User、Account、Session这些是 NextAuth.js 需要的表。提前迁移好数据库后面开发才不会因为缺表而报错。3.2 定义第一个业务模型并迁移数据库在 t3code 里我第一个做的业务模型是Project用来管理项目列表。定义好 Schema 后执行迁移pnpm prisma migrate dev --name init-project这个命令会做三件事对比当前 Schema 和数据库差异、生成迁移 SQL、在node_modules/.prisma/client里重新生成客户端类型。有一点要注意如果你改了字段名而不是删除重建Prisma 会提示你在 SQL 文件里补充DROP或ALTER操作避免数据丢失。我实际遇到过字段改名后数据全丢的情况所以我在执行迁移前会先回车看生成的 SQL 内容确认没问题再执行。迁移后顺手把DATABASE_URL环境变量配好。本地开发我用的是 SQLite生产环境用的是 PostgreSQL。SQLite 和 PostgreSQL 在 Prisma 里的写法绝大多数一致但遇到Json字段、enum类型时会有差异。所以我的经验是尽量在 Schema 里避免使用特定数据库独有的类型保持可迁移性。3.3 实现完整业务链路数据库到页面的数据流这一节我拿 t3code 里“项目成员列表”功能来说明完整的数据流。第一步在 Route 里定义查询export const projectRouter createTRPCRouter({ members: protectedProcedure .input(z.object({ projectId: z.string() })) .query(async ({ ctx, input }) { const project await ctx.db.project.findUnique({ where: { id: input.projectId }, include: { members: { include: { user: true } } }, }); if (!project) { throw new TRPCError({ code: NOT_FOUND, message: 项目不存在 }); } return { projectName: project.name, members: project.members.map((m) ({ userId: m.user.id, nickname: m.user.nickname, email: m.user.email, role: m.role, })), }; }), });第二步在 Server Component 里调用。我这边用 Next.js App Router可以在页面根组件里直接调用import { api } from /trpc/server; export default async function ProjectPage({ params }: { params: { id: string } }) { const data await api.project.members({ projectId: params.id }); return ProjectMembers initialData{data} /; }第三步如果需要有交互操作比如增加成员就在 Client Component 里调用 mutationuse client; import { api } from /trpc/react; function AddMemberButton({ projectId }: { projectId: string }) { const utils api.useUtils(); const addMember api.project.addMember.useMutation({ onSuccess: () utils.project.members.invalidate(), }); return ( button onClick{() addMember.mutate({ projectId, email: newexample.com })} 添加成员 /button ); }这里的invalidate()非常关键。它告诉 react-query 把project.members的缓存标记为过期触发重新请求从而让界面自动更新。如果不调用新增成员后页面不会刷新需要手动刷新浏览器这就破坏了交互体验。3.4 前端页面与样式联调细节t3code 的页面 UI 全部用 Tailwind 来完成。Tailwind 4 默认使用 CSS-first 配置可以直接在 CSS 文件里写theme定义品牌颜色不用再维护一个tailwind.config.js。我在联调时遇到的问题主要是响应式布局。T3 Stack 默认生成的模板是桌面端优先但我项目主要面向移动端用户需要大量覆盖小屏样式。规则是先用sm:、md:、lg:前缀逐级覆盖复杂布局直接用flex、grid组合。如果你发现某个样式没有按预期生效优先检查类名顺序——Tailwind 没有“后面的类覆盖前面的类”这种自然优先级它是按生成的 CSS 顺序来的冲突时需要自己避免。字体这块Tailwind 默认字体栈在不同平台差异很大会导致页面效果不一致。我引入了next/font加载思源黑体并在顶层组件设置font-family保证 Windows、macOS 和 Linux 下字体表现一致。4. 常见问题与排查技巧实录4.1 tRPC 类型推断失败的常见原因t3code 项目跑了一段时间我遇到的类型推断失败基本都集中在 tRPC 的 Router 引用上。表现是前端调用api.someRouter.someQuery时没有类型提示或者直接报Property xxx does not exist。最常见的原因是 Router 没有正确合并。tRPC 的appRouter是由多个子 Router 合并而来如果你在appRouter里漏写了某个 Router前端自然找不到它。我的排查流程是先打开src/server/api/root.ts检查createTRPCRouter({ ... })里的合并列表再逐个检查子 Router 是否导出正确。另一个原因是客户端引用的类型不对。Next.js 项目有 Server 和 Client 两套 tRPC Client如果 Server 端用了createTRPCClient而 Client 端用了createTRPCReact两者类型结构不同就可能出现“明明 Router 里有的方法前端却看不到”的诡异现象。解决方案是统一从/trpc/react和/trpc/server两个入口导入对应实例不要混用。4.2 Prisma 查询性能与 N1 问题t3code 里列表页容易出现 N1 查询问题。比如查询项目列表后又循环每个项目去查作者信息数据库会执行 1N 条 SQL页面响应明显变慢。Prisma 提供了include和select两种预加载方式。我在项目列表页的查询里增加了include: { author: true }一条 SQL 就把关联数据查出来。遇到多级嵌套时include里可以继续嵌套include但要注意嵌套层级太深会导致查询结果集膨胀很多场景反而不如拆开查询更高效。我的建议是最多嵌套两层超过两层就考虑拆分。还有一个性能容易忽略的点Prisma 默认返回所有字段如果业务只需要id和name尽量用select明确字段减少数据传输量。这在 Serverless 环境尤其重要因为响应时间直接和数据库返回数据量挂钩。4.3 Server Component 与 Client Component 的边界问题Next.js App Router 下最容易踩的坑是在 Server Component 里用了useState、useEffect构建直接报错。Node.js 环境下Server Component 只在服务端运行不能在它里面写浏览器相关的代码。t3code 里我维护了一条组件划分原则需要交互、需要状态的组件一律加use client指令纯展示类组件尽量保持 Server Component。如果一个页面同时需要 Server 端取数刷新和客户端交互我就把页面拆成两层外层 Server 负责取数内层 Client 负责交互通过props传递初始数据。这样既保证了 SSR 性能又保留了前端交互能力。一开始我总是把“客户端”和“组件里用了事件”画等号后来才理解use client是模块边界不是组件边界。一个模块里的所有组件都会被当作客户端组件加载所以尽量把真正需要交互的最小模块标记为客户端减少不必要的 JavaScript 包体积。4.4 部署环境的典型配置问题t3code 生产部署时我遇到了一个比较典型的配置问题。Vercel 的 Serverless 环境下Prisma Client 需要生成兼容 Serverless 的二进制文件。如果你只执行了本地开发用的生成命令部署上去后数据库请求会报PrismaClientInitializationError。解决方式是在构建命令里加一条prisma generate另外Serverless 环境的连接数很宝贵如果数据库是 PostgreSQL建议给 Prisma 设置连接池参数。Prisma 在 Serverless 下会自动复用连接但你最好在schema.prisma里指定connection_limit避免每个请求都新建连接导致数据库连接数爆掉。NextAuth.js 在部署时也容易踩坑。它的默认 Session 是用 JWT 加密的生产环境必须配置NEXTAUTH_SECRET环境变量否则每次部署后 Session 都会失效。而且NEXTAUTH_URL在 Vercel 上会自动设置但在自有服务器上要手动配不然回调地址会指向错误的域名。4.5 五个常用排查技巧速查整理一下我这段时间排查问题时的检查清单遇到问题按顺序走一遍大部分问题都能迎刃而解问题类型第一步检查第二步检查第三步检查类型错误tsc --noEmit看报错位置检查 tRPC Router 合并检查导入路径别名数据查询报错检查DATABASE_URL检查 Prisma 迁移状态查看数据库连接数页面白屏浏览器 Console 看报错检查服务端日志检查部署环境变量认证失效检查NEXTAUTH_SECRET检查回调 URL检查 GitHub OAuth 设置样式不生效检查类名拼写检查 Tailwind 配置检查 CSS 加载顺序4.6 几个我反复踩的坑最后说几个我在 t3code 开发中反复踩到的坑都不难解决但遇到了会莫名浪费时间。一是useQuery的enabled选项。在等待某些条件满足后才触发查询时如果enabled传的是falsereact-query 会认为查询处于pending状态但你拿到的data是undefined拿error也是undefined很容易误判成“接口有问题”。正确的做法是拿isPending和isFetched组合判断或者给query设置initialData。二是 tRPC 的serverClient在 Server Component 里的调用时机。每次页面刷新Server Component 都会创建新的 tRPC Context如果你在这个 Context 里去读 Session一定要确保 Session 已经加载完成。我在一个页面上遇到过‘首次加载正常刷新后报未登录’的问题最后发现是 NextAuth 的 Session 读取时机和页面渲染顺序不一致造成的后来在父布局里统一加载 Session再通过 Context 传给子组件解决了问题。三是 Prisma 数据库迁移时机。团队协作时如果一个人改了 Schema 并提交了迁移文件另一个人拉完代码后直接启动应用会报“表不存在”。不要慌先跑一次prisma migrate deploy。记住migrate dev是开发阶段生成迁移用的migrate deploy才是把已有迁移同步到环境数据库用的。这两个命令的定位一定要分清楚。四是 Tailwind 的类名动态拼接问题。如果你用模板字符串动态拼类名比如bg-${color}-500Tailwind 的 JIT 编译器无法在构建时提取到完整的类名样式会丢失。解决办法是使用完整的类名映射对象或者把所有可能的类名写成完整字符串让编译器能够扫描到。5. 个人体会与扩展建议t3code 这套实践跑了一个多月最大的体会是类型安全不是银弹但它能帮你把大量低级错误挡在编译期。以前写接口联调最怕的就是字段名写错、类型不匹配、文档过期这些在 t3code 里基本不会出现。代价是学习曲线偏陡尤其是 tRPC 和 Next.js App Router 的配合刚开始总会遇到一些莫名的问题。但只要熬过第一周后面写业务逻辑的效率提升非常明显。如果你也想尝试这套技术栈我建议从一个小工具项目开始比如一个待办清单、一个内部博客后台。先把 T3 Stack 的核心链路打通再逐步增加认证、校验、多模块路由这些进阶能力。不要一上来就追求完整的企业级架构先跑通再优化这样更容易体会到每层抽象带来的价值。我还想补充的是T3 Stack 阵营现在也在持续进化。tRPC 出了 v11Next.js 的 Server Actions 也能实现类似全栈调用能力。说实话Server Actions 在某些简单场景下更轻量但 tRPC 的优势在于显式的 Router 边界、中间件机制和客户端类型缓存控制。如果你的项目交互复杂、权限分层多tRPC 依然是更稳的选择。后续如果有新的实践心得我再整理一篇细聊。