t3code 是我最近几个月一直在打磨的一个个人项目一句话概括一个坚持类型安全优先的全栈 TypeScript 应用脚手架。给不熟悉的朋友解释一下你可以把它理解成一套开了箱就能跑的前后端一体化开发模板核心组合是 Next.js tRPC Tailwind CSS Prisma也就是圈子里常说的 T3 技术栈t3code 则是我在这套组合之上沉淀出来的工程化迈克件。它解决的问题其实挺具体现在的全栈开发平均一个人要维护前端路由、后端接口、数据库表结构、鉴权逻辑四套东西任何一个环节类型对不上线上就等着亮红灯。t3code 的核心思路是让 TypeScript 类型从数据库一路贯穿到页面组件中间不需要手写任何 API 契约和类型定义改一处编辑器立刻提示你其他地方哪里要跟着改。这篇内容适合正在做全栈 TypeScript 项目、或者对类型安全有执念的开发者看也适合受够了一堆 boilerplate 代码、想直接用一套成熟方案快速起项目的人参考。我会把 t3code 的选型逻辑、核心实现、完整实操流程和我在真实项目里踩过的坑都拆开聊代码可以直接抄走改。1. 项目缘起与整体设计思路1.1 为什么会有 t3code 这个项目事情得从我带的一个中型项目说起。团队用的是传统的前后端分离架构前端 React后端 Node.js 写 REST API数据库由后端同学单独维护。表面上看没什么问题但真正跑起来之后痛点非常集中——前端和后端各维护一份类型定义接口文档稍有滞后前端拿到的最新字段后端还没更新一联调就是一下午。后来我尝试了 OpenAPI 自动生成类型确实能解决一部分问题但引入 swagger 注解、生成链路、提交钩子整个工程的复杂度反而上去了。t3code 的出发点就是把这些胶水层全部干掉。我在想一个问题既然前后端都用 TypeScript为什么不能让类型定义只有一个源头然后所有地方共享顺着这个思路找下去tRPC 几乎是标准答案。它允许你在服务端定义函数然后在客户端像调用本地函数一样调用这些远程函数类型通过 TypeScript 的推断机制自动传递不需要手写任何 API 层代码。结合 Prisma 直接操作数据库类型又从表结构一路推到了业务函数。整个链路的数据类型只有一个权威源头其余全部推导这就是 t3code 想给你的核心体验。1.2 技术选型为什么是这四个核心组件很多朋友问过我为啥不选别的组合比如 Next.js 配 GraphQL或者 NestJS 配 Swagger。我的回答是t3code 的目标不是功能最多而是心智负担最小。Next.js提供文件路由、服务端渲染、静态生成和 API 路由一套框架把页面和服务端函数放在同一个工程里部署天然简单。选它不选纯 Vite Express 的原因在于全栈应用里页面渲染、SEO、服务端逻辑往往耦合紧密拆成两个工程维护成本会翻倍。tRPC这是我的最爱。没有 schema 定义、没有 codegen、没有装饰器纯粹靠 TypeScript 的类型推断搞定端到端类型安全。调用远程函数就像调用本地异步函数IDE 自动补全和错误提示跟本地代码完全一致。Prisma数据库 ORM 里类型体验最好的一个。schema 文件即数据模型的权威定义迁移工具链成熟查询 API 完全类型化配合 tRPC 几乎没有认知断层。Tailwind CSS样式方案选择很多但 Tailwind 胜在约定大于配置工具类直接写在模板里不会出现这个组件的样式定义在哪个文件的搜索成本。这四个组件配合起来整套数据流是Prisma Schema → 数据库表 → tRPC 路由函数 → Next.js 页面组件全程一个类型系统没有多余的中间产物。1.3 t3code 的目录设计一个 T3 风格项目跑起来之后目录结构大致是下面这样的my-app/ ├── prisma/ │ └── schema.prisma # 数据模型唯一权威来源 ├── src/ │ ├── pages/ # Next.js 文件路由 │ │ ├── api/ # tRPC 入口挂载在这里 │ │ └── index.tsx │ ├── server/ │ │ ├── api/ # tRPC 路由定义 │ │ │ └── routers/ │ │ ├── db.ts # Prisma Client 实例 │ │ └── auth.ts # 鉴权配置可选 │ ├── styles/ │ │ └── globals.css # Tailwind 入口 │ └── utils/ │ └── api.ts # tRPC 客户端封装 ├── .env # 环境变量 └── package.json这个目录体现了一个非常重要的设计原则服务端代码集中放在 server 目录下页面只通过 tRPC 客户端访问能力不直接操作数据库。很多类型不安全的问题本质上都是因为服务端逻辑散落在页面里出了问题根本不知道数据从哪来。t3code 通过目录约定把这条边界焊死新增功能时团队自然遵循相同的路径几乎不需要解释。2. 核心实现类型安全如何贯穿全链路2.1 tRPC 路由层设计tRPC 的核心概念是 router 和 procedure。router 是路由集合procedure 是具体接口。以用户功能为例路由定义大概是// src/server/api/routers/user.ts import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const userRouter createTRPCRouter({ getById: publicProcedure .input(z.object({ id: z.string().uuid() })) .query(async ({ ctx, input }) { return ctx.db.user.findUnique({ where: { id: input.id }, select: { id: name: true, email: true }, }); }), updateProfile: protectedProcedure .input(z.object({ name: z.string().min(1).max(50) })) .mutation(async ({ ctx, input }) { return ctx.db.user.update({ where: { id: ctx.session.user.id }, data: { name: input.name }, }); }), });这里有人会问tRPC 不是号称不需要 schema 吗怎么又整出 zod 了其实 zod 不定义 API 契约它只负责两个事情一是在运行时校验输入数据的合法性z.string().uuid() 会拒绝非 UUID 格式二是通过 z.infer 把运行时校验器反推成 TypeScript 类型。tRPC 的输入类型不是手写的 interface而是从 zod schema 推断出来的所以唯一权威源依然只有一个。第二个关键点是 publicProcedure 和 protectedProcedure 的区分。protectedProcedure 是 tRPC 中间件机制的一个典型用法——它先检查 session 里是否有用户没有就直接抛错有才继续往下执行。这个中间件在 t3code 里是内置的新路由只要声明自己是 protected鉴权逻辑就会被强制检查不需要在每个接口里手动写 if (!user) throw。2.2 Prisma 数据模型与数据库迁移Prisma 的 schema 文件是数据层的心脏。以常见的博客系统为例// prisma/schema.prisma generator client { provider prisma-client-js } datasource db { provider postgresql url env(DATABASE_URL) } model User { id String id default(cuid()) name String? email String unique posts Post[] createdAt DateTime default(now()) } model Post { id String id default(cuid()) title String content String author User relation(fields: [authorId], references: [id]) authorId String published Boolean default(false) }这里有几个细节值得注意。主键我倾向用 cuid 而不是自增 int因为自增主键在分布式环境下容易暴露业务量而且多实例部署时可能出现冲突cuid 是字符串但有序生成作为 URL 参数也不会被穷举。email 加了 unique 约束数据库层面兜底了业务上的一个邮箱一个账号规则比只在应用层校验可靠得多。数据库迁移命令是npx prisma migrate dev --name init它会自动对比 schema 和目标数据库的差异生成迁移 SQL 并执行。需要强调的是迁移文件要提交到代码仓库因为在多环境开发、测试、生产部署时迁移顺序和记录是所有环境数据库结构保持一致的唯一线索丢了迁移历史几乎是灾难。2.3 Next.js 页面与 tRPC 的衔接页面组件这边t3code 使用 tanstack/react-query 作为 tRPC 的底层数据请求库。tRPC 本身只负责函数调用和类型传递实际的数据缓存、重试、并行请求都由 react-query 接管。一个典型页面的写法是// src/pages/index.tsx import { api } from ~/utils/api; export default function HomePage() { const { data, isLoading } api.user.getById.useQuery({ id: ... }); if (isLoading) return div加载中.../div; if (!data) return div用户不存在/div; return ( div p{data.name}/p p{data.email}/p /div ); }你可以仔细看这个流程api.user.getById.useQuery 这个函数useQuery 前面的对象路径是自动提示出来的根本没有字符串形式的 URL没有手动拼参数没有响应类型断言。如果服务端把 email 字段改名或删除前端页面编译时直接报错连跑起来都不用。这就是 t3code 最值钱的部分——把联调这个环节变成了编辑器的即时反馈。与此同时t3code 默认开启了 Next.js 的 React Server Components 能力对于无需交互的只读页面可以让请求在服务端完成浏览器拿到的就是完整 HTML对 SEO 和首屏渲染都很友好。写的时候只需要注意组件里凡是用了浏览器 APIlocalStorage、window 之类或者 useState/useEffect 的标注 use client 即可否则默认就在服务端跑。2.4 Tailwind 样式体系与主题定制Tailwind 在 t3code 里承担的是纯样式层的约定管理。很多团队觉得 Tailwind 的 class 容易把模板写乱我实际用下来的感受是复杂度不是 Tailwind 带来的而是组件拆分粒度不合适带来的。t3code 的模板里定义了一套组件类用 apply 把高频样式组合收敛成语义化类名比如/* src/styles/globals.css */ tailwind base; tailwind components; tailwind utilities; layer components { .btn-primary { apply inline-flex items-center justify-center rounded-md bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500; } .card { apply rounded-lg border border-gray-200 bg-white p-6 shadow-sm; } }这样页面里写的是classNamebtn-primary而不是一长串工具类既有 Tailwind 的原子化收益——样式的修改和删除不会污染全局又保持了代码可读性。主题定制方面可以在 tailwind.config.ts 里扩展 colors、spacing 等设计令牌让前端同学只认语义令牌primary、danger、surface而不是具体色号后续换肤或品牌调整成本会低很多。3. 完整实操从零初始化一个 t3code 项目3.1 初始化与依赖安装t3code 提供了基于 create-t3-app 的初始化脚本执行完下面这行一个完整项目就起来了npx create-t3-applatest my-app交互式命令行会让你勾选需要的模块我建议基础阶段全部选上后面用不上再删。初始化完成后进入项目安装依赖cd my-app npm install这里的依赖其实分三层运行时依赖next、react、trpc/server、trpc/client、prisma/client、zod 等、开发依赖typescript、tailwindcss、prisma、eslint、prettier 等以及 tRPC 相关的 react 适配层tanstack/react-query、trpc/react-query。安装完立刻跑一个npm run dev看到 Next.js 的欢迎页说明基础链路没问题。3.2 配置环境变量与数据库t3code 的风格是一切配置显式化。项目根目录有个 .env.example 文件复制成 .env 后填以下几个关键变量# .env DATABASE_URLpostgresql://user:passwordlocalhost:5432/my_app?schemapublic NEXTAUTH_SECRET你的随机密钥 NEXTAUTH_URLhttp://localhost:3000DATABASE_URL 指向 PostgreSQL 实例本地没有数据库的话可以起一个 Docker 容器一条命令搞定docker run --name t3code-db -e POSTGRES_PASSWORDpostgres -p 5432:5432 -d postgres:16验证数据库连接是否正常用npx prisma db push直接把 schema 推到开发库日常开发建议用 db push 快速迭代正式环境用 migrate deploy然后npx prisma studio打开图形化管理界面能看到刚才定义的 User、Post 表已经创建好。3.3 编写第一个业务功能假设需要做一个创建文章并展示列表的功能。第一步在 Prisma schema 里确认 Post 模型存在然后创建 tRPC 路由// src/server/api/routers/post.ts import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure.query(async ({ ctx }) { return ctx.db.post.findMany({ orderBy: { createdAt: desc }, take: 20, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1).max(100), content: z.string().min(1), }) ) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });然后把 postRouter 挂到根路由里// src/server/api/root.ts import { postRouter } from ./routers/post; import { userRouter } from ./routers/user; export const appRouter createTRPCRouter({ user: userRouter, post: postRouter, }); export type AppRouter typeof appRouter;前端页面调用时react-query 的 invalidate 机制让数据更新后自动刷新列表const utils api.useUtils(); const createPost api.post.create.useMutation({ onSuccess: async () { await utils.post.list.invalidate(); }, });这里 onSuccess 里调 invalidate意思是创建成功后让 post.list 这个查询重新拉取数据。整个链路里没有写一行 fetch、axios 或 URL这就是 t3code 的日常开发方式——你写的所有代码其实只分两类定义数据的能力服务端和使用数据的能力客户端。3.4 部署到生产环境的要点代码写完之后部署阶段有几个坑必须提前避掉。Prisma Client 需要在构建时生成Dockerfile 里必须加npx prisma generate这一步而且要在next build之前执行否则生产环境的 Prisma Client 是残缺的运行时直接报 P1001 这类连接错误。数据库迁移在部署流程里的顺序也很讲究容器启动时先去跑npx prisma migrate deploy成功后再启动 Next.js 服务避免新代码已经跑起来但表结构还没更新的情况。CDN 或反向代理层需要注意 Next.js 的文件路由和静态资源缓存策略一般把_next/static路径设置为强缓存页面 HTML 设置为 no-cache这样既能利用 CDN 缓存又不会让用户拿到过期页面。部署完成之后建议立刻看一眼服务端日志里有没有 tRPC 错误最常见的一类就是跨域配置不对导致浏览器请求被拦Next.js 和 tRPC 同源部署的话基本不会遇到但只要拆了子域就必须在服务端配置 CORS 白名单。4. 常见问题与排查技巧实录4.1 tRPC 类型不收敛怎么办症状是功能跑得通但编辑器里 TypeScript 一直报错或者改了服务端返回值前端不生效。先确认你是否重启了 dev server——tRPC 的类型推导是编译期行为如果类型文件变了但 dev server 没有重新编译编辑器是感知不到的。另一个常见原因是 router 没有挂到根路由。t3code 里存在孤立 router的情况你新建了一个 postRouter但忘了在 root.ts 里 add前端 api.post 的对象路径就永远不出现。排查方式很简单在 root.ts 里export type AppRouter typeof appRouter这行加一个类型查询编辑器 hover 就能看到当前 AppRouter 暴露了哪些路由。4.2 Prisma 迁移报错合集Prisma 的迁移错误有很强的规律性。最常遇到的是列已存在或表不存在——原因基本都是本地用 db push 改了 schema又用 migrate dev 生成迁移两者在本地产生了分歧。解决思路是日常开发只用一个命令要么 db push适合快速迭代不记录迁移要么 migrate dev适合正式记录每次变更别混着用。如果是生产环境迁移失败不要直接在数据库里手工改表结构。正确做法是重新生成一个干净的迁移文件把差异补上或者用npx prisma migrate resolve --applied标记已经手动执行的迁移。我吃过最大的亏就是线上报错了直接 psql 改表后来迁移历史完全对不上环境重建异常痛苦。4.3 Next.js 与服务端渲染的边界很多团队在 T3 项目里把 tRPC 请求全部放在 useEffect 里执行这会带来两个问题一是页面首屏出现空白或加载动画SEO 不友好二是所有数据请求都在浏览器发起没有利用服务端的网络带宽优势。t3code 推荐的做法是善用 Next.js 的 RSC 特性对于列表页、详情页这些以展示为主的内容可以在服务端直接调用 tRPC 查询把数据作为 props 传给客户端组件对于表单提交、交互操作才用客户端组件里的 useMutation。一个判断标准是这个页面是否需要登录用户的前端状态如果不需要优先服务端渲染。4.4 性能与体验优化心得tRPC 本身只是一个 RPC 层性能瓶颈往往在数据查询上。一次 list 接口返回 20 条文章每条都要计算作者信息和评论数如果没有用 Prisma 的 include 或嵌套 select会产生 N1 查询问题——也就是一次接口背后跑了 20 多次 SQL。用 Prisma 的 include 一次联表查出来再在页面里按需取用接口耗时能降一个数量级。另外 react-query 的缓存策略也值得配置。t3code 默认对查询请求做 5 分钟 staleTime意味着 5 分钟内同一个查询不会重复发请求这在列表页反复切换筛选条件时收益很明显。数据变化频繁的页面比如实时仪表盘可以把 staleTime 调小到 5 秒并开启 refetchOnWindowFocus让切回标签页时自动刷新。5. 扩展方向与个人心得5.1 插件化与模板市场t3code 后续最值得做的扩展方向是模板市场。目前脚手架只能生成一套标准结构但如果能像 create-next-app 那样支持 --template 参数比如博客模板电商模板管理后台模板每个模板预置好对应的 Prisma 模型和 tRPC 路由起新项目的速度会从中级提升到直接开工。我验证过这种做法的可行性核心脚手架逻辑不变模板层只是一个包含 pages、routers、schema 的附加包替换成本不高。5.2 团队协作中的类型安全收益t3code 在团队协作里最大的价值不是省了写代码的时间而是消灭了一整类理解偏差问题。两个人合作开发一个功能时前端同学只要api.post.create.useMutation()一调参数类型自动弹出字段名拼错、类型写错在编辑阶段就会被拦下后端改字段类型时前端编译红叉立现。我把这套脚手架推进团队半年多之后联调会议从每周两次减少到基本没有因为根本不需要讨论这个接口返回哪些字段——代码就是契约编辑器就是文档。5.3 我踩过的坑和长期维护体会最后分享几个我自己的真实教训。第一个是全链路升级依赖的时候不要一口气把 Next.js、React、tRPC、Prisma 全部升到最新版。这几个库的版本耦合很紧尤其 tRPC 的 v10 和 v11 之间 API 变化非常大升级时建议逐一升级每升一个就完整跑一遍类型检查和测试。第二个是环境变量管理团队多人协作时建议做一个脚本从统一的面板拉取 .env 文件别在群里发明文——数据库连接串一旦泄露不只是隐私问题还可能被拖库。还有个容易忽略的细节prisma schema 是整个类型链路的源头每一次改动都要走代码评审。它不像普通代码可以频繁回滚schema 变更意味着数据库结构变更历史迁移文件无法伪造。所以我的建议是 schema 文件优先由最有经验的同事审宁可改慢一点也不要留下错误字段。如果你准备搭一个全新的全栈 TypeScript 项目我建议直接花一个小时跑一遍 t3code 的初始化流程自己动手创建一个带数据库的简单功能你会直观感受到类型从数据库长到页面上是一种什么体验。踩过几次坑之后大概率就回不去手写 API 层的老路子了。