最近连续写了几个内部工具之后手头攒了不少关于全栈 TypeScript 项目的思考正好借着一个新项目的代号 t3code 把这些实践固化下来。所谓 t3code其实是我给自己一套基于 T3 生态搭建的代码模板起的名字核心就是 Next.js、TypeScript、tRPC、Prisma、Tailwind 这套组合顺带把认证、校验、部署这些绕不开的环节一并理清。这篇文章我想把它写成一份从初始化到跑通、再到踩坑复盘的完整记录适合两类人看一类是刚听说 T3 技术栈、想找个靠谱路径入门的全栈开发者另一类是已经用 Next.js 写过几个项目、但每次都被类型不安全和接口联调折腾得够呛的人。如果你只是想看现成结论那直接跳到最后几段如果你想弄明白每一步为什么这么走、坑是怎么出现的建议从头往后读。1. t3code的定位为什么把T3这套组合认真用起来1.1 从命名说起T3不是框架而是一组取舍T3 这个名字最早来自 create-t3-app它的核心不是某个新框架而是把几套已经很成熟的技术组合在一起通过约定统一起来。TypeScript 提供类型体系Next.js 负责应用框架和渲染策略tRPC 负责端到端的类型安全 API 调用Prisma 负责数据库访问层Tailwind 负责样式。你可以把 t3code 理解成这些技术的一个收敛实例。我见过不少团队一上来就上 monorepo、微前端、插件化架构结果项目还没跑起来就先被工程复杂度压垮。t3code 的思路恰恰相反它只解决一件事让前端、后端和数据库之间的数据流在类型层面闭环。这个少即是多的取舍在中小型项目中回报率极高尤其是三五个人的团队沟通成本每低一分迭代速度就快一分。1.2 适合 t3code 型项目的技术选型对照选型这事没有银弹关键是知道自己放弃了什么。我在做 t3code 之前做过一个简单的技术选型对照这里直接贴出来方便你对照自己的项目场景。需求维度t3code 的选择备选方案选择理由应用框架Next.js App RouterVite React Router、Remix需要 SSR/SSG 混合渲染且部署生态成熟类型安全 APItRPCREST OpenAPI、GraphQL前后端共享类型无需生成客户端代码数据层PrismaDrizzle、TypeORMSchema 直观迁移工具稳定社区资源多输入校验ZodYup、Valibot与 tRPC 集成最顺类型推断能力突出认证NextAuthClerk、自定义 JWT常规场景开箱即用OAuth 供应商覆盖广数据库SQLite开发/ PostgreSQL生产MySQL、MongoDB开发零配置生产环境语义强、生态好这个表不是标准答案但它能帮你快速建立坐标系。如果你知道自己要做的产品是重数据关系、强类型协作的中后台系统t3code 这套组合会非常顺手。如果项目偏重内容展示、没有太多用户交互逻辑那可能直接用 Next.js 静态生成就够了没必要上 tRPC。2. 初始化t3code脚手架背后的配置逻辑2.1 创建项目时真正需要按需勾选的内容我第一次搭建项目时习惯把 create-t3-app 的所有选项都勾上后来发现有些功能在当前阶段根本用不上反而增加了理解和维护成本。t3code 的初始化我建议按下面的原则取舍。首先包管理器这块我个人更倾向于 pnpm因为它的软链接机制在依赖多了之后优势非常明显。npm 和 yarn 也可以用但如果你有多个项目同时开发pnpm 能显著减少磁盘占用和安装时间。其次认证流程如果产品规划里有用户登录这个动作那 NextAuth 值得一开始就加进去省得后面迁移。Tailwind 我建议必选哪怕你打算用组件库Tailwind 在微调样式时依然很方便。2.2 生成后的目录结构到底该怎么理解初始化完成后src 目录下会有几个看起来名称近似的文件夹pages 或 app、server、trpc、styles。很多人第一次看到 src/server 和 src/trpc 会有疑惑——服务端代码和 tRPC 配置分开的意义是什么我的理解是src/server 放的是真正意义上的后端基础设施数据库连接、Prisma 实例、认证配置、第三方服务封装。src/trpc 放的是API 接口定义层router 的创建、中间件、受保护路由的封装。这样区分之后当你需要修改一个数据库查询逻辑时不需要在 API 路由文件里到处翻找当你需要调整权限校验时就去 src/trpc 里找中间件。分工清晰团队协作时不会互相踩到代码。3. 打通类型安全链路Prisma、tRPC和前端调用的一次完整对接3.1 数据模型先行定义一套贴近业务的Schema我对 t3code 里数据模型的建议是不要先在数据库管理工具里手动建表而是直接写 Prisma Schema然后通过 migrate 命令生成迁移。这样你能把数据模型留在版本控制里每个字段的变更记录都可以追溯。这里以一个小型项目任务管理功能为例核心表大概是这样model Project { id String id default(cuid()) name String ownerId String members User[] relation(ProjectMember) createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Task { id String id default(cuid()) title String status TaskStatus default(TODO) projectId String assigneeId String? dueDate DateTime? createdAt DateTime default(now()) } enum TaskStatus { TODO IN_PROGRESS DONE }多花一点时间设计字段类型尤其是 id 的生成方式、可选字段的标识、枚举值的定义后面会帮你省掉非常多联调时的类型报错。比如把 dueDate 设为可选前端拿到 null 和 undefined 时TypeScript 类型系统会强制你处理从而避免运行时出现Cannot read properties of null这类问题。3.2 用Zod统一输入校验别让信任扩散到边界tRPC 的一个常见用法是在 router 层直接写输入校验Zod 在这里的作用不是多一层安全这么简单它是类型系统的延伸。当你把一个 Zod Schema 传给 tRPC 的 input 方法时前端调用方也能自动推断出入参类型。比如这段代码import { z } from zod; import { router, publicProcedure } from ../trpc; const createTaskInput z.object({ title: z.string().min(1).max(100), projectId: z.string(), assigneeId: z.string().optional(), }); export const taskRouter router({ create: publicProcedure .input(createTaskInput) .mutation(async ({ ctx, input }) { return ctx.prisma.task.create({ data: { title: input.title, projectId: input.projectId, assigneeId: input.assigneeId, }, }); }), });写完之后前端调用 createTask 这个 mutation 时TypeScript 能自动提示 title 是 string、projectId 是 string、assigneeId 是 string 或 undefined。如果你在页面里传了一个 number 类型编译期就会报错而不是等到接口返回 400 才去排查。这个体验一旦用习惯你就很难回到纯 REST 的时代。3.3 从后端Router到前端useQuery的调用路径tRPC 的类型安全之所以能做到端到端是因为它把 router 的类型导出给前端使用。在 t3code 中通常会在 src/trpc 里导出一个类型 AppRouter然后在 React 侧的 tRPC Client 中引入这个类型。前端的调用方式非常接近 React Queryimport { api } from ~/utils/api; const { data, isLoading, refetch } api.task.getAllByProject.useQuery( { projectId: xxx }, { enabled: !!projectId } );你会发现不需要手动定义接口返回类型也不需要自己去维护 DTO数据传输对象后端返回什么前端就自动知道是什么。我觉得这是 t3code 目前最有价值的一点它让前后端之间的默契体现在代码里而不是靠文档和口头沟通。3.4 让Postgres和本地SQLite的差异提前暴露很多项目在本地开发时用 SQLite部署时切到 PostgreSQL这个策略本身没问题但有一个隐藏风险本地能跑通的功能不代表生产环境也跑得通。比如 Prisma 里如果用到了 PostgreSQL 特有的数组类型SQLite 根本不支持你在本地开发时完全无感知部署后才报错。我的建议是CI 流程里加一个基于 PostgreSQL 的集成测试至少保证核心链路的接口在接近生产的环境下跑一遍。如果团队规模小、暂时没有精力搭 CI那至少在生产环境部署后第一时间跑一遍核心业务冒烟用例。4. 开发中实际损耗时间的坑与排查过程4.1 第一个坑tRPC context里拿不到session这个坑我用一句话总结就是NextAuth 的 session 不是自动跑到 tRPC context 里的你得手动接。t3code 里默认的 context 写法是基于 getServerSession 的但如果调用的顺序不对或者服务端上下文里没有正确传递 session你在 protectedProcedure 里就收不到用户信息。当时我排查的过程是这样的先检查 NextAuth 配置本身登录是否成功session 是否写入 Cookie然后在 tRPC context 里加了一段调试日志打印 getServerSession 的返回结果发现 context 里拿到的是 null但页面组件里用 useSession 却正常最后确认是 createContext 里没有把 NextAuth 的配置项传进去导致服务端无法解析 Cookie。修复方式其实就一行把 authOptions 传到 getServerSession 的第二个参数里。但排查过程花了我好几个小时。这种经验写出来不值钱但卡住的时候真的会怀疑人生。4.2 第二个坑Prisma Client生成后不生效Prisma 在每次修改 schema 之后都需要重新生成 Client。我遇到的情况是改了 schema 并执行 migrate 之后前端的类型提示还是旧的 prisma 实例导致调用新增字段时 TypeScript 报错但报错的信息很抽象不是明说你缺少迁移而是说你访问的属性不存在。这个问题的本质是开发服务器的缓存没有正确刷新。解决方法其实很粗暴先跑一次 npx prisma generate然后重启 Next.js 开发服务器。如果环境变量发生了变化比如 DATABASE_URL 从本地切到了远程库那还需要重新执行 generate。这个过程不需要什么高深技巧但养成改 schema 后先 generate 再写代码的习惯能省掉大量莫名其妙的报错。4.3 第三个坑部署到Vercel时的环境变量和数据库连接本地开发时DATABASE_URL 指向 localhost 的 Postgres一切都正常。部署到 Vercel 之后问题集中在两块环境变量没配或者连接数超限。第一块的教训是Vercel 的 Preview 环境和 Production 环境要用不同的环境变量组而这两个环境是分开配的。你如果只在 Production 里配了 DATABASE_URL那么部署预览分支时服务端就会因为连不上数据库而白屏。第二块更隐蔽。免费版的 Vercel Serverless Functions 会为每个请求启动一个独立的执行环境如果每个函数都新建 Prisma 连接很容易把数据库连接池打满。解决方法是把 Prisma Client 实例全局缓存避免重复创建。const globalForPrisma global as unknown as { prisma: PrismaClient }; export const prisma globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) globalForPrisma.prisma prisma;这个写法在 Next.js 官方文档里也推荐过。我自己的体会是很多部署层面的问题不是因为代码写错而是因为执行环境变了而你还在用本地开发的思维去理解它。4.4 排查这类问题时的通用方法论踩坑多了之后我整理出一套排查固定流程先看环境变量再看执行环境最后才怀疑代码逻辑。这三个维度的命中率极高。环境变量检查 DATABASE_URL、NEXTAUTH_SECRET、API Key 等是否存在、对齐执行环境确认自己是在 Serverless 环境还是长驻进程环境两者的连接管理方式不同代码逻辑重新梳理数据流看 session、prisma 到底有没有按预期注入。这套流程说起来很普通但它确实帮我解决过 90% 以上的疑难杂症。很多人在群里发了一堆代码片段求助最后发现只是环境变量少配了一个。5. 把t3code往前推一步性能、监控与团队协作5.1 响应体积与RSC边界Next.js App Router 支持 React Server Components 之后很多人容易走向另一个极端把所有逻辑都塞到服务端组件里。服务端组件确实能从网络上省掉很多 JavaScript但也有代价每次页面渲染都会执行服务端逻辑如果里面嵌套了耗时的数据库查询TTFB首字节时间会明显变差。t3code 里的 tRPC 通常跑在客户端组件里这就形成一个分工能静态生成的内容尽量静态化需要动态数据的内容才通过 tRPC 在客户端获取。衡量这个边界的一个简单方法是打开浏览器的 Network 面板看首屏资源体积和接口响应耗时。如果首屏 HTML 已经很大但页面几乎没有动态数据说明你过度依赖服务端渲染如果首屏资源很小但接口转圈很久说明接口逻辑需要优化。5.2 日志和错误追踪的必要性中小型项目最容易忽视基础设施但日志和错误追踪恰恰是最不能省的一环。tRPC 的错误信息在开发环境很详细到了生产环境因为安全原因会被包装成通用的 Internal Server Error这时没有日志系统几乎等于瞎猜。我的建议是尽早接入 Sentry 或者类似的错误监控平台。Sentry 对 Next.js 的支持很成熟能捕捉服务端异常、客户端报错还能结合 release 信息定位到具体代码版本。接入成本不高两三个小时就能完成收益却很直接——再也不用等用户截图反馈才去查问题。5.3 小团队协作时的接口契约最后想说一个偏软性的问题接口契约。t3code 用类型系统把前后端绑定之后很多协作问题自然消失了但并没有完全消失。比如说后端调整了某个 mutation 的输入结构前端虽然会收到类型报错但如果前端只是在某个组件里调用了这个 mutation而那个组件已经被其他页面复用报错点可能和你实际改动的位置离得很远。这时团队内部还是需要就接口变更做一些沟通至少要在 PR 描述里写清楚改了哪个 API、调用方需要做什么调整。我个人的经验是类型安全把沟通成本降了一个量级但完全消失是不可能的。保持一个简单的接口变更记录文档比任何工具都靠谱。把 t3code 搭完并跑稳之后我最大的感受是技术栈的选择不需要追求新奇能稳定解决一类问题就够了。T3 这套组合最打动我的地方在于几乎所有环节都是顺着类型走的从数据库字段到 API 入参再到前端组件类型像一条线把它们串起来了。如果你也在给团队定技术规范不妨找一个内部小项目先试试这套组合跑通之后再决定要不要大规模推广。