t3code：基于T3技术栈的全栈工程骨架解析与实战-北京尧图网络

t3code 这个项目最初就是被我自己一次次重复初始化给逼出来的。团队里每开一个全栈项目都要重新搭 Next.js、接 TypeScript、配 Prisma、连通 tRPC、再调整 Tailwind这套流程走顺了也要一个下午走不顺就是一天起步。后来我把这套东西沉淀成一个代码模板库就叫 t3code它不是一个新框架而是一套围绕 T3 技术栈Next.js TypeScript tRPC Prisma Tailwind的工程骨架把 Web 全栈应用里最常用、最容易出错的部分固定下来。这篇文章主要聊它的设计、踩坑和一次完整的落地过程适合正在用 React 做全栈、或者想在团队里减少重复造轮子的人。t3code 的核心思路是把“技术选型”从每个项目里拿掉让开发人员打开仓库时看到的已经是一个跑得通、类型安全、页面和接口连起来的完整应用而不是一堆需要自己拼装的积木。下面的内容会先拆解为什么选择这条路线再带你走一遍实际搭建流程最后把我在使用过程中整理的踩坑记录一起交出来。1. 项目脉络为什么会有 t3code1.1 从我最不想做的初始化工作说起如果你单独写过 Next.js 项目大概能体会初始化阶段有多烦。先要 npx create-next-app然后安装 TypeScript 相关依赖配置tsconfig.json的严格模式接着引入 Prisma初始化数据库连接定义第一个 model再装 tRPC搞定 server 和 client 的边界处理上下文类型和procedure的导出方式最后还不一定能记住 Tailwind 的版本Tailwind 3 和 4 的配置方式差别还不小。一台新机器、一个新仓库想把这一套完整跑通至少是半天工作量。我在经历第三次的时候就开始烦了。烦的不是写业务代码而是这些“结构性代码”每个项目都是同一份NextAuth 配置、Prisma 的全局单例、tRPC 的 createTRPCContext、Tailwind 的 content 扫描路径。它们不产生业务价值却占用大量心智。t3code 就是针对这个问题做的它在create-t3-app生成的原始模板基础上再往前推了一步加入目录划分、文件命名规范、错误处理、超时重试、日志约定甚至在模板里预置一个示例业务模块让接手项目的人可以照着示例结构写代码而不是去猜这个仓库怎么组织。1.2 T3 栈每个成员在干什么T3 这个名字容易让人迷惑好像是个新框架其实不是。它就是一套社区里被验证过的组合彼此之间用 TypeScript 的类型串起来。我这里用表格整理一下每个成员的实际职责方便不熟悉的人快速对齐。成员实际职责典型场景Next.js负责路由、SSR、静态生成和前端渲染页面、layout、服务端组件TypeScript全链路类型约束约束接口、请求、响应数据和 API 的契约tRPC提供前端直调后端的类型安全 RPC替代手写 fetch 和 REST clientPrisma数据库建模、迁移和类型安全的查询用户、订单、文章等数据的 CRUDTailwind CSS原子化样式减少写 CSS 的上下文切换页面排版、组件样式NextAuth认证与会话配合 Prisma 持久化 session登录、注册、OAuth 回调这套组合最吸引我的点是它把“类型安全”从数据库一直带到浏览器。你在 Prisma 里定义一个Book模型tRPC 后端返回Book[]前端useQuery拿到结果后不用写任何类型断言编辑器里直接能补全book.title。如果数据库字段改了编译阶段就会报错不需要靠运行时去猜。1.3 t3code 不是框架是骨架有人会问你直接去用 create-t3-app 不行吗行但不够。create-t3-app 给出的是一个干净起点所有业务逻辑还是要自己从头组织。t3code 的定位更接近“骨架”它把项目结构、公共工具函数、认证封装、错误码规范放进去并且带一个可以删除的示例模块。新项目可以在这个骨架上直接长业务也可以只把它当做一个参考规范模仿它的目录组织方式。我在这个项目里特意没有做“过度封装”。模板里能看到所有的配置文件和中间件没有用一个黑盒包起来。原因很简单模板是要给团队用的如果大家看不懂包里的东西出了问题就会很痛苦。保持可见、保持简单每条规则都有注释比把一个复杂功能压缩成一行调用更靠谱。2. t3code 的核心设计与目录结构拆解2.1 目录结构为什么长这样t3code 的目录不是凭空想的每一项都有明确的目的。我拿当前版的目录当例子t3code/ ├── app/ │ ├── api/ # 任何需要 route handler 的场景 │ ├── (auth)/login/page.tsx # 登录页按路由组划分 │ └── dashboard/ │ ├── layout.tsx # 后台布局统一权限校验 │ └── books/page.tsx # 示例业务页面 ├── src/ │ ├── server/ │ │ ├── db.ts # Prisma 单例防止开发环境连接泄漏 │ │ ├── auth.ts # NextAuth 配置 │ │ └── api/ │ │ ├── root.ts # 合并所有子路由 │ │ ├── trpc.ts # tRPC 初始化和上下文类型 │ │ └── routers/ │ │ ├── book.ts # 示例业务路由 │ │ └── user.ts │ ├── trpc/ │ │ ├── client.ts # 前端 tRPC 客户端 │ │ ├── server.ts # 服务端类型辅助 │ │ └── react.tsx # Provider 封装 │ └── styles/ ├── prisma/ │ ├── schema.prisma │ └── seed.ts ├── .env.example └── package.json你可能会发现app/是 Next.js 的 App Router业务代码却放在src/下。这样做的原因是把“路由层”和“数据层”分开。路由文件尽量薄只负责取数据和渲染页面真正的业务逻辑、查询、权限判断都收在src/server中。以后如果要从 Next.js 迁移到别的框架改动集中在app/这层核心逻辑可以整体移动这对我这种经常改架构的人来说很有安全感。2.2 类型安全链路一个 schema 贯穿到底t3code 里我最满意的一点是让“数据库字段”成为整个应用的唯一事实来源。以图书管理为例先在prisma/schema.prisma里定义模型model Book { id String id default(cuid()) title String author String status String default(unread) createdAt DateTime default(now()) updatedAt DateTime updatedAt }接着在 tRPC 路由里写一个查询接口import { z } from zod; import { createTRPCRouter, publicProcedure } from ~/server/api/trpc; import { prisma } from ~/server/db; export const bookRouter createTRPCRouter({ list: publicProcedure .query(async () { return await prisma.book.findMany({ orderBy: { createdAt: desc }, }); }), create: publicProcedure .input(z.object({ title: z.string().min(1), author: z.string().min(1), status: z.enum([unread, reading, done]).default(unread), })) .mutation(async ({ input }) { return await prisma.book.create({ data: input }); }), });这里的重点不是代码量少而是类型推导。前端调用trpc.book.list.useQuery()时返回的data自动带上Book[]的所有字段。写错了字段名编辑器直接红标字段改了所有用它的地方都会提示更新。前后端不需要接口文档也不需要手工同步类型这就是 t3code 相对传统前后端分离的最大优势。2.3 认证和权限怎么抽出来认证是每个业务系统都绕不开的模块。t3code 里默认集成 NextAuth并封装了一层“受保护路由”避免每个页面里重复写 session 判断。操作上很简单在src/server/api/trpc.ts里定义protectedProcedureimport { createTRPCRouter, publicProcedure, protectedProcedure } from ~/server/api/trpc; export const userRouter createTRPCRouter({ me: protectedProcedure.query(async ({ ctx }) { return ctx.session.user; }), });protectedProcedure内部会先判断ctx.session是否存在不存在就抛出UNAUTHORIZED错误。页面端我还在app/dashboard/layout.tsx里加了一层服务端校验防止用户直接访问后台页面。前后端双重校验虽然代码多了一点但能保证接口不是裸奔的。3. 实操用 t3code 30 分钟搭一个全栈应用3.1 初始化与依赖安装我保证下面的每一步都是可以复现的。首先从模板仓库拉代码git clone https://github.com/your-org/t3code.git my-app cd my-app cp .env.example .env pnpm install依赖管理我用pnpm不是 npm。原因很实际pnpm 的硬链接机制在装 Next.js 和 Prisma 这种大依赖时明显更快磁盘占用也更小。如果你是单人项目npm 也不是不能用但团队协作时 pnpm 的安装一致性更好.lock文件变化也更可读。安装依赖后立刻启动数据库。本地开发我用 Docker 跑 PostgreSQLdocker run --name t3code-db -e POSTGRES_PASSWORDdevpassword -p 5432:5432 -d postgres:16接着在.env里配置DATABASE_URLpostgresql://postgres:devpasswordlocalhost:5432/t3code?schemapublic然后执行pnpm prisma migrate dev --name init。这会在数据库里建表同时生成 Prisma Client。到这里基础环境已经通了。3.2 定义第一个业务模型并完成迁移我用图书管理做示例继续往prisma/schema.prisma里加字段。比如增加tags数组和price金额字段model Book { id String id default(cuid()) title String author String price Decimal db.Decimal(10, 2) tags String[] status String default(unread) createdAt DateTime default(now()) updatedAt DateTime updatedAt }执行pnpm prisma migrate dev --name add_price_and_tags这里需要解释一下为什么price用Decimal而不是Float。货币计算对精度要求高数据库里Float会出现 0.1 0.2 不等于 0.3 的问题Decimal保存的是精确小数。t3code 里我默认推荐这个写法避免后面金额对不上账。3.3 写 tRPC API 并在页面调用刚才已经定义好bookRouter了接下来把它挂到根路由import { createTRPCRouter } from ~/server/api/trpc; import { bookRouter } from ~/server/api/routers/book; import { userRouter } from ~/server/api/routers/user; export const appRouter createTRPCRouter({ book: bookRouter, user: userRouter, }); export type AppRouter typeof appRouter;前端页面上这样调用use client; import { trpc } from ~/trpc/react; export default function BookList() { const { data: books, isLoading } trpc.book.list.useQuery(); const createBook trpc.book.create.useMutation({ onSuccess: () { // 重新拉取列表 }, }); if (isLoading) return p加载中/p; return ( ul {books?.map((book) ( li key{book.id}{book.title} / {book.author}/li ))} /ul ); }第一次写这种代码的人可能会有点不适应页面里没有 fetch、没有 axios、没有接口地址好像“网络请求消失了”。其实 tRPC 在背后做了很多事你不需要知道 URL也不需要对数据做类型断言这恰恰是它的价值。要记住的一点是页面默认是 Server Components凡是用了useQuery的组件必须加use client标记否则会报 hooks 错误。3.4 Tailwind 排版小实战业务系统不用花里胡哨的 UI但基本的排版还是要有的。t3code 里预置了 Tailwind并且把常用间距、颜色、Typography 类整理成常量。比如列表页卡片div classNamegrid grid-cols-1 gap-4 p-4 sm:grid-cols-2 lg:grid-cols-3 {books?.map((book) ( div classNamerounded-xl border border-gray-200 bg-white p-5 shadow-sm h3 classNametext-lg font-semibold text-gray-900{book.title}/h3 p classNamemt-1 text-sm text-gray-500{book.author}/p span classNamemt-3 inline-block rounded-full bg-blue-50 px-3 py-1 text-xs text-blue-700 {book.status} /span /div ))} /div这套样式在移动端和桌面端之间自动响应grid-cols-1到lg:grid-cols-3的断点让页面在不同尺寸下都有合理布局。实际开发中你可能会遇到“样式没生效”的情况多半是 Tailwind 的content配置没扫到 src 下的路径我在第 4 部分会给你排查方法。4. 常见问题与排查实录4.1 改了 schema 但 Prisma Client 报错这是 t3code 使用中最高频的问题你更新了schema.prisma也执行了prisma migrate dev但是程序运行时一直提示找不到某个字段或者在typeof prisma.book里类型没更新。根本原因通常是 Prisma Client 生成失效了。解决办法很简单pnpm prisma generate然后重启 dev server。如果还在报错检查package.json里的prisma版本和prisma/client版本是否一致。两个包版本不一致会导致 client 和 engine 对应不上这个问题在 pnpm 的 hoisting 策略下特别容易发生。我建议在根目录package.json里固定prisma为同一个版本号不要混装不同主版本的 Prisma。4.2 tRPC 的 input 类型和数据库字段老是对不上做表单提交时前端传来的字段大部分是string比如price用户输入的是12.99但 Prisma 模型里price是Decimal。tRPC 的 zod 校验会要求自定义类型于是经常看到一个错误Expected number, received string。我在模板里推荐两种做法。第一种是在前端 input 就转换好用Number(value)第二种是使用 zod 的 coerced 类型import { z } from zod; const inputSchema z.object({ title: z.string().min(1), price: z.coerce.number().positive(), });z.coerce会在运行时自动把字符串转成数字省去前端很多校验代码。但我必须提醒你不要滥用z.coerce去掩盖数据本身的格式问题。如果接口要接收ISO 日期最好直接用z.iso.datetime()配合z.coerce.date()严格控制输入格式把脏数据挡在接口外层。4.3 NextAuth 登录后一直跳回登录页这个坑我踩过不止一次。现象是用户输完账号密码NextAuth 返回成功但页面刷新后 session 又变成 null人被弹回登录页。排查思路按顺序来检查环境变量AUTH_SECRET是否设置。没有 secretsession 的 JWT 签名在服务端会不稳定。检查 NextAuth 的数据库 adapter 是否和你的 session 策略一致。如果你用 JWT session就不需要PrismaAdapter如果你要持久化 session就要保证AUTH_URL和数据库里的 session 表匹配。检查 Provider 的authorize回调是否返回了完整的 user 对象。只有id、email、name都有session 回调才能正常取到数据。t3code 的模板默认用 JWT session 加 credentials provider配置量小适合大多数内部系统。如果你要接入 GitHub、Google 登录建议单独看 NextAuth 的 adapter 文档把 Provider 的env配置提前准备好。4.4 部署到服务器后构建慢、镜像特别大用 t3code 搭的应用在部署时也会遇到性能问题。Next.js 和 Prisma 都是体积大户尤其 Prisma 会在构建时下载 query engine 二进制导致 Docker 镜像经常超过 1GB。我常用的优化有三个问题原因解决方式镜像大安装了 devDependencies多阶段构建生产阶段只装 dependencies启动慢Prisma 引擎不匹配在 schema 里声明binaryTargets [native, linux-musl-openssl-3.0.x]构建内存爆Next.js 并发压缩设置NEXT_PRIVATE_BUILD_WORKERS1我在团队里实际用下来通过多阶段构建和 binary target 精简镜像能从 1.2GB 压到 400MB 左右。注意如果你的部署环境是 Alpine 镜像binaryTargets就必须带linux-musl-openssl-3.0.x否则容器里连不上数据库只报一个很难懂的P1001错误。5. 模板的维护和落地经验5.1 模板不是一次性工程要持续演进t3code 这类仓库最容易犯的毛病是一开始很用心三个月后就没人维护。我现在的做法是固定迭代节奏每季度升级一次依赖升级时写一个小的 changelog记录从 Next.js 14 到 15、Tailwind 3 到 4 需要动哪些文件。升级依赖前先跑一遍模板里的示例测试确保create、list、update三个典型接口都正常。示例模块会被当做一个“冒烟测试项目”先挂 CI再给团队用。5.2 让新人看懂比让新人炫技重要模板做好的前提是所有人达成共识。我在团队里推广 t3code 时的体会是最需要强调的不是“类型安全”多酷而是这个约定能帮大家少填多少坑。我会让每个新人在 t3code 基础上加一个模块从 Prisma model 到 tRPC router 再到页面完整走一遍。这一步跑完他们对目录结构、类型链路、权限封装的认知基本就一致了。后面写业务代码时互相 review 的成本很低因为模式只有一种。t3code 后续我还在往里加的东西包括可选的单元测试模板、日志采集中间件、以及一套接口错误码规范。但我不打算把它做成一个复杂框架骨架就该保持骨架的样子。一个能看到所有配置、允许你随时改代码的模板比一个零配置的魔法黑盒更让人安心。你自己或你的团队去做类似沉淀时记住这点就够了。

t3code：基于T3技术栈的全栈工程骨架解析与实战

相关推荐

AI驱动的项目管理决策平台：易趋系统解析

WinHex定位FAT32文件首扇区：从MBR/DBR到起始簇号换算

WinHex数据恢复：MBR到FAT32目录项的扇区定位与交叉校验

更多资讯

AI原生应用中的持续学习技术实践与优化

Notepad++便携版配置指南：U盘免安装、正则替换与插件避坑

嵌入式硬件选型指南：从51到STM32、ESP32主流单片机对比与实战

绿色版Notepad++便携实战：配置、编码、运行与正则列编辑

PowerBuilder DataWindow 数据库开发机制与避坑

OpenMontage 开源视频剪辑自动化框架：从零搭建到批量渲染实战

今日更新

基于YOLOv11的石油泄漏智能检测系统开发实践

AI行业变局：合规、Mod化与上下文管理的实战启示

计算机视觉与AI原生应用融合的技术实践

本周精选

防幻觉智能体架构：电源硬件设计中的大模型编排与工具化实践

OpenGL面试核心考点：渲染管线、矩阵变换与性能排查全解析

全国计算机二级C语言真题PDF高效刷题指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？