1. 项目概述t3code 到底是什么1.1 从代号到代码骨架t3code 是我给自己所有业余项目起的统一代号最开始是为了方便管理仓库个人博客、小工具、内部看板全部丢进一个以 t3code 为前缀的工程目录里。后来这个代号的意义慢慢变了它不再只是一个前缀而是一套被我固化的全栈 TypeScript 工程骨架。简单说t3code 代表以 T3 技术生态为核心的全栈开发方案我把 React、TypeScript、API 层、数据库访问、认证这些环节全部拉通形成一套开箱即用的起点工程。这套骨架解决的核心问题是前后端割裂。传统 React 项目通常拆成前端仓库和后端仓库前端用 fetch 或 axios 调接口后端写 REST 路由两边各自维护一套类型定义。结果就是接口文档、类型声明、实际返回值经常不一致改一个字段要同时改三处。t3code 的思路是把前端、API、数据库访问放在同一个 TypeScript 工程里让类型从数据库一路穿透到页面组件。我不用再定义两份 User 类型不用再手工同步接口字段改一个地方编译期就能发现所有受影响的位置。这个项目适合谁参考如果你正在做全栈 Side Project不想维护两套工程如果你受够了前后端联调时因为字段类型对不上而花半小时排查如果你想把登录、数据库、接口、页面样式这些基建问题一次性搞定那么 t3code 这套骨架的搭建过程值得完整看一遍。我写这篇文章的目的不是泛泛介绍 T3 技术栈而是把实际搭建过程中每个关键选择的理由、踩过的坑、改过的配置都记录下来让后面的人能少走弯路。1.2 T3 理念的核心类型安全不是口号T3 技术栈的核心理念用一句话概括就是能 TypeScript 的地方全部 TypeScript。这句话听起来像废话实际执行起来需要大量工具协同框架层用 TypeScript 强类型页面 Props接口层用 tRPC 推导前后端类型数据库层用 Prisma 生成类型模型输入校验用 Zod 保证运行时数据边界。每一层都在做同一件事缩小类型盲区。我见过不少项目号称全栈 TypeScript结果后端路由的参数是 any前端调接口的响应类型手写一份近似结构数据库查出来的数据还要在 service 层二次断言。这些写法在单个文件里都有充足理由但连在一起就是一个巨大的信任链漏洞。t3code 的做法是让工具链强制约束每层边界路由输入经过 Zod 校验后有明确类型Prisma 查询结果的类型由数据库 schema 生成tRPC 的 procedure 定义天然同时被服务端和客户端引用。类型不是人写的注释而是编译产物的一部分。这套理念落地之后最直观的感受是重构变得轻松了。我有一次把用户表的 nickname 字段改成 displayName只动了 Prisma schema 和两处代码引用剩下的所有报错全都由 TypeScript 编译器帮我标注出来前端组件、tRPC 路由、参数校验连带着全部检查完毕前后花了不到十分钟。放在以前手写类型同步的项目里这种重构至少要全局搜索加肉眼比对加接口联调一小时起步。1.3 这套代码骨架适合谁我梳理了一下t3code 这个骨架最适合三种人。第一种是独立开发者一个人要包揽前端、后端、数据库、部署如果能用一套 TypeScript 写完所有逻辑心智负担会大幅降低。第二种是小团队人数不多不想要微服务和复杂中间件一个 Next.js 应用同时承载页面和 API 层足够节省成本。第三种是想系统学习现代全栈开发的人T3 技术栈的每一环都是当前社区里热门度高且有代表性的方案组合在一起能学到完整的工程化思维。反过来如果你面临的是高并发场景、大量异构服务集成、团队里有人坚持用 Java 写网关那这套全栈 TypeScript 骨架未必合适。工具选型讲究匹配场景t3code 的优势是敏捷、类型安全、开发体验好它的边界也在这里。我的经验是先明确自己的项目规模再决定要不要采用这套路线别因为它是流行方案就盲目套用。2. 技术选型为什么是这套组合2.1 Next.js App Router全栈应用的舞台t3code 的应用层选择 Next.js而且是 App Router 模式。这个选择背后的逻辑不复杂我需要一个同时承担页面渲染和 API 接口的应用框架Next.js 的 Server Components 让我能在服务器端直接读取数据库、调用内部逻辑然后把结果以 React 组件树的形式渲染出来。相比传统的前后端分离架构省掉了一层网络请求页面响应时直接拿到完整 HTML。App Router 带来的另一个好处是文件即路由。我可以在 pages 目录旁边建立对应的 API handlers页面和接口放在同一个功能模块里相关代码的聚合度很高。比如一个用户详情模块page.tsx、header.tsx、route.ts 全都在同一个目录下维护时不需要跳来跳去。刚开始不习惯这种组织方式但用了一周之后就回不去了代码的局部性真的能降低认知负担。需要特别留意的是 Server Components 的边界。它只在服务器端运行里面不能直接使用浏览器 API也不能随意挂 useState。我一开始经常犯的错是在 Server Component 里想处理点击事件后来习惯了把交互下沉到 Client Component通过 Props 传数据这才理顺了架构。这个心智模型转变是所有转 App Router 的人都要跨过的坎。2.2 tRPC消除前后端的翻译层tRPC 是 t3code 中最具有魔术感的一环它让我在前端代码里直接调用服务器端函数并且类型自动完整传递。用过 gRPC 或者 JSON-RPC 的朋友会发现 tRPC 的思路并不奇特它把 API 从路由字符串 请求方法变成了函数调用客户端通过一个代理对象发起调用所有输入输出类型都可以被 TypeScript 编译器追踪。实际体验相当顺滑。我写一个获取用户列表的 procedure在服务端定义好输入参数类型和返回类型然后在客户端组件里 import 同一个 router调用 query 方法就能拿到带完整类型的响应。强类型带来了直接的开发提速IDE 自动补全能看到返回字段不再需要来回翻接口文档或者手动定义接口返回类型。tRPC 在构建上的要求比较高它依赖前后端共享 TypeScript 类型所以工程上要坚持用 monorepo 或者单仓库结构把 tRPC 路由定义放在一个独立模块里。t3code 采用的就是单仓库方案同一份类型定义既被服务端引用也被客户端引用。这个设计让幽灵类型彻底消失我之前常年维护两份接口定义改字段漏改的事件频发现在这类问题基本绝迹。2.3 Prisma Zod从数据库到表单的约束数据完整性方面t3code 同时用了 Prisma 和 Zod它们负责两个不同的阶段。Prisma 管数据库层的建模和访问它通过 schema.prisma 文件声明模型运行 prisma generate 后生成完整的 TypeScript 类型和查询客户端。Zod 管运行时输入校验管 HTTP 请求传进来的参数。它们形成了两道闸门进系统前先过 Zod存数据库前再经过 Prisma 客户端。我用一个具体场景来拆解。注册接口接收 username 和 email前端传入的数据可能是任意形状先用 Zod schema 校验长度、格式、必填项都在这层过滤。通过之后调 Prisma 的 create 写入数据库如果 email 违反唯一索引Prisma 会抛一个 P2002 错误。从原始输入到持久化数据每一个环节都有明确的安全边界。这种层层校验的设计感觉就像流水线装了两道质量检测仪瑕疵品根本走不到终点。Zod 还有一个实用特性从 schema 推导类型。我可以直接 type RegisterInput z.infer 这个类型同时被 tRPC 输入参数定义引用保证了校验规则和类型定义永远同步。不会出现校验通过了但类型对不上这种奇怪局面。2.4 Tailwind CSS样式不想多动脑子样式方案选 Tailwind CSS核心原因是我想减少样式文件的心智开销。传统的 CSS 方案需要给类起名字、维护样式表、确保选择器优先级不打架这些在快速迭代的业余项目里是纯浪费。Tailwind 的原子类直接在 JSX 里写响应式样式我不用在多个文件之间跳来跳去改文字颜色、间距、弹性布局都很顺手。有朋友质疑 Tailwind 的 HTML 会变得很脏类名一长串可读性差。实际用下来的感受是只要组件拆得足够细每个组件的 JSX 不会太长那一串类名其实相当于一份内联样式说明维护成本完全可以接受。再配合 tailwind-merge 和 clsx 处理条件类名基本不会出现类名冲突的问题。在 t3code 里我把样式方案限定在 Tailwind 里没有引入 CSS Modules 或者 CSS-in-JS目的很明确统一方案减少选择。团队成员接手项目时不需要讨论样式风格打开就能写写出来就能一致。对于小团队和个人项目来说这种不做选择题的设计省下的时间非常可观。3. 落地方案从 t3code init 到第一个完整功能3.1 初始化一切从脚手架开始t3code 的第一步是初始化项目。我不建议所有人从零手写配置那样要安装几十个依赖、手动组织 tsconfig、配置 ESLint 和 Prettier选 TypeScript 版本时还有一堆细节决策。我实际使用的是社区维护的脚手架命令它会交互式询问你要不要启用 tRPC、Prisma、NextAuth 等模块选定之后生成一份可运行的起点工程。npm create t3-applatest t3code生成之后的目录结构大致是这样t3code/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── app/ │ │ ├── api/ │ │ ├── layout.tsx │ │ └── page.tsx │ ├── server/ │ │ ├── api/ │ │ │ └── root.ts │ │ ├── db.ts │ │ └── auth.ts │ └── trpc/ │ ├── server.ts │ ├── client.ts │ └── react.tsx初次跑起来之后先别急着写业务代码我习惯做三件基础确认跑一次 lint、跑一次 build、跑一次 dev server。这三件事能把脚手架生成时的潜在问题尽早暴露出来尤其是本地 Node 版本和依赖版本的兼容问题。很多人在脚手架阶段跳过了这些检查等到开发到一半才发现 build 失败回头排查的成本就高了。3.2 建立 tRPC 路由先搭根再长叶子tRPC 路由的组织方式是 t3code 的核心骨架。根路由在src/server/api/root.ts中定义所有的子模块通过createTRPCRouter注册进去。我习惯把业务按领域拆成不同的 router比如 usersRouter、projectsRouter、settingsRouter然后在 root.ts 里聚合导出。// src/server/api/root.ts import { createTRPCRouter } from /trpc/server; import { usersRouter } from ./routers/users; import { projectsRouter } from ./routers/projects; export const appRouter createTRPCRouter({ users: usersRouter, projects: projectsRouter, });这样组织之后客户端调用路径就和路由树天然对应。trpc.users.getById.useQuery会映射到users.getById这个 procedure。每增加一个业务模块我只需要新建一个 router 文件、在 root.ts 里注册一行、再到客户端组件里调用整个过程没有任何重复的样板代码。一个值得注意的细节procedure 的输入参数尽量使用 Zod schema 做运行时校验。很多人一开始只写类型定义忽略校验导致接收到的数据可能是 undefined 或类型错位。实测定下来给每个接受输入的 procedure 配一个 schema能拦截掉一大部分脏数据问题。比如用户传了一个空字符串作为 IDZod 会在入口直接拒绝而不会让它走到数据库查询那一步再报错。3.3 数据模型与 Prisma 接入数据层是 t3code 里最接近传统后端开发的部分。我在 prisma/schema.prisma 中定义模型比如用户、项目、评论三张表然后运行prisma generate和prisma db push或者迁移命令把 schema 同步到数据库。// prisma/schema.prisma model User { id String id default(cuid()) email String unique name String? projects Project[] createdAt DateTime default(now()) } model Project { id String id default(cuid()) title String description String? authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) }这里有两个常见的坑。第一个是数据库连接串的正确配置本地开发用 SQLite 最省事但上线建议切到 PostgreSQL因为并发写入和连接管理能力完全不同。第二个是 Prisma Client 的单例模式在 Next.js 开发模式下热更新会导致反复创建新的 Prisma Client 实例最终打爆数据库连接。社区通行的做法是 globalThis 上创建全局单例。// src/server/db.ts 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 全栈项目里都会用到没有它开发时经常会在终端刷到Too many connections或者类似的提示。3.4 认证与会话守住数据的门认证模块我选用 NextAuth因为 T3 技术栈和它有成熟的集成方式。配置并不复杂核心是在src/server/auth.ts里声明 providers 和 session 回调然后在根路由里注册 protectedProcedure。// src/server/api/trpc.ts export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new Error(未登录); } return next(); });凡是需要登录权限的接口全部用 protectedProcedure 替代基础 procedure。这样保护逻辑集中在中间件层级业务代码里不用重复判断用户是否存在。每次打开 t3code 的 IDE看到那些分散的 if 判断逐渐减少我就知道中间件抽取得越到位代码越不容易漏掉权限校验。另一个要点是 session 的类型扩展。默认的 session.user 只有 id、name、email如果我需要往 session 里塞一个 role 字段必须在 NextAuth 的模块声明里扩展类型。这一步容易被忽略但缺了它你在组件里访问 session.user.role 时会直接类型报错。类型扩展本质是在告诉 TypeScript这个库给出的类型不够了我来补全它。3.5 构建部署的检查清单本地开发跑通后部署前我会跑一套固定检查。第一条是npm run build构建失败直接暴露类型错误、导入错误和打包问题。第二条是检查环境变量.env.example必须列出所有需要的变量免得部署时遗漏。第三条是检查 Prisma 客户端是否与迁移文件匹配跑prisma migrate deploy确保生产数据库结构是最新的。部署平台我用了 Vercel因为它和 Next.js 的集成最顺滑推代码到 Git 仓库后自动触发构建环境变量在控制台配置完毕即可。对于数据库我使用托管 PostgreSQL这样应用实例重启后数据不会丢。这套流程跑过几次之后变成了肌肉记忆新开一个 t3code 项目基本上十分钟内就能完成从空仓库到线上可访问的过程。4. 典型坑位与排查思路4.1 前后端类型失联的典型场景tPRC 虽然号称类型安全但实际使用中也会出现前后端类型对不上的怪象。我遇到的最典型场景是在服务端 procedure 返回值里加了一个新字段但客户端查询到的响应类型迟迟没有更新。排查之后发现是 tRPC 的类型推断依赖 TypeScript 的路径别名如果 tsconfig 里的 paths 配置不统一客户端 import 到的 router 类型可能是旧版本或者干脆解析到了一个重复定义的模块。解决方案非常直接保证全程使用/trpc/*这类统一的别名不要一部分文件用相对路径一部分用别名。如果你发现改了服务端代码后客户端类型没有同步提示先检查 tsconfig 的 paths 映射再用 IDE 的类型跳转功能确认客户端 import 的 appRouter 指向的是同一个文件。这个问题的本质是看似同一个类型实际是两个模块。还有一个冷门场景两个同名 router 文件分别放在不同目录导致根路由注册错了类型。这种错误编译期不一定报出来但查询结果和代码没关联。我后来养成了一个习惯根路由文件里明确导出 appRouter客户端只从固定路径 import不搞花活。4.2 Prisma 连接池与冷启动部署之后遇到的第一个性能坑是数据库连接数。PostgreSQL 默认最大连接数通常是一百左右而 Serverless 环境下每个实例都会创建自己的 Prisma Client 连接池。如果某段时间流量上来实例数增加连接数很快被打满数据库开始拒绝新连接整个应用表现为接口超时。我排查过一次很典型的故障白天某个页面持续请求数据库晚上复盘日志发现Connection pool timeout出现几十次。当时的解决方向不是调大数据库连接上限而是让 Prisma Client 在 Serverless 环境中复用连接同时在低峰期减少实例数量。这件事的经验是连接数的优化要从应用层和基础设施层两头下手不能只改一个方向。4.3 tRPC 查询的缓存与失效tRPC 的缓存机制对刚上手的人来说容易踩坑。它默认会把相同参数的查询结果缓存一段时间如果你的数据在别处被修改客户端看到的数据可能还是旧值。我在一个项目里遇到过这样的情况更新用户昵称成功后页面上立刻用 tRPC 的 useUtils 的 invalidate 方法重查数据但列表区域因为缓存 key 不匹配迟迟不刷新。排查后发现列表查询和单条详情查询虽然属于同一个 router但它们的 input 参数结构不同缓存 key 自然也不同。我误以为 invalidate 整个 router 就能刷新所有查询实际上需要在刷新时明确范围。后来我调整了失效策略不再全局 invalidate而是按具体的查询路径做点对点失效数据一致性立刻正常了。这个细节如果不在真机项目里踩一次光看文档很难意识到。4.4 构建期的环境变量问题最后说一个几乎每个人都会遇到的坑环境变量在构建期不生效。Next.js 默认在编译阶段会把 process.env 里的变量内联到客户端代码中如果没有正确读取环境变量页面会显示未初始化或者直接报错。再加上 tRPC 依赖浏览器端发起请求如果环境变量没注入到客户端整个查询链路可能断裂。我常用的排查手段是写一个/api/health接口返回当前环境里关键变量的存在状态然后在浏览器里看它是否正常。这个方法比翻构建日志更直观能快速定位问题出在服务器环境变量没配置还是构建时没正确读取。切记不要把密钥类变量传到客户端环境里敏感信息一律走服务端避免泄露。结尾给同样想用 t3code 做项目的你这套工程骨架我用了将近一年从最初搭脚手架到后来在多个实际项目里复用最大的体会是约束带来自由。一开始会把 TypeScript 全栈理念理解为限制觉得这种强类型流动束缚了发挥但用久了发现恰恰是这些约束让我在写业务代码时不用反复确认数据结构。我不会再为一个字段是 string 还是 string[] 来回翻接口文档因为类型系统已经替我记清楚了。最后分享一个我后来一直在用的小技巧每次新开 t3code 项目时先花十分钟把根路由、数据库模型、认证配置这些骨架代码全部跑通再开始写业务。这个前置投入看起来是浪费时间实际能省掉后面大量的排错成本。等你经历过数据表结构改三次、session 类型没有扩展、缓存失效没刷新的痛苦之后就会理解为什么值得在起点上多花精力。t3code 不是什么高深的技术发明它只是把一堆经得起验证的好工具按正确的姿势组装起来的一件事但把这件事做到位开发体验的改善是实打实的。