第一次见到t3code这个名字时我以为又是一个赶时髦的缩写组合。真正把整套代码跑起来之后我才意识到它的价值不在某个单一框架而在于把现代全栈项目里最麻烦的“类型衔接”和“配置整合”一次性做完了。简单说t3code是一套基于 T3 技术栈的全栈项目底座核心组合是 Next.js TypeScript Tailwind CSS tRPC Prisma。它解决的问题非常具体前端调用接口不再靠猜后端改完字段前端立刻报错提醒数据库模型定义完类型能自动贯穿到页面组件和 API 层再加上 Tailwind 处理样式几乎不用在 CSS 文件之间反复跳转。这套组合适合前端想转全栈的开发者、独立开发者做小产品原型也适合三五个人的小团队统一技术底座。我后面所有内容都会基于这个项目模板来拆解尽量把每一步为什么这么做都讲清楚。1. 项目定位t3code 到底解决了什么问题1.1 全栈开发最常见的两种痛配置地狱和类型撕裂我先说一个很多团队从前后端分离转到全栈时的真实感受。传统做法是前端 React 一个仓库后端 Express 一个仓库两边各有一套接口文档。前端定义 request 类型后端定义 response 类型中间靠 Postman 或者 Swagger 同步。业务一复杂前端改了一个字段名后端还在用旧字段直到线上报错才被发现。这个问题的本质不是“写错代码”而是“类型没有在编译期打通”。t3code解决的就是这个痛点。它强制你用一套 TypeScript 类型贯穿整个链路Prisma 根据数据库 schema 生成类型tRPC 复用这些类型生成 API 调用函数前端组件里直接useQuery就能拿到带类型推断的返回值。改数据库字段迁移之后跑一遍prisma generate所有引用点一起报错IDE 里就能把所有关联位置找出来。这比任何运行时监控都更早地规避问题。另一个痛点更常见配置地狱。Next.js 项目要配 webpack、babel、tsconfig、并处理 API 路由和静态资源加上 Prisma 要管数据库连接和迁移加上 Tailwind 要配 content 路径和主题再加鉴权、环境变量一个项目半天起不来是常态。t3code本质上是把这些配置预先收敛成一套经过验证的默认值你不需要理解每一层怎么协同也能先跑起来等业务深入后再按需修改。1.2 什么场景适合用它什么场景最好绕开我用了大半年t3code之后对它的适用范围有了比较明确的判断。如果你做的事情是独立开发一个 SaaS 工具、企业内部系统、数据看板、内容后台或者你是几个人协作的小团队想在第一周就见到能跑的完整业务闭环那这套组合非常合适。它把最常见的“用户登录 - 数据写入 - 列表展示 - 权限控制”链路做成了开箱状态你只需要往里面填业务表结构。反过来如果你的场景是已经有庞大的遗留数据库和成熟的 REST/GraphQL 服务或者团队前端、后端是两拨人后端要用 Java/Go 独立维护那就不需要强行套t3code。它更适合那些自己掌握全流程、希望减少沟通损耗的人。还有个容易忽略的场景做外包或接私活。给甲方做后台管理项目时最怕的就是需求反复改字段。用t3code的打通式类型系统甲方要求给用户表加一个phone字段你改完 schema 生成迁移前端引用user.phone的地方对照编译错误全部改掉半小时内就能改完交付。2. 技术选型拆解为什么 t3code 按下的是“确定性优先”2.1 Next.js 作为全栈入口关键是心智统一t3code没有选择把前端打包成纯静态站点也没有选择 Express 单独开后端端口而是把整个应用放在 Next.js 里。很多人觉得 Next.js 只是 React 的服务端渲染框架其实它同时承担了页面路由、API 路由、服务端数据获取三层职责。在t3code里页面文件和 API 路由都在同一个应用进程内数据库调用发生在服务端浏览器拿到的是渲染完成的 HTML。这样做的最大好处是心智统一我不需要维护两个项目、两套部署流程、两套日志。尤其做个人项目时一个项目目录、一条启动命令、一份环境变量就能把完整系统跑起来。再说服务端渲染的收益。后台管理类页面往往有首屏数据加载需求。传统前端做法是页面加载后发出 fetch 请求 → 显示 loading → 数据返回 → 重新渲染。t3code的页面可以直接在服务端调用 tRPC 查询把数据作为当前页面的 props 传给组件首屏 HTML 里就带真实数据。用户感知是秒开搜索引擎也能读到内容这对内容型产品有实际价值。2.2 tRPC 让 API 调用像函数调用一样安全t3code里最颠覆使用习惯的是 tRPC。它不是一个传统框架而是一种“没有 API 的 API 方案”。你不需要手写 URL、method、请求体字段只需要在服务端定义一个 router在前端 import 同一个函数引用调用方式就是api.post.list.useQuery(...)。为什么能做到类型安全因为 tRPC 的 schema 由 zod 定义zod 对象既是运行时校验器又是静态类型来源。比如我定义list的输入是{ limit: number }那么在客户端调用时如果传了一个字符串limitTypeScript 编译期就会直接报错。如果服务端查询返回的字段和前端使用的字段不一致同样在编译期报错。很多不熟悉的人会担心tRPC 是不是只适合小项目我的看法是只要你的系统前端和服务端共享 TypeScript 代码库它就完全够用。大型系统里如果有什么模块必须独立部署你仍可以把 tRPC router 暴露为 HTTP 服务其他语言系统走标准 JSON 接口即可。至少在t3code这种模板存在的时间里它的维护价值远大于传统接口联调。2.3 Prisma 把数据库模型变成类型“源头”t3code的数据层选型是 Prisma。它的核心优势有三个schema 可读性好、迁移文件可审查、类型自动生成。Prisma schema 不像 TypeORM 那样用装饰器写死在实体类里而是一个独立的schema.prisma文件。你在这个文件里定义表和关系执行prisma migrate生成 SQL 迁移文件再执行prisma generate生成客户端代码。这个客户端代码内置了所有类型你的db.post.findMany()返回结果会被 TypeScript 推导成Post[]而且Post类型包含你定义的所有字段。用 Prisma 还有一个对新手很友好的地方错误提示相对清晰。字段名写错、关系没有定义迁移阶段就会报出来。对比直接写 SQL 的 mybatis 风格排查成本会低很多。t3code把 Prisma 和 tRPC 放在一起后数据库的列名就是前端接口返回字段的“唯一事实来源”彻底消灭了手写 DTO 和 VO 的重复劳动。2.4 Tailwind CSS 并不只是样式方案更是一种设计约束t3code引入 Tailwind CSS表面上看是“原子化 CSS 更省事”但我用下来发现它的真正价值是“避免样式命名灾难”。传统方式是每个组件一个.module.css或者在styles目录里定义 BEM 类名。项目一大类名冲突和优先级问题就开始出现。Tailwind 的做法是直接在 JSX 里写flex items-center justify-between这类工具类没有“样式文件与组件文件对应查找”的思维负担。当然原子类的代价是 JSX 会变长有些人觉得“模板里塞太多类名不够干净”。我的折中方案是把复杂的颜色和间距抽象成组件组件内部接受 className 覆盖页面层保持语义化命名和 Tailwind 工具类并存。t3code默认配置里也支持这个做法你不需要被“纯工具类”教条绑架按团队习惯调整即可。2.5 这几层到底是怎么配合的会不会打架我听到过一种质疑Next.js、tRPC、Prisma、Tailwind 都是独立发展阶段很强的工具硬放一起会不会互相牵制实际上它们的分工非常清晰。Prisma 管数据库层产出类型和查询客户端tRPC 管 API 层读取 Prisma 客户端并按 zod 规则校验入参Next.js 管路由和渲染层在服务端组件里调用 tRPC 查询在客户端组件里通过 hooks 触发修改Tailwind 只负责样式表达不掺和任何数据流。每一层只做一件事交给下一层的产物是强类型数据或 UI 描述没有循环依赖。真正的风险点其实是版本升级节奏。Next.js 每年有大版本更新tRPC 也有自己的迭代不能盲目更新要先看官方升级文档确认兼容性。t3code的价值也在于它是一个可复现的“稳定组合版本”你照着一份代码模板维护不会出现“按网上教程装完所有依赖但起不来”的情况。3. 从零初始化 t3code脚手架命令和目录设计3.1 一条命令生成可运行项目t3code的起点是官方脚手架 create-t3-app。我通常会先确认 Node.js 版本在 18 以上然后执行npx create-t3-applatest t3code创建过程中会让你选择需要的模块Next.js、TypeScript、Tailwind CSS、tRPC、Prisma、NextAuth.js。如果做的是一个需要登录的后台系统我会把 NextAuth.js 也勾上一次性把 session 机制和数据库用户表组件配好。还要注意选择“是否使用 import alias”。强烈建议选/*这样代码里的相对路径引用会明显更好维护。初始化完成后直接执行npm run dev打开本地 3000 端口看到的应该是一个带导航栏的首页。这一步相当于验证了“基础配置能跑通”后面改造业务是在一套已验证的建筑骨架上装修而不是空地起楼。3.2 目录结构如何暗示数据流我实际初始化出来并整理过的t3code目录结构大致是t3code/ ├─ app/ │ ├─ (auth)/ │ ├─ dashboard/ │ ├─ layout.tsx │ ├─ page.tsx │ └─ api/trpc/[trpc]/route.ts ├─ prisma/ │ ├─ schema.prisma │ └─ migrations/ ├─ server/ │ ├─ api/ │ │ ├─ root.ts │ │ ├─ trpc.ts │ │ └─ routers/ │ ├─ auth.ts │ └─ db.ts ├─ styles/ │ └─ globals.css ├─ .env.example ├─ next.config.js ├─ tailwind.config.ts └─ tsconfig.json这个结构最需要理解的是app和server的边界。app/api/trpc/[trpc]/route.ts是 Next.js 暴露 HTTP 端点的唯一入口它把 tRPC router 转成处理请求的标准路由。写业务的时候你很少需要改这个文件。server/api/routers才是写业务的地方每个业务域一个文件比如post.ts、user.ts最后在root.ts里合并成 appRouter。这样当你打开一个路由文件能一眼看到这个域提供了哪些查询和变更操作。server/db.ts是 PrismaClient 单例的导出位置。这里有个常见坑如果在多个文件里分别new PrismaClient()开发环境下会创建过多数据库连接热更新时尤其容易卡死。t3code默认生成代码里已经用全局变量缓存了 client我建议保留这个写法。3.3 关键配置文件里藏着的几个细节先看.env.example。它至少包含这些变量DATABASE_URLmysql://user:passwordlocalhost:3306/t3code NEXTAUTH_SECRETyour-secret NEXTAUTH_URLhttp://localhost:3000实际开发时我会把.env.example作为环境变量清单真正敏感的密钥放在.env.local里并确认 .gitignore 忽略了它。很多团队数据库密钥被提交到仓库事故就是这么来的。再看next.config.js它通常不需要大动。需要知道的是transpilePackages选项如果将来你开发了本地 npm 包想复用需要把包名加进去否则 Next.js 不会编译 node_modules 里那些未编译的 TS 代码。最后是tsconfig.json里的baseUrl和paths。t3code默认把./server/*指向源码目录。这个配置直接影响你在业务代码里import { db } from ~/server/db能否被正确解析。遇到“模块找不到”的错误第一反应不是去安装包而是检查 paths 配置和文件名大小写。4. 核心业务闭环用户、文章、仪表盘4.1 Prisma schema 设计与首次迁移只有脚手架没有业务模板是没有意义的。我来演示t3code里最常见的闭环用户发表文章首页展示文章列表后台显示统计数字。先定义 Prisma modelmodel User { id String id default(cuid()) email String unique name String? 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 createdAt DateTime default(now()) }设计上有两点值得说明。第一主键用cuid()而不是自增数字好处是分布式环境下不会撞号也避免让别人猜测业务总量。第二authorId的命名要和关系字段对应Prisma 才能正确识别多对一关系。写完后执行npx prisma migrate dev --name init这条命令会创建数据库表并生成迁移文件。迁移文件是文本形式应该提交到代码仓库这样团队成员prisma migrate deploy就能同步表结构。4.2 tRPC Router 编写规范接下来在server/api/routers/post.ts里定义文章查询接口import { z } from zod; import { createTRPCRouter, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure .input( z.object({ limit: z.number().min(1).max(50).default(10), }) ) .query(async ({ ctx, input }) { return ctx.db.post.findMany({ take: input.limit, orderBy: { createdAt: desc }, include: { author: { select: { name: true }, }, }, }); }), });这里最有意思的是input和output的类型都由 zod 推导。客户端调用时limit的类型、是否必须、取值范围全部被 TypeScript 感知。如果某天你在前端调用了limit: 100编译期就会被拦截而不是等到请求发起后后端报 400。我再扩展一个创建文章的 mutationcreate: publicProcedure .input( z.object({ title: z.string().min(1, 标题不能为空), content: z.string().min(1), authorId: z.string().cuid(), }) ) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: input.authorId, }, }); }),写好的 router 要在 root.ts 里合并export const appRouter createTRPCRouter({ post: postRouter, user: userRouter, });导出的appRouter就是整个前端的类型来源。核心习惯是每个业务域一个 router 文件不要在 root.ts 里堆业务代码否则后期几百行混在一起类型还能通但人已经疯了。4.3 页面数据接入类型安全第一次体现前端页面在app/dashboard/page.tsx里使用服务端组件方式调用import { api } from ~/server/api/root; import { db } from ~/server/db; export default async function DashboardPage() { const posts await db.post.findMany({ orderBy: { createdAt: desc }, take: 10, }); const total await db.post.count(); return ( main classNamep-6 h1 classNametext-2xl font-bold仪表盘/h1 p文章总数{total}/p ul {posts.map((post) ( li key{post.id}{post.title}/li ))} /ul /main ); }这段代码里没有 fetch、没有 URL、没有 any 类型。posts的类型完全来自 Prisma 的findMany返回值。如果改天Post表加了status字段前端直接写post.status就能拿到新字段不需要额外定义接口。对于需要动态交互的客户端组件就用 tRPC hooksuse client; import { api } from ~/server/api/react; export function PostList() { const { data, isLoading } api.post.list.useQuery({ limit: 10 }); if (isLoading) return p加载中.../p; return ( ul {data?.map((post) ( li key{post.id}{post.title} - {post.author.name}/li ))} /ul ); }api.post.list.useQuery的参数类型、返回类型全部从服务端 router 自动推导。这就是t3code的核心体验写完 router前端不需要再看接口文档。4.4 服务端渲染和客户端渲染该怎么选很多新手会把所有页面都写成客户端组件然后抱怨首屏慢。我的判断标准很简单页面内容如果和用户会话状态无关就优先用服务端组件直接查库页面内容如果完全依赖客户端交互比如搜索框、表单实时校验、弹窗就用带use client的组件。t3code里还有一个常用中间态在服务端组件里先取数据传给客户端组件客户端组件只负责交互。比如文章列表的筛选按钮可以把初始列表作为 props 传入后续筛选在客户端继续调用useQuery。这样首屏不闪烁交互又流畅。5. 实际运行中的那些坑我踩过的都写在下面5.1 tRPC 返回 Date 对象时的序列化边界tRPC 默认会把Date对象序列化成 ISO 字符串所以 Prisma 查询返回的createdAt到了前端就成了字符串。如果你写的组件直接用new Date(post.createdAt)没问题如果你用比较两个时间就会出现类型对不上。我的处理习惯是在 Prisma schema 里把日期类型保持为DateTime在展示层明确转成toLocaleString()。不建议为了省事把数据库字段降级成字符串因为排序、时区计算都会变成噩梦。5.2 Tailwind 动态拼接类名失效这是所有 Tailwind 用户都会踩的坑。在 JSX 里写${condition ? text-red-500 : text-gray-500}时类名是完整字符串能生效。但如果写成className{text-${color}-500}, Tailwind 的静态扫描就找不到text-red-500这个类编译产物里不会有对应样式。t3code项目里我的规避方法很简单要么使用完整的类名字符串要么在tailwind.config.ts的 safelist 里声明需要动态生成的类名组合。前者优先因为语义更清晰。5.3 Prisma 连接数打满与冷启动超时本地开发时热更新会频繁重建 PrismaClient如果不做全局缓存连接数会涨得很快。t3code默认的db.ts通常已经包含这段逻辑import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient | undefined; }; export const db globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) globalForPrisma.prisma db;这段代码的建议保留。另一个问题出现在 serverless 环境每次冷启动建立数据库连接会增加几百毫秒延迟。如果预算允许给 Prisma 加连接池配置比较稳妥。连接池连接字符串通常是DATABASE_URL的 URL 参数加上?connection_limit5这样的配置具体参数要看托管平台文档。5.4 环境变量混淆和密钥泄漏t3code的.env.example里写着 NEXTAUTH_SECRET。如果你不做登录功能这个变量无所谓一旦启用 NextAuth.js没有正确的 secret很多会话逻辑会随机失败。另一个常见错误是服务端代码里写了process.env.DATABASE_URL却在客户端组件里访问。Next.js 默认会把没有NEXT_PUBLIC_前缀的变量只暴露给服务端客户端引用到的值是undefined导致线上故障但本地模拟不出来。排查这类问题的顺序是先在页面服务端打印变量存不存在再确认客户端访问的环境变量名是否有NEXT_PUBLIC_前缀。6. 部署上线与日常维护要点6.1 构建打包和数据库迁移的顺序t3code部署时最容易翻车的场景是代码先发布数据库迁移还没跑前端查新字段直接报错。正确顺序是先执行数据库迁移再部署应用代码或者在同一部署流程里先 migrate 再 build。我在 CI 里的脚本一般是npx prisma migrate deploy npx prisma generate npm run buildmigrate deploy只执行未执行过的迁移文件不会像migrate dev那样要求你输入名称或重新生成迁移。正式环境永远只跑 deploy。prisma generate确保新的客户端类型被打进构建产物。最后再跑next build这样页面里用到的字段和数据库实际结构是一致的。6.2 认证、文件上传、监控这些扩展方向t3code模板本身更像地板和承重墙居住体验取决于你如何扩展。如果你需要登录把 NextAuth.js 的 provider 配置填好数据库里加Account、Session模型Prisma migrate 后就能用。文件上传建议独立走对象存储不要把文件放进数据库在本地开发时可以用localStorage目录线上换成 OSS/S3。监控维度上我最推荐先接日志其次接错误上报。t3code项目里我会用 Server Action 或 tRPC middleware 统一记录每个请求的耗时、输入参数和错误堆栈。注意不要记录密码和 token 字段日志泄漏也是数据安全事故。6.3 一条一直被我记住的开发纪律最后分享一个经验不一定和技术选型有关。用t3code这类强类型项目时最大的诱惑是“改完类型然后找遍所有引用点”。IDE 的重构功能可以把字段重命名一步到位但运行时有状态的数据比如用户已经写入的历史记录不会因为字段改名而自动迁移。所以凡是涉及核心表结构的修改我的习惯是先写数据迁移脚本再改类型和界面最后跑一遍全量测试确认没有脏数据。顺序反了短期看不出问题长期一定会被隐藏的旧数据绊倒。从我个人的使用体会看t3code最大的意义不是某一项技术而是它用组合拳把“类型安全”推到了开发者很容易获得的位置。它在提醒我好项目不是堆砌更多新轮子而是让每次改动都能在最早阶段暴露问题。如果你正在筹备一个全新的全栈产品我建议你照着这个思路把项目跑起来先让类型作为你最严格也最耐心的代码评审员。
