t3code这个名字听起来像个随手的workspace目录但它是我认认真真规划了大半年、已经跑在生产环境里的全栈项目代号。T3在这里指的不是某个框架的第三个大版本而是T3 Stack这个组合——TypeScript、Tailwind CSS、tRPC外加跑在前台的Next.js。当初决定用它的时候身边不少同事觉得我是自找麻烦前后端都写细颗粒度类型还要让RPC层把类型从前端一路穿透到数据库开发初期的思维负担并不小。可项目真跑起来我才发现这套组合最值钱的地方不是我写代码多快而是重构时编译器替我把边界踩得干干净净。这篇东西不是官方文档也不打算做成教程就是把我从立项、初始化、业务模块落地、上线部署到维护半年里踩出来的坑和想明白的道理原原本本记下来。如果你正准备在中小型项目里尝试T3 Stack或者已经在用但总被tRPC的类型问题整得头疼这篇应该能给你省下不少时间。1. 让项目叫t3code是一次用类型换脑力的理性选择很多人听到T3 Stack的第一反应是又是新玩具但真正驱动我做这个选择的不是追新而是一个具体得不能再具体的痛点上下文断裂。传统的前后端分离项目里前端同事写页面时不知道后端接口到底返回什么后端同事改完模型也不确定前端哪里会炸。每个项目都靠Postman截图、接口文档、甚至口头沟通来维系默契这种默契在项目变大之后一定会漏。1.1 T3 Stack到底给了我什么T3 Stack的核心不是把几个库拼在一起而是把类型系统贯穿整条链路。TypeScript是基础语言tRPC负责前后端调用协议Prisma负责数据库模型三者共享同一个类型来源。你可以把tRPC想象成一张带类型标注的菜单后端定义了这道菜长什么样前端点单的时候编译器直接告诉你这道菜能不能加辣、会不会超时、返回的是不是你要的口味而不是等菜端上来才发现上错了。我自己做过一个比喻传统REST API像是打电话给餐馆问今天有什么菜对方口头报一遍你记在本子上回头厨房换了菜单你还不知道。tRPC是把菜单直接电子化推到你手里厨房改菜你手里的菜单同步变。这个同步不是运行时发生的是编译时发生的。1.2 项目画像是这样定的t3code具体做什么立项时我写得很窄一个内部使用的任务管理系统用户不多几十人但表单密集、权限逻辑多、状态转换频繁。核心实体只有用户、项目、任务、标签、评论五张表业务迭代频率很高基本每周都有新的列表页和操作按钮。这类项目的特征决定了选型底线类型安全优先、不搞微服务、部署要简单到一个人能维护、前端交互要足够快。如果你也在评估自己的项目适不适合T3 Stack可以对照三个条件第一业务逻辑密集但并发量不大第二前端页面和后端接口高度耦合改一个字段就要同步改两端第三团队愿意为类型安全付出一点开发速度。满足这三点T3 Stack就是典型的好选择。反过来如果项目是纯展示型网站几乎没有业务逻辑那Next.js单独就够了不需要tRPC。1.3 为什么放弃了老牌架构我并不是没有考虑过成熟方案恰恰是因为用得太熟才想换。REST API加手写类型的模式最痛的是双份类型定义后端有dto.ts前端有apiTypes.ts两边各自维护一旦某个字段忘了同步编译期完全看不出来运行期才开始报错。GraphQL解决了类型问题但引入了查询语言和缓存体系的额外学习成本对一个内部系统来说有点杀鸡用牛刀。下面这张表是我立项时给自己做的判断依据现在回头看仍然成立方案类型从哪来学习成本缓存复杂度适合规模REST 手写类型手工维护两份低低但易失真小团队临时项目GraphQLSchema自动推导高高需要客户端缓存多端复杂查询tRPC后端定义直接穿透中低默认服务端查询中小型全栈项目所以t3code最终定了Next.js做壳、tRPC做骨、Prisma做筋、Tailwind做皮。这个组合不是最流行的但对我们这种项目形态它是最省心的。2. 把t3code从脚手架推上生产初始化与目录落位目录结构和脚手架听起来是新手话题但我在t3code上吃亏最多的恰恰是这些基础环节。脚手架的默认选项并不等于最优配置每一步都要想清楚它会怎么影响后续的开发和部署。2.1 脚手架不是下一步而是第一步我用的是create-t3-app的交互式脚手架生成命令很简单pnpm create t3-applatest t3code接下来会有几个询问选项我勾选了Next.js、tRPC、Prisma、Tailwind CSS和NextAuth.js。这里有个值得注意的地方脚手架给的版本号会随社区更新而变化我的项目当时落在Next.js 14的App Router模式、React 18、TypeScript 5、Tailwind 3.4。如果你现在开新项目版本号大概率已经前进了一两个大版本但核心设计思路不变。有一个选项我建议仔细斟酌就是NextAuth.js。当时我很果断地勾了实际用下来发现在内部系统里我们更希望用企业微信扫码登录NextAuth的适配成本远高于自己写一个session回调。事后我其实把NextAuth换成了自研的登录中间件这算是在选型上多走的一步。所以我的建议是如果项目的认证方式很标准邮箱密码、GitHub登录用NextAuth没问题如果有特殊的第三方登录需求先花半天调研适配方案再决定。2.2 这棵目录树每一层在兜什么底t3code的目录结构不是随便生成的它把服务端代码和客户端代码物理隔离了。核心结构是这样src/ app/ # Next.js页面路由客户端组件和服务端组件都在这里 page.tsx layout.tsx api/ trpc/ [trpc]/route.ts # tRPC的HTTP入口 server/ api/ root.ts # 所有router的聚合出口 routers/ task.ts # 具体业务模块 tag.ts db.ts # Prisma client单例 auth.ts # 认证与session上下文 trpc/ server.ts # 服务端tRPC初始化 client.ts # 客户端tRPC初始化 prisma/ schema.prisma这个布局解决了一个关键问题src/server下的代码只会在服务端运行永远不进入客户端bundle。这意味着tRPC路由里可以直接操作数据库不必担心密钥和查询逻辑被暴露到浏览器。Next.js的App Router让这个边界变得更清晰服务端组件里可以直接调用tRPC router客户端组件则通过tRPC客户端调用两套方式各司其职。2.3 落地第一个业务模块任务看板纸上谈兵没意思我把t3code里的第一个完整模块——任务看板——从零走一遍。需求很简单用户能创建任务给任务打标签查看任务列表。先在Prisma里定好数据模型model User { id String id default(cuid()) name String tasks Task[] } model Task { id String id default(cuid()) title String status String default(todo) // todo | doing | done tags Tag[] author User relation(fields: [authorId], references: [id]) authorId String createdAt DateTime default(now()) } model Tag { id String id default(cuid()) name String unique tasks Task[] }这里有个经验任务状态字段我没有用枚举而是用字符串。好处是以后加状态不用跑迁移坏处是校验需要额外把关。对于迭代速度快的内部系统字符串加zod校验比Prisma枚举更灵活。接着定义tRPC router。Task的router写在server/api/routers/task.tsimport { z } from zod; import { createTRPCRouter, publicProcedure, protectedProcedure } from /server/api/trpc; import { db } from /server/db; export const taskRouter createTRPCRouter({ list: protectedProcedure.query(async ({ ctx }) { return ctx.db.task.findMany({ include: { tags: true }, orderBy: { createdAt: desc }, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1, 标题不能为空), tagIds: z.array(z.string()).optional(), }) ) .mutation(async ({ ctx, input }) { return ctx.db.task.create({ data: { title: input.title, authorId: ctx.session.user.id, tags: input.tagIds?.map((id) ({ id })) ?? [], }, }); }), });然后在root.ts里合并import { createTRPCRouter } from /server/api/trpc; import { taskRouter } from ./task; import { tagRouter } from ./tag; export const appRouter createTRPCRouter({ task: taskRouter, tag: tagRouter, }); export type AppRouter typeof appRouter;前端页面调用就非常直接const { data: tasks, refetch } api.task.list.useQuery(); const createTask api.task.create.useMutation({ onSuccess: () refetch(), });这段流程看起来平平无奇但注意一个细节整个过程中我没有写过一个接口地址没有定义过一个前端类型没有处理过HTTP状态码。所有可能出错的地方编译器在开发期就替我拦截了。这就是t3code选择这条路线的根本原因。3. tRPC是t3code的主心骨类型安全API的实战拆解如果你第一次接触tRPC可能觉得它不过是把函数调用包装成HTTP请求。但从使用者的视角它改变了写代码的方式你不再调用接口而是在调用函数。这个心智模型的转换直接影响项目里代码的组织方式。3.1 从HTTP协议到RPC调用tRPC的模式革命传统API开发里前端写fetch(/api/task/create, { method: POST, body: JSON.stringify(...) })后端写POST /api/task/create的handler两边的输入输出全靠约定。tRPC把这一层彻底抹平了前端导入的是api.task.create这个函数它自带参数类型和返回类型调用时的参数校验、错误处理、loading状态都被框架接管。为什么说这是模式革命因为tRPC不需要OpenAPI、不需要GraphQL schema、不需要生成器。类型就是协议本身。后端改了procedure的输入结构前端编译立刻报错这种即时反馈在大型重构时简直是保命符。我在t3code里做过一次任务表的字段重命名改了Prisma模型、改了几处router前端所有用到旧字段的地方瞬间标红半小时全改完上线零故障这在以前REST时代是不可想象的。3.2 一个router从定义到调用的完整链路为了让没接触过tRPC的读者也能看明白我把一次完整调用的链路拆开讲。服务端初始化时initTRPC.context()定义了Context类型context是每个请求都会被注入的数据类似中间件产出。t3code里我做了session注入import { initTRPC, TRPCError } from trpc/server; import { type CreateNextContextOptions } from trpc/server/adapters/next; import { getServerAuthSession } from /server/auth; import { db } from /server/db; export const createTRPCContext async (opts: CreateNextContextOptions) { const session await getServerAuthSession(); return { db, session, }; }; const t initTRPC.contexttypeof createTRPCContext().create(); export const publicProcedure t.procedure; export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { ...ctx, session: ctx.session } }); });这里protectedProcedure的作用是在进入具体业务逻辑之前强制校验身份。做过后端的人都知道每个接口里复制粘贴用户身份校验代码是灾难开端。有了中间件机制权限控制收敛到一处新加router时只要选择用哪个procedure就决定了这个端点要不要登录才能访问。前端调用方需要一次初始化import { createTRPCReact } from trpc/react-query; import type { AppRouter } from /server/api/root; export const api createTRPCReactAppRouter();注意这里传入的是typeof appRouter类型不是运行时导入。前端通过类型引用知道了后端所有procedure的形状这就是tRPC的全部秘密没有网络层面的魔法只有类型推导的奇迹。createTRPCReact生成的函数带上.useQuery()、.useMutation()内部自动接入React Query的缓存和状态管理。3.3 我反复踩的三类类型陷阱类型安全不是免费午餐实际使用中我踩过不少坑列出来给大家避雷。第一个坑是procedure的input类型变成never。症状是前端调用createTask.useMutation()时variables参数没有任何属性提示。原因通常是忘了给procedure加.input()或者.input()传了一个没有用zod定义的对象。tRPC的推导机制完全依赖zod schema只要null或undefined混进去类型就废掉。解决方案是每个有入参的procedure必须显式声明zod对象这是纪律问题不是技术问题。第二个坑是router合并时的命名冲突。t3code一度在root.ts里同时挂载了taskRouter和tagRouter而两个router内部都有名为list的procedure使用上没问题因为命名空间是api.task.list和api.tag.list。真正的问题是合并顺序影响类型提示速度router数量上百后VSCode的自动补全会明显变慢。我的解法是把大router按领域拆分后再合并尽量避免一个root文件里塞几百个procedure。第三个坑是服务端组件直调tRPC时的缓存行为。Next.js App Router的Server Component里可以直接调用api.task.list.query()但它不会走React Query的缓存每次渲染都会打一次数据库。t3code早期我这个用法导致页面每次刷新都有大量重复查询后来我干脆规定凡是需要缓存和实时状态更新的地方一律用客户端组件加useQuery()服务端直调只在完全静态的初始化场景使用。4. Tailwind在t3code里的组件化实践效率与设计系统性如果说tRPC解决了数据层的类型问题Tailwind解决的是样式层的效率问题。但效率这东西是双刃剑用得好了开发飞快用得失控就是一场样式灾难。4.1 原子化CSS如何从快速见效滑向混乱失控Tailwind的魅力在于你在HTML里直接堆class就能出效果几小时就能把一个不起眼的页面调出设计感。但项目三个月后你打开组件文件看到的是几十个class挤在一起改一个间距要在五个地方同时动手。t3code早期就经历过这个阶段最夸张的是一个按钮的class串长达十来个token换主题时我差点原地辞职。原子化失控的症状很明显同样的flex items-center justify-between在十几个文件里复制粘贴颜色、字号、圆角完全没有统一规则改一次视觉风格要全局搜替换。出现这些信号说明你需要组件化和设计约束了。4.2 className合并工厂与语义化封装我的解法是引入clsx加tailwind-merge的组合做一个统一的cn函数然后用它封装基础组件。先看这个工具函数import { clsx, type ClassValue } from clsx; import { twMerge } from tailwind-merge; export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }clsx负责过滤falsy值和合并对象tailwind-merge负责解决两个class冲突时后者覆盖前者的逻辑。比如调用方传了bg-red-500而组件默认是bg-blue-500twMerge能识别这是同一个CSS属性并让传入值生效。没有这层处理Tailwind的类名冲突会让人非常痛苦。以Button为例我用class-variance-authority来做变体管理import * as React from react; import { cva, type VariantProps } from class-variance-authority; import { cn } from /lib/utils; const buttonVariants cva( inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50, { variants: { variant: { default: bg-zinc-900 text-white hover:bg-zinc-800, outline: border border-input bg-background hover:bg-accent, ghost: hover:bg-accent hover:text-accent-foreground, }, size: { default: h-10 px-4 py-2, sm: h-9 rounded-md px-3, lg: h-11 rounded-md px-8, }, }, defaultVariants: { variant: default, size: default, }, } ); export interface ButtonProps extends React.ButtonHTMLAttributesHTMLButtonElement, VariantPropstypeof buttonVariants {} export function Button({ className, variant, size, ...props }: ButtonProps) { return ( button className{cn(buttonVariants({ variant, size }), className)} {...props} / ); }这里的关键是把样式变化抽象成variant和size两个维度而不是让使用方自己拼类。以后设计系统要改主题只动buttonVariants这一个文件全站按钮同步更新。4.3 暗色模式、响应式与RSC的默契配合t3code对暗色模式是硬需求所以我在Tailwind配置里开启了darkMode: class用next-themes包管理主题切换。坑点在于服务端渲染的首次空白客户端还没完成主题读取时页面先以亮色渲染一帧再跳到暗色体验很差。解决方法是把主题初始化脚本放到head里同步执行并且在html标签上设置suppressHydrationWarning。响应式方面我的原则是移动优先先写基础样式再套sm:、md:、lg:。但Tailwind有一个潜在性能陷阱如果类名是动态拼接的比如bg-${color}-500PurgeCSS/JIT编译器无法扫描到完整类名样式构建后会缺失。t3code早期我在这上面栽过按钮颜色全丢后来全部改写为完整的bg-blue-500形式并放在组件内部可见的位置。还有一个App Router时代特有的小问题Server Component里不能直接用ThemeProvider这种依赖浏览器状态的客户端组件。我的做法是把它封装成一个独立的Client Component在layout.tsx里嵌套使用而不是把整个布局变成客户端组件。5. 上线不是终点t3code部署期间的连环坑代码写完了本地跑通了以为万事大吉我告诉你真正的坑都在部署和运维环节。t3code上线那周我几乎每天都想摔键盘下面这几件事是血泪经验。5.1 环境变量的滞后性坑了第一次发布第一次部署到云主机时构建直接失败。日志显示Prisma在读取DATABASE_URL时拿到空值。我检查了代码本地明明好好的为什么线上不行原因很简单prisma migrate deploy和next build这两个命令在执行时需要环境变量已经加载但我们的部署脚本是在SSH登录后的非交互shell里跑的.env文件根本没有被source。更隐蔽的是Next.js在构建时会内联部分环境变量到客户端代码如果你有NEXT_PUBLIC_*变量必须在构建前注入部署后再改不生效。我的解决方法是把所有环境变量集中放在部署平台的配置面板里不依赖仓库里的.env文件。同时在项目根目录维护一份.env.example每删除或新增一个变量就更新它作为配置变更的文档。另外加了一步强制校验部署脚本最前面跑一个env-check脚本缺失关键变量直接fail不给半成品上线机会。5.2 migrate而不是migrate dev生产库迁移纪律开发阶段我习惯用prisma migrate dev它会在改schema后自动同步数据库并生成迁移文件。但生产环境和开发环境完全是两回事我在测试环境执行prisma migrate dev跑了一次结果它试图重置数据库差点把一部分测试数据清空。教训是生产环境和预发环境必须用prisma migrate deploy这个命令只会执行尚未应用过的迁移文件不会重置任何数据。严谨的做法是发布流程里串行执行# 1. 先跑迁移确保schema最新 npx prisma migrate deploy # 2. 再构建这样Prisma client与数据库结构一致 npx next build # 3. 最后启动 node server.js顺序为什么不能乱如果先build再migrate构建生成的Prisma client可能对应旧的schema连接数据库时某些查询就会字段不匹配。构建和迁移的顺序是我在线上栽过一次才学乖的。5.3 构建资源、日志与监控的三件套t3code最早用默认的Next.js构建产物镜像里带了几百MB的无用依赖。后来我在next.config.js里开启output: standalone体积从700MB降到180MB启动速度也有肉眼可见的提升。这个选项会把服务端需要的文件打包成一个独立目录部署时只需要复制.next/standalone和服务端需要的静态资源即可。日志方面默认console输出在容器里难以检索。我换成了pino输出JSON结构化日志每条日志带requestId和sessionId排查问题时用grep一条命令就能串起整个请求链路。错误监控接入了SentrytRPC的error handler里主动上报前端React的错误边界也统一收集。数据库连接数也是一个隐蔽的坑。t3code的Next.js服务在serverless平台上会被拆成多个实例每个实例都创建一个PrismaClient连接数很容易撑爆PostgreSQL。我的处理方式是全局单例在server/db.ts里用globalThis缓存PrismaClient确保整个进程只初始化一次。import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma?: PrismaClient }; export const db globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) { globalForPrisma.prisma db; }这个模式在Next.js热更新时还能避免开发环境的连接泄漏属于每个Next.jsPrisma项目都该抄走的代码。6. 维护t3code半年后的经验切片存档项目跑了大半年迭代了几十轮有些经验已经沉淀成团队的代码习惯。这章没有完整的故事线是我从日常维护中截取的经验切片每一条都是被真实情况逼出来的。6.1 命名与目录约定让类型右侧长满业务tRPC的类型穿透能力很强但这不代表你可以随便命名。procedure是前后端共同的语言命名混乱会让类型提示变成噪音。我的约定是查询类procedure一律用getX或listX开头变更类用createX、updateX、deleteX返回类型尽量扁平化不要嵌套超过两层否则前端取数据的代码会非常啰嗦。router文件按业务域划分一个域一个文件。t3code现在的结构是task.ts、tag.ts、project.ts、comment.ts、user.ts。每个文件内部先写查询再写变更和Prisma模型一一对应新同事接手时对着目录就能猜出八成接口。6.2 类型安全不是万能药边界在哪里我踩过的另一个认知陷阱是把tRPC当成所有通信的银弹。实际上它有明确的边界不适合传输二进制大文件比如上传图片和Excel导出不适合和第三方系统对接外部系统没有你的类型定义不适合需要独立超时控制的长任务。我的处理方式是给t3code加了一条不成文的规定文件上传走S3预签名URL异步任务用消息队列回调tRPC只负责业务数据和任务状态查询。第三方API对接时我单独建一个external/目录里面放专门的fetch封装和类型翻译层绝不让外部接口的返回类型直接渗透进业务代码。这个边界定清楚之后类型安全才有意义否则为了类型而类型反而会拖垮开发效率。6.3 健康检查脚本与发布前的自检清单半年里我做了很多次发布最值钱的产出是一份发布前自检清单和一个小脚本。脚本挂在scripts/health.sh作用很朴素检查应用进程是否活着、数据库能否连接、关键业务接口是否返回预期状态码。#!/usr/bin/env bash set -euo pipefail # 应用进程健康检查 curl -fsS http://localhost:3000/api/health || { echo app is down; exit 1; } # 数据库连接检查 node -e const { PrismaClient } require(prisma/client); const prisma new PrismaClient(); prisma.\$queryRaw\SELECT 1\ .then(() { console.log(db ok); process.exit(0); }) .catch(() { console.error(db error); process.exit(1); }); 发布前的自检清单我放在仓库的CONTRIBUTING.md里分为四步一跑一次完整的pnpm typecheck二确认环境变量齐全且值和目标环境一致三prisma migrate deploy后检查迁移状态四构建并启动后手动过一遍核心流程。这套流程跑下来大概二十分钟但我再没出现过上线即崩的惨剧。最后说一个小体会。t3code这个名字从立项到现在已经变成了团队内部的一个口头禅先看看t3code怎么写的。类型安全不是说代码永远不会出错而是把错误拦截在最容易修复的环节。维护这套系统半年我最深的感觉是它的每一行代码都在告诉你它想干什么而不是让你靠记忆和猜测去拼凑整个系统的模样。这种确定感是T3 Stack给我最大的回报。
t3code这个名字听起来像个随手的workspace目录但它是我认认真真规划了大半年、已经跑在生产环境里的全栈项目代号。T3在这里指的不是某个框架的第三个大版本而是T3 Stack这个组合——TypeScript、Tailwind CSS、tRPC外加跑在前台的Next.js。当初决定用它的时候身边不少同事觉得我是自找麻烦前后端都写细颗粒度类型还要让RPC层把类型从前端一路穿透到数据库开发初期的思维负担并不小。可项目真跑起来我才发现这套组合最值钱的地方不是我写代码多快而是重构时编译器替我把边界踩得干干净净。这篇东西不是官方文档也不打算做成教程就是把我从立项、初始化、业务模块落地、上线部署到维护半年里踩出来的坑和想明白的道理原原本本记下来。如果你正准备在中小型项目里尝试T3 Stack或者已经在用但总被tRPC的类型问题整得头疼这篇应该能给你省下不少时间。1. 让项目叫t3code是一次用类型换脑力的理性选择很多人听到T3 Stack的第一反应是又是新玩具但真正驱动我做这个选择的不是追新而是一个具体得不能再具体的痛点上下文断裂。传统的前后端分离项目里前端同事写页面时不知道后端接口到底返回什么后端同事改完模型也不确定前端哪里会炸。每个项目都靠Postman截图、接口文档、甚至口头沟通来维系默契这种默契在项目变大之后一定会漏。1.1 T3 Stack到底给了我什么T3 Stack的核心不是把几个库拼在一起而是把类型系统贯穿整条链路。TypeScript是基础语言tRPC负责前后端调用协议Prisma负责数据库模型三者共享同一个类型来源。你可以把tRPC想象成一张带类型标注的菜单后端定义了这道菜长什么样前端点单的时候编译器直接告诉你这道菜能不能加辣、会不会超时、返回的是不是你要的口味而不是等菜端上来才发现上错了。我自己做过一个比喻传统REST API像是打电话给餐馆问今天有什么菜对方口头报一遍你记在本子上回头厨房换了菜单你还不知道。tRPC是把菜单直接电子化推到你手里厨房改菜你手里的菜单同步变。这个同步不是运行时发生的是编译时发生的。1.2 项目画像是这样定的t3code具体做什么立项时我写得很窄一个内部使用的任务管理系统用户不多几十人但表单密集、权限逻辑多、状态转换频繁。核心实体只有用户、项目、任务、标签、评论五张表业务迭代频率很高基本每周都有新的列表页和操作按钮。这类项目的特征决定了选型底线类型安全优先、不搞微服务、部署要简单到一个人能维护、前端交互要足够快。如果你也在评估自己的项目适不适合T3 Stack可以对照三个条件第一业务逻辑密集但并发量不大第二前端页面和后端接口高度耦合改一个字段就要同步改两端第三团队愿意为类型安全付出一点开发速度。满足这三点T3 Stack就是典型的好选择。反过来如果项目是纯展示型网站几乎没有业务逻辑那Next.js单独就够了不需要tRPC。1.3 为什么放弃了老牌架构我并不是没有考虑过成熟方案恰恰是因为用得太熟才想换。REST API加手写类型的模式最痛的是双份类型定义后端有dto.ts前端有apiTypes.ts两边各自维护一旦某个字段忘了同步编译期完全看不出来运行期才开始报错。GraphQL解决了类型问题但引入了查询语言和缓存体系的额外学习成本对一个内部系统来说有点杀鸡用牛刀。下面这张表是我立项时给自己做的判断依据现在回头看仍然成立方案类型从哪来学习成本缓存复杂度适合规模REST 手写类型手工维护两份低低但易失真小团队临时项目GraphQLSchema自动推导高高需要客户端缓存多端复杂查询tRPC后端定义直接穿透中低默认服务端查询中小型全栈项目所以t3code最终定了Next.js做壳、tRPC做骨、Prisma做筋、Tailwind做皮。这个组合不是最流行的但对我们这种项目形态它是最省心的。2. 把t3code从脚手架推上生产初始化与目录落位目录结构和脚手架听起来是新手话题但我在t3code上吃亏最多的恰恰是这些基础环节。脚手架的默认选项并不等于最优配置每一步都要想清楚它会怎么影响后续的开发和部署。2.1 脚手架不是下一步而是第一步我用的是create-t3-app的交互式脚手架生成命令很简单pnpm create t3-applatest t3code接下来会有几个询问选项我勾选了Next.js、tRPC、Prisma、Tailwind CSS和NextAuth.js。这里有个值得注意的地方脚手架给的版本号会随社区更新而变化我的项目当时落在Next.js 14的App Router模式、React 18、TypeScript 5、Tailwind 3.4。如果你现在开新项目版本号大概率已经前进了一两个大版本但核心设计思路不变。有一个选项我建议仔细斟酌就是NextAuth.js。当时我很果断地勾了实际用下来发现在内部系统里我们更希望用企业微信扫码登录NextAuth的适配成本远高于自己写一个session回调。事后我其实把NextAuth换成了自研的登录中间件这算是在选型上多走的一步。所以我的建议是如果项目的认证方式很标准邮箱密码、GitHub登录用NextAuth没问题如果有特殊的第三方登录需求先花半天调研适配方案再决定。2.2 这棵目录树每一层在兜什么底t3code的目录结构不是随便生成的它把服务端代码和客户端代码物理隔离了。核心结构是这样src/ app/ # Next.js页面路由客户端组件和服务端组件都在这里 page.tsx layout.tsx api/ trpc/ [trpc]/route.ts # tRPC的HTTP入口 server/ api/ root.ts # 所有router的聚合出口 routers/ task.ts # 具体业务模块 tag.ts db.ts # Prisma client单例 auth.ts # 认证与session上下文 trpc/ server.ts # 服务端tRPC初始化 client.ts # 客户端tRPC初始化 prisma/ schema.prisma这个布局解决了一个关键问题src/server下的代码只会在服务端运行永远不进入客户端bundle。这意味着tRPC路由里可以直接操作数据库不必担心密钥和查询逻辑被暴露到浏览器。Next.js的App Router让这个边界变得更清晰服务端组件里可以直接调用tRPC router客户端组件则通过tRPC客户端调用两套方式各司其职。2.3 落地第一个业务模块任务看板纸上谈兵没意思我把t3code里的第一个完整模块——任务看板——从零走一遍。需求很简单用户能创建任务给任务打标签查看任务列表。先在Prisma里定好数据模型model User { id String id default(cuid()) name String tasks Task[] } model Task { id String id default(cuid()) title String status String default(todo) // todo | doing | done tags Tag[] author User relation(fields: [authorId], references: [id]) authorId String createdAt DateTime default(now()) } model Tag { id String id default(cuid()) name String unique tasks Task[] }这里有个经验任务状态字段我没有用枚举而是用字符串。好处是以后加状态不用跑迁移坏处是校验需要额外把关。对于迭代速度快的内部系统字符串加zod校验比Prisma枚举更灵活。接着定义tRPC router。Task的router写在server/api/routers/task.tsimport { z } from zod; import { createTRPCRouter, publicProcedure, protectedProcedure } from /server/api/trpc; import { db } from /server/db; export const taskRouter createTRPCRouter({ list: protectedProcedure.query(async ({ ctx }) { return ctx.db.task.findMany({ include: { tags: true }, orderBy: { createdAt: desc }, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1, 标题不能为空), tagIds: z.array(z.string()).optional(), }) ) .mutation(async ({ ctx, input }) { return ctx.db.task.create({ data: { title: input.title, authorId: ctx.session.user.id, tags: input.tagIds?.map((id) ({ id })) ?? [], }, }); }), });然后在root.ts里合并import { createTRPCRouter } from /server/api/trpc; import { taskRouter } from ./task; import { tagRouter } from ./tag; export const appRouter createTRPCRouter({ task: taskRouter, tag: tagRouter, }); export type AppRouter typeof appRouter;前端页面调用就非常直接const { data: tasks, refetch } api.task.list.useQuery(); const createTask api.task.create.useMutation({ onSuccess: () refetch(), });这段流程看起来平平无奇但注意一个细节整个过程中我没有写过一个接口地址没有定义过一个前端类型没有处理过HTTP状态码。所有可能出错的地方编译器在开发期就替我拦截了。这就是t3code选择这条路线的根本原因。3. tRPC是t3code的主心骨类型安全API的实战拆解如果你第一次接触tRPC可能觉得它不过是把函数调用包装成HTTP请求。但从使用者的视角它改变了写代码的方式你不再调用接口而是在调用函数。这个心智模型的转换直接影响项目里代码的组织方式。3.1 从HTTP协议到RPC调用tRPC的模式革命传统API开发里前端写fetch(/api/task/create, { method: POST, body: JSON.stringify(...) })后端写POST /api/task/create的handler两边的输入输出全靠约定。tRPC把这一层彻底抹平了前端导入的是api.task.create这个函数它自带参数类型和返回类型调用时的参数校验、错误处理、loading状态都被框架接管。为什么说这是模式革命因为tRPC不需要OpenAPI、不需要GraphQL schema、不需要生成器。类型就是协议本身。后端改了procedure的输入结构前端编译立刻报错这种即时反馈在大型重构时简直是保命符。我在t3code里做过一次任务表的字段重命名改了Prisma模型、改了几处router前端所有用到旧字段的地方瞬间标红半小时全改完上线零故障这在以前REST时代是不可想象的。3.2 一个router从定义到调用的完整链路为了让没接触过tRPC的读者也能看明白我把一次完整调用的链路拆开讲。服务端初始化时initTRPC.context()定义了Context类型context是每个请求都会被注入的数据类似中间件产出。t3code里我做了session注入import { initTRPC, TRPCError } from trpc/server; import { type CreateNextContextOptions } from trpc/server/adapters/next; import { getServerAuthSession } from /server/auth; import { db } from /server/db; export const createTRPCContext async (opts: CreateNextContextOptions) { const session await getServerAuthSession(); return { db, session, }; }; const t initTRPC.contexttypeof createTRPCContext().create(); export const publicProcedure t.procedure; export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { ...ctx, session: ctx.session } }); });这里protectedProcedure的作用是在进入具体业务逻辑之前强制校验身份。做过后端的人都知道每个接口里复制粘贴用户身份校验代码是灾难开端。有了中间件机制权限控制收敛到一处新加router时只要选择用哪个procedure就决定了这个端点要不要登录才能访问。前端调用方需要一次初始化import { createTRPCReact } from trpc/react-query; import type { AppRouter } from /server/api/root; export const api createTRPCReactAppRouter();注意这里传入的是typeof appRouter类型不是运行时导入。前端通过类型引用知道了后端所有procedure的形状这就是tRPC的全部秘密没有网络层面的魔法只有类型推导的奇迹。createTRPCReact生成的函数带上.useQuery()、.useMutation()内部自动接入React Query的缓存和状态管理。3.3 我反复踩的三类类型陷阱类型安全不是免费午餐实际使用中我踩过不少坑列出来给大家避雷。第一个坑是procedure的input类型变成never。症状是前端调用createTask.useMutation()时variables参数没有任何属性提示。原因通常是忘了给procedure加.input()或者.input()传了一个没有用zod定义的对象。tRPC的推导机制完全依赖zod schema只要null或undefined混进去类型就废掉。解决方案是每个有入参的procedure必须显式声明zod对象这是纪律问题不是技术问题。第二个坑是router合并时的命名冲突。t3code一度在root.ts里同时挂载了taskRouter和tagRouter而两个router内部都有名为list的procedure使用上没问题因为命名空间是api.task.list和api.tag.list。真正的问题是合并顺序影响类型提示速度router数量上百后VSCode的自动补全会明显变慢。我的解法是把大router按领域拆分后再合并尽量避免一个root文件里塞几百个procedure。第三个坑是服务端组件直调tRPC时的缓存行为。Next.js App Router的Server Component里可以直接调用api.task.list.query()但它不会走React Query的缓存每次渲染都会打一次数据库。t3code早期我这个用法导致页面每次刷新都有大量重复查询后来我干脆规定凡是需要缓存和实时状态更新的地方一律用客户端组件加useQuery()服务端直调只在完全静态的初始化场景使用。4. Tailwind在t3code里的组件化实践效率与设计系统性如果说tRPC解决了数据层的类型问题Tailwind解决的是样式层的效率问题。但效率这东西是双刃剑用得好了开发飞快用得失控就是一场样式灾难。4.1 原子化CSS如何从快速见效滑向混乱失控Tailwind的魅力在于你在HTML里直接堆class就能出效果几小时就能把一个不起眼的页面调出设计感。但项目三个月后你打开组件文件看到的是几十个class挤在一起改一个间距要在五个地方同时动手。t3code早期就经历过这个阶段最夸张的是一个按钮的class串长达十来个token换主题时我差点原地辞职。原子化失控的症状很明显同样的flex items-center justify-between在十几个文件里复制粘贴颜色、字号、圆角完全没有统一规则改一次视觉风格要全局搜替换。出现这些信号说明你需要组件化和设计约束了。4.2 className合并工厂与语义化封装我的解法是引入clsx加tailwind-merge的组合做一个统一的cn函数然后用它封装基础组件。先看这个工具函数import { clsx, type ClassValue } from clsx; import { twMerge } from tailwind-merge; export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }clsx负责过滤falsy值和合并对象tailwind-merge负责解决两个class冲突时后者覆盖前者的逻辑。比如调用方传了bg-red-500而组件默认是bg-blue-500twMerge能识别这是同一个CSS属性并让传入值生效。没有这层处理Tailwind的类名冲突会让人非常痛苦。以Button为例我用class-variance-authority来做变体管理import * as React from react; import { cva, type VariantProps } from class-variance-authority; import { cn } from /lib/utils; const buttonVariants cva( inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50, { variants: { variant: { default: bg-zinc-900 text-white hover:bg-zinc-800, outline: border border-input bg-background hover:bg-accent, ghost: hover:bg-accent hover:text-accent-foreground, }, size: { default: h-10 px-4 py-2, sm: h-9 rounded-md px-3, lg: h-11 rounded-md px-8, }, }, defaultVariants: { variant: default, size: default, }, } ); export interface ButtonProps extends React.ButtonHTMLAttributesHTMLButtonElement, VariantPropstypeof buttonVariants {} export function Button({ className, variant, size, ...props }: ButtonProps) { return ( button className{cn(buttonVariants({ variant, size }), className)} {...props} / ); }这里的关键是把样式变化抽象成variant和size两个维度而不是让使用方自己拼类。以后设计系统要改主题只动buttonVariants这一个文件全站按钮同步更新。4.3 暗色模式、响应式与RSC的默契配合t3code对暗色模式是硬需求所以我在Tailwind配置里开启了darkMode: class用next-themes包管理主题切换。坑点在于服务端渲染的首次空白客户端还没完成主题读取时页面先以亮色渲染一帧再跳到暗色体验很差。解决方法是把主题初始化脚本放到head里同步执行并且在html标签上设置suppressHydrationWarning。响应式方面我的原则是移动优先先写基础样式再套sm:、md:、lg:。但Tailwind有一个潜在性能陷阱如果类名是动态拼接的比如bg-${color}-500PurgeCSS/JIT编译器无法扫描到完整类名样式构建后会缺失。t3code早期我在这上面栽过按钮颜色全丢后来全部改写为完整的bg-blue-500形式并放在组件内部可见的位置。还有一个App Router时代特有的小问题Server Component里不能直接用ThemeProvider这种依赖浏览器状态的客户端组件。我的做法是把它封装成一个独立的Client Component在layout.tsx里嵌套使用而不是把整个布局变成客户端组件。5. 上线不是终点t3code部署期间的连环坑代码写完了本地跑通了以为万事大吉我告诉你真正的坑都在部署和运维环节。t3code上线那周我几乎每天都想摔键盘下面这几件事是血泪经验。5.1 环境变量的滞后性坑了第一次发布第一次部署到云主机时构建直接失败。日志显示Prisma在读取DATABASE_URL时拿到空值。我检查了代码本地明明好好的为什么线上不行原因很简单prisma migrate deploy和next build这两个命令在执行时需要环境变量已经加载但我们的部署脚本是在SSH登录后的非交互shell里跑的.env文件根本没有被source。更隐蔽的是Next.js在构建时会内联部分环境变量到客户端代码如果你有NEXT_PUBLIC_*变量必须在构建前注入部署后再改不生效。我的解决方法是把所有环境变量集中放在部署平台的配置面板里不依赖仓库里的.env文件。同时在项目根目录维护一份.env.example每删除或新增一个变量就更新它作为配置变更的文档。另外加了一步强制校验部署脚本最前面跑一个env-check脚本缺失关键变量直接fail不给半成品上线机会。5.2 migrate而不是migrate dev生产库迁移纪律开发阶段我习惯用prisma migrate dev它会在改schema后自动同步数据库并生成迁移文件。但生产环境和开发环境完全是两回事我在测试环境执行prisma migrate dev跑了一次结果它试图重置数据库差点把一部分测试数据清空。教训是生产环境和预发环境必须用prisma migrate deploy这个命令只会执行尚未应用过的迁移文件不会重置任何数据。严谨的做法是发布流程里串行执行# 1. 先跑迁移确保schema最新 npx prisma migrate deploy # 2. 再构建这样Prisma client与数据库结构一致 npx next build # 3. 最后启动 node server.js顺序为什么不能乱如果先build再migrate构建生成的Prisma client可能对应旧的schema连接数据库时某些查询就会字段不匹配。构建和迁移的顺序是我在线上栽过一次才学乖的。5.3 构建资源、日志与监控的三件套t3code最早用默认的Next.js构建产物镜像里带了几百MB的无用依赖。后来我在next.config.js里开启output: standalone体积从700MB降到180MB启动速度也有肉眼可见的提升。这个选项会把服务端需要的文件打包成一个独立目录部署时只需要复制.next/standalone和服务端需要的静态资源即可。日志方面默认console输出在容器里难以检索。我换成了pino输出JSON结构化日志每条日志带requestId和sessionId排查问题时用grep一条命令就能串起整个请求链路。错误监控接入了SentrytRPC的error handler里主动上报前端React的错误边界也统一收集。数据库连接数也是一个隐蔽的坑。t3code的Next.js服务在serverless平台上会被拆成多个实例每个实例都创建一个PrismaClient连接数很容易撑爆PostgreSQL。我的处理方式是全局单例在server/db.ts里用globalThis缓存PrismaClient确保整个进程只初始化一次。import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma?: PrismaClient }; export const db globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) { globalForPrisma.prisma db; }这个模式在Next.js热更新时还能避免开发环境的连接泄漏属于每个Next.jsPrisma项目都该抄走的代码。6. 维护t3code半年后的经验切片存档项目跑了大半年迭代了几十轮有些经验已经沉淀成团队的代码习惯。这章没有完整的故事线是我从日常维护中截取的经验切片每一条都是被真实情况逼出来的。6.1 命名与目录约定让类型右侧长满业务tRPC的类型穿透能力很强但这不代表你可以随便命名。procedure是前后端共同的语言命名混乱会让类型提示变成噪音。我的约定是查询类procedure一律用getX或listX开头变更类用createX、updateX、deleteX返回类型尽量扁平化不要嵌套超过两层否则前端取数据的代码会非常啰嗦。router文件按业务域划分一个域一个文件。t3code现在的结构是task.ts、tag.ts、project.ts、comment.ts、user.ts。每个文件内部先写查询再写变更和Prisma模型一一对应新同事接手时对着目录就能猜出八成接口。6.2 类型安全不是万能药边界在哪里我踩过的另一个认知陷阱是把tRPC当成所有通信的银弹。实际上它有明确的边界不适合传输二进制大文件比如上传图片和Excel导出不适合和第三方系统对接外部系统没有你的类型定义不适合需要独立超时控制的长任务。我的处理方式是给t3code加了一条不成文的规定文件上传走S3预签名URL异步任务用消息队列回调tRPC只负责业务数据和任务状态查询。第三方API对接时我单独建一个external/目录里面放专门的fetch封装和类型翻译层绝不让外部接口的返回类型直接渗透进业务代码。这个边界定清楚之后类型安全才有意义否则为了类型而类型反而会拖垮开发效率。6.3 健康检查脚本与发布前的自检清单半年里我做了很多次发布最值钱的产出是一份发布前自检清单和一个小脚本。脚本挂在scripts/health.sh作用很朴素检查应用进程是否活着、数据库能否连接、关键业务接口是否返回预期状态码。#!/usr/bin/env bash set -euo pipefail # 应用进程健康检查 curl -fsS http://localhost:3000/api/health || { echo app is down; exit 1; } # 数据库连接检查 node -e const { PrismaClient } require(prisma/client); const prisma new PrismaClient(); prisma.\$queryRaw\SELECT 1\ .then(() { console.log(db ok); process.exit(0); }) .catch(() { console.error(db error); process.exit(1); }); 发布前的自检清单我放在仓库的CONTRIBUTING.md里分为四步一跑一次完整的pnpm typecheck二确认环境变量齐全且值和目标环境一致三prisma migrate deploy后检查迁移状态四构建并启动后手动过一遍核心流程。这套流程跑下来大概二十分钟但我再没出现过上线即崩的惨剧。最后说一个小体会。t3code这个名字从立项到现在已经变成了团队内部的一个口头禅先看看t3code怎么写的。类型安全不是说代码永远不会出错而是把错误拦截在最容易修复的环节。维护这套系统半年我最深的感觉是它的每一行代码都在告诉你它想干什么而不是让你靠记忆和猜测去拼凑整个系统的模样。这种确定感是T3 Stack给我最大的回报。
