1. 项目概述与真实定位1.1 为什么会有 t3code 这样的项目做开发的时间长了你会发现一个很有意思的现象大家每年都在说“不要重复造轮子”但真正到了团队起步、新项目初始化的时候大部分时间还是消耗在“搭架子”上。从选技术栈开始到配置路由、状态管理、样式方案、接口请求层、环境变量、代码规范、CI/CD这一套流程下来一个经验丰富的全栈工程师也得折腾一两天。如果团队里每个人的习惯还不一样那项目风格很快就变得“百花齐放”维护成本直线上升。t3code 就是冲着这个痛点去的。它不是一个简单的模板仓库而是一套完整的、可扩展的现代 Web 应用开发脚手架。我第一次接触到 t3code 的思路时第一反应是这不就是把 Next.js、TypeScript、Prisma、tRPC 这些东西全部揉在一起吗但真正用下来之后我才发现它背后的设计逻辑远不只是“把热门库堆起来”这么简单。t3code 解决的核心问题有两个第一个是“启动速度”让一个新项目从零到能跑起来、能部署控制在十分钟以内第二个是“类型安全”它要求从前端到后端、从数据库到 API全程都走 TypeScript 的强类型通道把“类型不一致导致线上问题”这个最常见的故障源在编译期就彻底杜绝掉。这个项目适合谁我的判断是三类人一是中小型团队的技术负责人他们需要快速验证业务想法而不是花两周时间搭基础设施二是独立开发者一个人要扛前后端t3code 能省掉大量重复劳动三是刚想接触全栈开发的新人因为 t3code 本身就是一个很好的“全栈最佳实践”范例跟着它的结构走一遍比看十篇零散教程都有用。1.2 t3code 里的“T3”到底指什么很多人第一次看到 t3code 时都会问同一个问题T3 是什么意思。它不是版本号也不是代号而是三个以 T 开头的核心原则的缩写——Type-safe类型安全、Testable可测试、Traceable可追踪。Type-safe 比较好理解就是从数据库的表结构、API 的请求响应到前端组件的 props全部用 TypeScript 的类型系统串起来。你在前端写data.user.name如果数据库里根本没有name字段编译时就直接报错给你看而不是等用户访问页面时才发现白屏了。这个体验我在传统项目里受够了经常是后端改了字段名前端一点感觉都没有上线当天线上报错运营同事一脸懵地来问怎么回事。Testable 强调的是整个项目结构要为测试让路。前端组件怎么隔离依赖、API 路由怎么注入 mock 数据、数据库怎么用测试环境的内置事务回滚这些在 t3code 里都有一套默认的约定。我做过的不少项目里测试覆盖率低不是因为大家不想写而是代码结构本身就很难测——全局状态满天飞依赖关系纠缠不清。t3code 的做法是从目录结构和依赖注入方式上就把“可测性”固化成习惯。Traceable 指的是可观测性和问题追踪。从服务端日志、API 请求链路到前端的错误上报t3code 都预留了标准化的接口。这一点在做商业产品时特别重要很多时候用户反馈“点了没反应”你都不知道是前端 JS 报错、后端超时还是数据库慢查询。有了 traceable 的基础架构排查问题的时间能从小时级别降到分钟级别。这三个原则放在一起其实就是在说一件事代码不仅要能跑还要跑得稳、查得清、改得动。2. 技术方案设计与选型思路2.1 前端框架为什么选 Next.js 而不是 Vitet3code 前端底层用的是 Next.js这个选型应该说是经过了充分权衡的。我知道 Vite 在开发体验上确实香启动速度快到离谱热更新几乎是毫秒级。但 t3code 的核心场景是“服务端渲染优先的完整应用”不是单页管理后台所以 Next.js 的 SSR、SSG、ISR 这些能力就变得不可替代。举一个很实际的例子我做过一个面向 C 端用户的内容型产品首页的内容其实变化不频繁但个别区块需要每分钟更新。如果用纯客户端渲染的 SPA用户首次打开需要先加载 JS 包再发请求拿数据白屏时间在弱网环境下可能达到三四秒。而 Next.js 可以在编译时把大部分内容静态生成出来配合 ISR 定向刷新那个每分钟要更新的区块用户体验差距是肉眼可见的。Next.js 的另一个优势是它本身就是一套完整的“全栈框架”不只是前端框架。它的 API Routes 可以写轻量的后端接口它的 Server Actions 可以直接在前端组件里调用服务端逻辑它的采边渲染能力让前后端代码共享同一个类型定义成为可能。对 t3code 来说这些功能是搭建“全栈强类型体系”的地基。当然Next.js 也有缺点比如它的服务端渲染模式让很多习惯了单纯 SPA 开发的开发者觉得心智负担重容易分不清哪些代码跑在服务端、哪些跑在客户端。这一点 t3code 通过目录约定app目录下默认全是服务端组件手动标记use client的才算客户端组件来帮助使用者建立正确的心理模型。一句话总结Vite 是“开发体验好”的代表Next.js 是“产品体验好”的代表t3code 选择的是产品体验优先。2.2 数据层Prisma 带来的不只是 ORM数据访问层 t3code 用的是 Prisma。Prisma 在圈内被称为“下一代 ORM”但它做的事情其实已经超越了传统 ORM 的范畴。传统 ORM比如 Sequelize、TypeORM的核心工作是帮你把 SQL 映射成对象但 Prisma 更进一步的在于它建立了一套自己的类型安全体系。你在项目里先写schema.prisma定义一个数据库模型长什么样然后在终端跑一句prisma generate它就能自动生成一套完整的 TypeScript 类型和查询 API。这意味着你在写prisma.user.findUnique({ where: { id } })时传入的字段、返回的结果全部是强类型约束的写错了直接编译报错。Prisma 的 migrate 工具也值得单独提一下。传统的数据库迁移脚本是写一大坨 SQL 文件谁来执行、按什么顺序执行全靠自觉。Prisma Migrate 是从 schema 文件生成迁移历史记录你再也不需要记住“上次改表结构跑了哪几个脚本”。这个在多人协作的团队里尤其重要我在之前的项目里就吃过这种亏新同事拉代码后忘记跑一个中间的迁移文件结果本地表结构和代码对不上调试了一下午才发现是迁移没跑全。t3code 在数据层还有一层额外的封装——它把数据查询的逻辑和业务逻辑做了区分。你可以在/server/api/routers目录里写自己的业务查询也可以在需要直接操作数据的地方调用内部封装的 repository 函数。这种分隔不是为了炫技而是为了后续换数据库比如从 PostgreSQL 换成 MySQL时业务层的改动面足够小。2.3 tRPC被低估的接口通信方案如果说 Next.js 和 Prisma 还算是“常规操作”那 tRPC 就是 t3code 里最“秀”的一环了。tRPC 的全称是 TypeScript Remote Procedure Call它解决的一个看似简单但实际非常棘手的问题让前端调用后端接口时类型定义能够自动跟着走不需要手写 API 文档不需要手写请求函数。传统的前后端联调流程是什么样的后端同学写一个接口然后更新 Swagger 文档前端同学对着文档写请求函数然后自己定义返回类型还要和后端对齐字段名。一旦字段改了个名这个过程得重来一遍。这中间消耗的时间、产生的沟通成本做过多项目的人应该都懂。tRPC 的做法是把后端 API 路由直接用函数的形式暴露出来。在后端定义一个hello函数export const appRouter router({ hello: procedure .input(z.string()) .query(({ input }) Hello ${input}!), });然后前端调用时const result await trpc.hello.query(world);result的类型自动就是string而且如果后端改了输入参数的类型前端编译立刻报错不需要去翻文档、也不需要在线沟通。更重要的是它不需要像 GraphQL 那样引入一整套复杂的 schema 语法和 codegen 工具链就是纯 TypeScript 的函数调用。有人会问那这不就是把接口搬到前端代码里了吗其实不是tRPC 的调用是真正的网络请求只不过它把你的“接口文档”从静态的文本变成了动态编译的类型检查。这个方案对“前后端同构的工程化团队”来说提升的效果是最明显的我第一次用 tRPC 完成一个完整功能时最大的感受是“再也不用半夜被前端叫起来对字段名了”。3. 核心功能拆解与目录结构3.1 t3code 的目录结构为什么这样设计t3code 的目录结构不是随便分分的每一个目录的存在都有它的理由。我第一次打开这个项目的目录时第一反应是“怎么这么多 src”的嵌套但用了一段时间后我发现每个模块的位置基本上是固定的闭着眼都能找到想改的文件这种“心智负担低”的体验对日常开发来说价值很大。标准的 t3code 项目结构大致如下prisma/ schema.prisma migrations/ src/ app/ # Next.js 的 App Router页面文件 api/ # 后端的 API 路由入口 layout.tsx page.tsx pages/ server/ api/ routers/ # tRPC 路由定义 root.ts # 根路由聚合 db.ts # Prisma 客户端实例 auth.ts # 认证配置逻辑 trpc/ server.ts # tRPC 服务端初始化 client.ts # tRPC 客户端调用封装 types/ styles/ lib/ utils.ts env.js # 环境变量集中定义 middleware.ts关键设计集中在几个文件里。prisma/schema.prisma是你的数据源src/server/api/routers/是你的后端业务逻辑src/app是你的前端页面和路由三者结合构成了一条完整的数据流管道。src/env.js这个文件虽然小但它解决了一个很多人都会忽视的问题环境变量的类型校验。你在里面用zod定义每个环境变量应该有的格式、哪个是必填、哪个有默认值。这样如果你没配置DATABASE_URL就直接启动应用会明确告诉你缺了什么而不是让你面对一个“页面转圈但查不到原因”的诡异错误。我自己在以往项目里因为环境变量拼写错误、缺少某个配置项导致的线上问题保守估计已经两位数了t3code 在项目模板层面就把这块堵住了。3.2 配置体系的三个关键文件t3code 的配置体系里有三个文件是新手最容易忽视、但恰恰是项目能否顺畅运行的关键。第一个是prisma/schema.prisma。它不只是定义数据库模型的“样子”而是整个项目类型系统的源头。你在需求里新增一个“用户手机号”字段不是先去数据库工具里加列也不是先在 API 层加字段而是先改 schema再跑生成命令然后所有相关的类型引用都会自动同步。这个流程在 t3code 里已经固化成肌肉记忆了需求变化 → 改 schema → 创建/执行 migration → 业务层自动切换新类型。第二个是src/server/auth.ts。t3code 的默认认证方案是基于支持的几大主流认证方式的比如账号密码、GitHub OAuth 等但这块一般在你真的接入真实用户体系时需要定制。我建议不要跳过它的封装直接把第三方 SDK 塞进页面里因为认证逻辑牵扯 session、cookie、CSRF、登录状态保持、权限校验这些横切关注点如果散落在各处代码里后期维护就是灾难。第三个是next.config.mjs。它里面做的主要是编译器相关设置比如给路径别名开启/映射。这个映射看着不起眼但在实际开发里有了它你就再也写不出../../../../lib/utils这种魔鬼路径。路径别名的价值不在于少打几个字而在于代码重构时不再因为目录层级变化导致所有 import 全部失效。3.3 全栈类型安全的链路是怎么串起来的这里我用一个具体的功能来展示 t3code 如何把“类型安全”贯穿整条链路。假设我们要做一个“获取当前用户信息”的接口。第一步在src/server/api/routers/user.ts里定义import { z } from zod; import { createTRPCRouter, publicProcedure, protectedProcedure } from ../trpc; export const userRouter createTRPCRouter({ getMe: protectedProcedure.query(async ({ ctx }) { const user await ctx.db.user.findUnique({ where: { id: ctx.session.user.id }, select: { id: true, name: true, email: true, image: true }, }); return user; }), });第二步为了不把整个后端数据对象暴露给前端你可以用select限定返回字段。前端调用的时候拿到的user对象类型就是{ id: string; name: string; email: string; image: string | null }。第三步前端组件里const { data: user, isLoading } trpc.user.getMe.useQuery();你在前端拿到的user?.email一定存在而不是“也许有、也许没有”的any。如果哪天后端把email字段改名成了emailAddress你这边编译直接报错连运行都不用运行。这条链路的精髓在于从数据库 schema 开始到 Prisma Client 生成的类型再到 tRPC 路由的 input/output 校验再到 React Query 的 hooks 返回值全程是同一套类型系统。不再需要手动写“interface UserDTO”然后用as强行断言——那种写法等于自己骗自己类型安全的大堤在断言的瞬间就已经溃堤了。4. 实操过程与核心功能实现4.1 从零到一用 t3code 初始化一个全栈项目这部分我给一个完整可复现的实操过程。环境要求是 Node.js 18、npm/pnpm/yarn 任一包管理器、已安装 Docker数据库容器要用。首先初始化项目npx create-t3-applatest my-t3-app如果这个命令还没有提供最新版本也可以直接用npm create t3-applatest。它会进入交互模式向你询问需要启用哪些插件包括 Next.js、Prisma、tRPC、Tailwind CSS、NextAuth.js、DrizzleORM 等。默认建议是把核心的几个都选上后面不需要的功能再手动移除。初始化完成后cd my-t3-app npm install然后在.env里补充你的数据库连接串默认是 PostgreSQLDATABASE_URLpostgresql://postgres:postgreslocalhost:5432/t3app?schemapublic启动 PostgreSQL 容器docker compose up -d db同步数据库结构npx prisma db push最后启动开发环境npm run dev打开http://localhost:3000你应该能看到一个可以直接登录、操作数据库的动态页面 —— 是的一个全栈应用已经跑起来了从命令开始到访问首页通常不超过五分钟这比你自己从零搭要快一个量级。4.2 3 个日常开发的典型场景场景一新增一张业务表。假设我们要加一个Post文章模型。修改prisma/schema.prismamodel Post { id String id default(cuid()) title String content String published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt }执行迁移npx prisma migrate dev --name add_post_model然后就能在 tRPC 路由里愉快地使用ctx.db.post了。场景二写一个需要鉴权的上报接口。用protectedProcedure代替publicProceduretRPC 内部会自动检查 session未登录用户会被统一拦截不需要在每个接口里手写一堆if (!session)的判断。场景三做一个数据分页列表。借助 Prisma 的能力你可以在路由里直接用skip和take再搭配前端 React Query 的useInfiniteQuery做无限滚动。类型安全检查、状态管理、缓存更新这些琐碎细节都不用自己手写。4.3 部署与上线的真实操作笔记t3code 的部署方案官方推荐的是本地 Docker 镜像部署或者平台一键部署。我实测过两种路线。本地 Docker 部署的思路是先构建生产镜像npm run build docker build -t my-t3-app .然后 Docker 容器启动时需要传入DATABASE_URL、认证相关的密钥等环境变量。这里有个小提示部署前一定要重新跑npx prisma migrate deploy而不是db push。db push是开发环境快速同步表结构的工具它会直接改数据库而migrate deploy是执行已有的 migration 历史更安全、更可控适合生产环境。在线平台部署以 Vercel 为例也方便。把代码推到 Git 仓库后关联 Vercel 项目在后台填好环境变量然后每次 push 到主分支自动触发构建部署。实测下来部署完的页面加载性能、SSR 响应速度和本地表现基本一致不用额外做太多调优文章。需要特别注意的是生产环境的NEXTAUTH_URL或类似的站點地址配置务必改成实际的线上域名不然登录跳转永远回到 localhost这个问题出现过非常多次。5. 常见问题与排查技巧实录5.1 类型报错Data 类型不匹配很多新手拿到 t3code 后遇到的第一个拦路虎是类型不匹配报错。比如Type string | undefined is not assignable to type string。这本质上不是 t3code 的 bug而是 TypeScript 的严格空值检查生效了。正确做法是遵从类型系统用if (value undefined)或value ?? fallback处理而不是用as string强行断言。断言确实能一时解决报错但它等于告诉 TypeScript “你检查得不对我说了算”一旦数据确实缺失你就在运行时给自己埋了一颗地雷。在我的经验里t3code 的类型报错有九成是开发者自己“绕路”导致的。绕路一时爽出bug火葬场。把类型检查当作一个严格的老师顺着它改代码而不是想方设法让它闭嘴。5.2 Prisma 冷启动慢本地跑的时候第一次访问数据库接口会看到明显的延迟这是 Prisma 引擎启动时加载查询库的必然开销。解决办法是使用prisma-client的accelerate功能或者在生产环境保持数据库连接复用。还有一个简单技巧在本地开发时开启DATABASE_URL的池化连接字符串比如?pgbouncertrue之类的连接配置可以在冷启动时有明显改善。实际生产环境我建议用独立的连接池方案这不仅是性能问题也是为了应对瞬间大流量时连接数被打满的情况。我自己在活动页推广时遇到过一次数据库连满导致的雪崩从那以后数据库连接池就再也没省过。5.3 tRPC 请求一直 500但日志里看不到细节这个问题排查起来很折磨人。tRPC 的错误默认会聚合在一个响应体里但日志信息不一定是完整的栈信息。最有效的方法是两步第一步在服务端 tRPC 配置里开启详细错误日志在onError回调里打日志第二步把request.query的入参也带上日志这样定位问题就清晰多了。const createTRPCContext ({ req, res }) { ... }; onError: ({ error, path, input }) { console.error(tRPC error on, path, input:, input, error:, error); },跑了这层日志后剩下的多半是 zod 校验失败或者数据库查询字段不存在。这类问题定位出来后修复一般不超过十分钟。5.4 Next.js 的页面渲染模式困惑t3code 的app目录默认是服务端组件这意味着很多你习惯直接写在组件里的浏览器 APIwindow、document都会报错。对付这个问题记住一条原则默认你想调浏览器 API 时需要标记use client或者把相关逻辑放进useEffect里。例如use client; export default function ClientComponent() { useEffect(() { console.log(window.innerWidth); }, []); return divclient/div; }这个原则很简单但确实是很多 Next.js App Router 新手最容易陷入的坑尤其是之前只写过纯 SPA 的开发者。我在团队里见过一个同事把use client放在了文件最顶部结果整个组件树都变成了客户端渲染SSR 的优势完全没吃到。所以要刻意注意不是整个页面要么全是客户端要么全是服务端而是哪个组件需要浏览器能力哪个组件单独标 client。这也是 t3code 的核心设计之一。6. 使用 t3code 一个月后的真实体会6.1 研发效率的提升幅度我带着它实际做了两个半项目之后最大的感知是“从想法到可演示原型”的时间被压缩到原来的三分之一左右。以前写一个全栈 demo前后端一起差不多要三天我第一次用 t3code 写同类型 demo半天就完成了剩下半天还在琢磨怎么把多余的空闲时间用来完善交互细节。这种效率提升不只来自脚手架本身的模板更多来自 t3code 所强化的那些习惯——统一的技术选型、统一的目录约定、统一的类型流动方式。团队里不需要再开“技术栈统一”的会议因为新项目仓库的结构天然一致新同学入职后的上手成本显著降低因为他们照着 t3code 的惯例走就不会犯大方向错误。6.2 什么时候不建议用 t3code我总结了几类不适合它的情况给大家做参考。第一类老项目重构。老项目通常有自己的技术栈、目录结构和迁移路径直接把 t3code 套上去容易制造两套体系并存的混乱。第二类纯管理后台或纯展示型页面。如果完全没有服务端渲染需求API 也极其简单用 Vite React 就够了硬套 t3code 反而徒增心智负担。第三类团队对 TypeScript 本身还不够熟悉的场景。类型安全是先有“约束”再有“收益”的如果团队连类型报错都理解不了光靠 t3code 改变不了根本问题。6.3 最后分享一个小技巧用 t3code 这种全栈框架时我建议把基础设施相关的代码和业务代码彻底分开。你在src/server/api/routers里写的路由函数尽量保持成“只做业务编排”不要直接操作数据库的细节。把查询、更新、删除这些操作统一封装到一个repository目录里页面、组件和路由就都不需要关心它们调的是 Prisma、接的是第三方 API 还是内存 mock 了。这样做的价值在后期特别明显当你想把单机数据库换成云数据库、把直连改成连接池、把部分查询下沉到专门的查询服务时只需要动 repository 一层其他部分不受影响。t3code 本身已经替你做好了“从零到一”剩下的“一到无穷”就看你这颗 repository 的种子埋得深不深了。
t3code全栈脚手架：Next.js+Prisma+tRPC打造类型安全开发体验
1. 项目概述与真实定位1.1 为什么会有 t3code 这样的项目做开发的时间长了你会发现一个很有意思的现象大家每年都在说“不要重复造轮子”但真正到了团队起步、新项目初始化的时候大部分时间还是消耗在“搭架子”上。从选技术栈开始到配置路由、状态管理、样式方案、接口请求层、环境变量、代码规范、CI/CD这一套流程下来一个经验丰富的全栈工程师也得折腾一两天。如果团队里每个人的习惯还不一样那项目风格很快就变得“百花齐放”维护成本直线上升。t3code 就是冲着这个痛点去的。它不是一个简单的模板仓库而是一套完整的、可扩展的现代 Web 应用开发脚手架。我第一次接触到 t3code 的思路时第一反应是这不就是把 Next.js、TypeScript、Prisma、tRPC 这些东西全部揉在一起吗但真正用下来之后我才发现它背后的设计逻辑远不只是“把热门库堆起来”这么简单。t3code 解决的核心问题有两个第一个是“启动速度”让一个新项目从零到能跑起来、能部署控制在十分钟以内第二个是“类型安全”它要求从前端到后端、从数据库到 API全程都走 TypeScript 的强类型通道把“类型不一致导致线上问题”这个最常见的故障源在编译期就彻底杜绝掉。这个项目适合谁我的判断是三类人一是中小型团队的技术负责人他们需要快速验证业务想法而不是花两周时间搭基础设施二是独立开发者一个人要扛前后端t3code 能省掉大量重复劳动三是刚想接触全栈开发的新人因为 t3code 本身就是一个很好的“全栈最佳实践”范例跟着它的结构走一遍比看十篇零散教程都有用。1.2 t3code 里的“T3”到底指什么很多人第一次看到 t3code 时都会问同一个问题T3 是什么意思。它不是版本号也不是代号而是三个以 T 开头的核心原则的缩写——Type-safe类型安全、Testable可测试、Traceable可追踪。Type-safe 比较好理解就是从数据库的表结构、API 的请求响应到前端组件的 props全部用 TypeScript 的类型系统串起来。你在前端写data.user.name如果数据库里根本没有name字段编译时就直接报错给你看而不是等用户访问页面时才发现白屏了。这个体验我在传统项目里受够了经常是后端改了字段名前端一点感觉都没有上线当天线上报错运营同事一脸懵地来问怎么回事。Testable 强调的是整个项目结构要为测试让路。前端组件怎么隔离依赖、API 路由怎么注入 mock 数据、数据库怎么用测试环境的内置事务回滚这些在 t3code 里都有一套默认的约定。我做过的不少项目里测试覆盖率低不是因为大家不想写而是代码结构本身就很难测——全局状态满天飞依赖关系纠缠不清。t3code 的做法是从目录结构和依赖注入方式上就把“可测性”固化成习惯。Traceable 指的是可观测性和问题追踪。从服务端日志、API 请求链路到前端的错误上报t3code 都预留了标准化的接口。这一点在做商业产品时特别重要很多时候用户反馈“点了没反应”你都不知道是前端 JS 报错、后端超时还是数据库慢查询。有了 traceable 的基础架构排查问题的时间能从小时级别降到分钟级别。这三个原则放在一起其实就是在说一件事代码不仅要能跑还要跑得稳、查得清、改得动。2. 技术方案设计与选型思路2.1 前端框架为什么选 Next.js 而不是 Vitet3code 前端底层用的是 Next.js这个选型应该说是经过了充分权衡的。我知道 Vite 在开发体验上确实香启动速度快到离谱热更新几乎是毫秒级。但 t3code 的核心场景是“服务端渲染优先的完整应用”不是单页管理后台所以 Next.js 的 SSR、SSG、ISR 这些能力就变得不可替代。举一个很实际的例子我做过一个面向 C 端用户的内容型产品首页的内容其实变化不频繁但个别区块需要每分钟更新。如果用纯客户端渲染的 SPA用户首次打开需要先加载 JS 包再发请求拿数据白屏时间在弱网环境下可能达到三四秒。而 Next.js 可以在编译时把大部分内容静态生成出来配合 ISR 定向刷新那个每分钟要更新的区块用户体验差距是肉眼可见的。Next.js 的另一个优势是它本身就是一套完整的“全栈框架”不只是前端框架。它的 API Routes 可以写轻量的后端接口它的 Server Actions 可以直接在前端组件里调用服务端逻辑它的采边渲染能力让前后端代码共享同一个类型定义成为可能。对 t3code 来说这些功能是搭建“全栈强类型体系”的地基。当然Next.js 也有缺点比如它的服务端渲染模式让很多习惯了单纯 SPA 开发的开发者觉得心智负担重容易分不清哪些代码跑在服务端、哪些跑在客户端。这一点 t3code 通过目录约定app目录下默认全是服务端组件手动标记use client的才算客户端组件来帮助使用者建立正确的心理模型。一句话总结Vite 是“开发体验好”的代表Next.js 是“产品体验好”的代表t3code 选择的是产品体验优先。2.2 数据层Prisma 带来的不只是 ORM数据访问层 t3code 用的是 Prisma。Prisma 在圈内被称为“下一代 ORM”但它做的事情其实已经超越了传统 ORM 的范畴。传统 ORM比如 Sequelize、TypeORM的核心工作是帮你把 SQL 映射成对象但 Prisma 更进一步的在于它建立了一套自己的类型安全体系。你在项目里先写schema.prisma定义一个数据库模型长什么样然后在终端跑一句prisma generate它就能自动生成一套完整的 TypeScript 类型和查询 API。这意味着你在写prisma.user.findUnique({ where: { id } })时传入的字段、返回的结果全部是强类型约束的写错了直接编译报错。Prisma 的 migrate 工具也值得单独提一下。传统的数据库迁移脚本是写一大坨 SQL 文件谁来执行、按什么顺序执行全靠自觉。Prisma Migrate 是从 schema 文件生成迁移历史记录你再也不需要记住“上次改表结构跑了哪几个脚本”。这个在多人协作的团队里尤其重要我在之前的项目里就吃过这种亏新同事拉代码后忘记跑一个中间的迁移文件结果本地表结构和代码对不上调试了一下午才发现是迁移没跑全。t3code 在数据层还有一层额外的封装——它把数据查询的逻辑和业务逻辑做了区分。你可以在/server/api/routers目录里写自己的业务查询也可以在需要直接操作数据的地方调用内部封装的 repository 函数。这种分隔不是为了炫技而是为了后续换数据库比如从 PostgreSQL 换成 MySQL时业务层的改动面足够小。2.3 tRPC被低估的接口通信方案如果说 Next.js 和 Prisma 还算是“常规操作”那 tRPC 就是 t3code 里最“秀”的一环了。tRPC 的全称是 TypeScript Remote Procedure Call它解决的一个看似简单但实际非常棘手的问题让前端调用后端接口时类型定义能够自动跟着走不需要手写 API 文档不需要手写请求函数。传统的前后端联调流程是什么样的后端同学写一个接口然后更新 Swagger 文档前端同学对着文档写请求函数然后自己定义返回类型还要和后端对齐字段名。一旦字段改了个名这个过程得重来一遍。这中间消耗的时间、产生的沟通成本做过多项目的人应该都懂。tRPC 的做法是把后端 API 路由直接用函数的形式暴露出来。在后端定义一个hello函数export const appRouter router({ hello: procedure .input(z.string()) .query(({ input }) Hello ${input}!), });然后前端调用时const result await trpc.hello.query(world);result的类型自动就是string而且如果后端改了输入参数的类型前端编译立刻报错不需要去翻文档、也不需要在线沟通。更重要的是它不需要像 GraphQL 那样引入一整套复杂的 schema 语法和 codegen 工具链就是纯 TypeScript 的函数调用。有人会问那这不就是把接口搬到前端代码里了吗其实不是tRPC 的调用是真正的网络请求只不过它把你的“接口文档”从静态的文本变成了动态编译的类型检查。这个方案对“前后端同构的工程化团队”来说提升的效果是最明显的我第一次用 tRPC 完成一个完整功能时最大的感受是“再也不用半夜被前端叫起来对字段名了”。3. 核心功能拆解与目录结构3.1 t3code 的目录结构为什么这样设计t3code 的目录结构不是随便分分的每一个目录的存在都有它的理由。我第一次打开这个项目的目录时第一反应是“怎么这么多 src”的嵌套但用了一段时间后我发现每个模块的位置基本上是固定的闭着眼都能找到想改的文件这种“心智负担低”的体验对日常开发来说价值很大。标准的 t3code 项目结构大致如下prisma/ schema.prisma migrations/ src/ app/ # Next.js 的 App Router页面文件 api/ # 后端的 API 路由入口 layout.tsx page.tsx pages/ server/ api/ routers/ # tRPC 路由定义 root.ts # 根路由聚合 db.ts # Prisma 客户端实例 auth.ts # 认证配置逻辑 trpc/ server.ts # tRPC 服务端初始化 client.ts # tRPC 客户端调用封装 types/ styles/ lib/ utils.ts env.js # 环境变量集中定义 middleware.ts关键设计集中在几个文件里。prisma/schema.prisma是你的数据源src/server/api/routers/是你的后端业务逻辑src/app是你的前端页面和路由三者结合构成了一条完整的数据流管道。src/env.js这个文件虽然小但它解决了一个很多人都会忽视的问题环境变量的类型校验。你在里面用zod定义每个环境变量应该有的格式、哪个是必填、哪个有默认值。这样如果你没配置DATABASE_URL就直接启动应用会明确告诉你缺了什么而不是让你面对一个“页面转圈但查不到原因”的诡异错误。我自己在以往项目里因为环境变量拼写错误、缺少某个配置项导致的线上问题保守估计已经两位数了t3code 在项目模板层面就把这块堵住了。3.2 配置体系的三个关键文件t3code 的配置体系里有三个文件是新手最容易忽视、但恰恰是项目能否顺畅运行的关键。第一个是prisma/schema.prisma。它不只是定义数据库模型的“样子”而是整个项目类型系统的源头。你在需求里新增一个“用户手机号”字段不是先去数据库工具里加列也不是先在 API 层加字段而是先改 schema再跑生成命令然后所有相关的类型引用都会自动同步。这个流程在 t3code 里已经固化成肌肉记忆了需求变化 → 改 schema → 创建/执行 migration → 业务层自动切换新类型。第二个是src/server/auth.ts。t3code 的默认认证方案是基于支持的几大主流认证方式的比如账号密码、GitHub OAuth 等但这块一般在你真的接入真实用户体系时需要定制。我建议不要跳过它的封装直接把第三方 SDK 塞进页面里因为认证逻辑牵扯 session、cookie、CSRF、登录状态保持、权限校验这些横切关注点如果散落在各处代码里后期维护就是灾难。第三个是next.config.mjs。它里面做的主要是编译器相关设置比如给路径别名开启/映射。这个映射看着不起眼但在实际开发里有了它你就再也写不出../../../../lib/utils这种魔鬼路径。路径别名的价值不在于少打几个字而在于代码重构时不再因为目录层级变化导致所有 import 全部失效。3.3 全栈类型安全的链路是怎么串起来的这里我用一个具体的功能来展示 t3code 如何把“类型安全”贯穿整条链路。假设我们要做一个“获取当前用户信息”的接口。第一步在src/server/api/routers/user.ts里定义import { z } from zod; import { createTRPCRouter, publicProcedure, protectedProcedure } from ../trpc; export const userRouter createTRPCRouter({ getMe: protectedProcedure.query(async ({ ctx }) { const user await ctx.db.user.findUnique({ where: { id: ctx.session.user.id }, select: { id: true, name: true, email: true, image: true }, }); return user; }), });第二步为了不把整个后端数据对象暴露给前端你可以用select限定返回字段。前端调用的时候拿到的user对象类型就是{ id: string; name: string; email: string; image: string | null }。第三步前端组件里const { data: user, isLoading } trpc.user.getMe.useQuery();你在前端拿到的user?.email一定存在而不是“也许有、也许没有”的any。如果哪天后端把email字段改名成了emailAddress你这边编译直接报错连运行都不用运行。这条链路的精髓在于从数据库 schema 开始到 Prisma Client 生成的类型再到 tRPC 路由的 input/output 校验再到 React Query 的 hooks 返回值全程是同一套类型系统。不再需要手动写“interface UserDTO”然后用as强行断言——那种写法等于自己骗自己类型安全的大堤在断言的瞬间就已经溃堤了。4. 实操过程与核心功能实现4.1 从零到一用 t3code 初始化一个全栈项目这部分我给一个完整可复现的实操过程。环境要求是 Node.js 18、npm/pnpm/yarn 任一包管理器、已安装 Docker数据库容器要用。首先初始化项目npx create-t3-applatest my-t3-app如果这个命令还没有提供最新版本也可以直接用npm create t3-applatest。它会进入交互模式向你询问需要启用哪些插件包括 Next.js、Prisma、tRPC、Tailwind CSS、NextAuth.js、DrizzleORM 等。默认建议是把核心的几个都选上后面不需要的功能再手动移除。初始化完成后cd my-t3-app npm install然后在.env里补充你的数据库连接串默认是 PostgreSQLDATABASE_URLpostgresql://postgres:postgreslocalhost:5432/t3app?schemapublic启动 PostgreSQL 容器docker compose up -d db同步数据库结构npx prisma db push最后启动开发环境npm run dev打开http://localhost:3000你应该能看到一个可以直接登录、操作数据库的动态页面 —— 是的一个全栈应用已经跑起来了从命令开始到访问首页通常不超过五分钟这比你自己从零搭要快一个量级。4.2 3 个日常开发的典型场景场景一新增一张业务表。假设我们要加一个Post文章模型。修改prisma/schema.prismamodel Post { id String id default(cuid()) title String content String published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt }执行迁移npx prisma migrate dev --name add_post_model然后就能在 tRPC 路由里愉快地使用ctx.db.post了。场景二写一个需要鉴权的上报接口。用protectedProcedure代替publicProceduretRPC 内部会自动检查 session未登录用户会被统一拦截不需要在每个接口里手写一堆if (!session)的判断。场景三做一个数据分页列表。借助 Prisma 的能力你可以在路由里直接用skip和take再搭配前端 React Query 的useInfiniteQuery做无限滚动。类型安全检查、状态管理、缓存更新这些琐碎细节都不用自己手写。4.3 部署与上线的真实操作笔记t3code 的部署方案官方推荐的是本地 Docker 镜像部署或者平台一键部署。我实测过两种路线。本地 Docker 部署的思路是先构建生产镜像npm run build docker build -t my-t3-app .然后 Docker 容器启动时需要传入DATABASE_URL、认证相关的密钥等环境变量。这里有个小提示部署前一定要重新跑npx prisma migrate deploy而不是db push。db push是开发环境快速同步表结构的工具它会直接改数据库而migrate deploy是执行已有的 migration 历史更安全、更可控适合生产环境。在线平台部署以 Vercel 为例也方便。把代码推到 Git 仓库后关联 Vercel 项目在后台填好环境变量然后每次 push 到主分支自动触发构建部署。实测下来部署完的页面加载性能、SSR 响应速度和本地表现基本一致不用额外做太多调优文章。需要特别注意的是生产环境的NEXTAUTH_URL或类似的站點地址配置务必改成实际的线上域名不然登录跳转永远回到 localhost这个问题出现过非常多次。5. 常见问题与排查技巧实录5.1 类型报错Data 类型不匹配很多新手拿到 t3code 后遇到的第一个拦路虎是类型不匹配报错。比如Type string | undefined is not assignable to type string。这本质上不是 t3code 的 bug而是 TypeScript 的严格空值检查生效了。正确做法是遵从类型系统用if (value undefined)或value ?? fallback处理而不是用as string强行断言。断言确实能一时解决报错但它等于告诉 TypeScript “你检查得不对我说了算”一旦数据确实缺失你就在运行时给自己埋了一颗地雷。在我的经验里t3code 的类型报错有九成是开发者自己“绕路”导致的。绕路一时爽出bug火葬场。把类型检查当作一个严格的老师顺着它改代码而不是想方设法让它闭嘴。5.2 Prisma 冷启动慢本地跑的时候第一次访问数据库接口会看到明显的延迟这是 Prisma 引擎启动时加载查询库的必然开销。解决办法是使用prisma-client的accelerate功能或者在生产环境保持数据库连接复用。还有一个简单技巧在本地开发时开启DATABASE_URL的池化连接字符串比如?pgbouncertrue之类的连接配置可以在冷启动时有明显改善。实际生产环境我建议用独立的连接池方案这不仅是性能问题也是为了应对瞬间大流量时连接数被打满的情况。我自己在活动页推广时遇到过一次数据库连满导致的雪崩从那以后数据库连接池就再也没省过。5.3 tRPC 请求一直 500但日志里看不到细节这个问题排查起来很折磨人。tRPC 的错误默认会聚合在一个响应体里但日志信息不一定是完整的栈信息。最有效的方法是两步第一步在服务端 tRPC 配置里开启详细错误日志在onError回调里打日志第二步把request.query的入参也带上日志这样定位问题就清晰多了。const createTRPCContext ({ req, res }) { ... }; onError: ({ error, path, input }) { console.error(tRPC error on, path, input:, input, error:, error); },跑了这层日志后剩下的多半是 zod 校验失败或者数据库查询字段不存在。这类问题定位出来后修复一般不超过十分钟。5.4 Next.js 的页面渲染模式困惑t3code 的app目录默认是服务端组件这意味着很多你习惯直接写在组件里的浏览器 APIwindow、document都会报错。对付这个问题记住一条原则默认你想调浏览器 API 时需要标记use client或者把相关逻辑放进useEffect里。例如use client; export default function ClientComponent() { useEffect(() { console.log(window.innerWidth); }, []); return divclient/div; }这个原则很简单但确实是很多 Next.js App Router 新手最容易陷入的坑尤其是之前只写过纯 SPA 的开发者。我在团队里见过一个同事把use client放在了文件最顶部结果整个组件树都变成了客户端渲染SSR 的优势完全没吃到。所以要刻意注意不是整个页面要么全是客户端要么全是服务端而是哪个组件需要浏览器能力哪个组件单独标 client。这也是 t3code 的核心设计之一。6. 使用 t3code 一个月后的真实体会6.1 研发效率的提升幅度我带着它实际做了两个半项目之后最大的感知是“从想法到可演示原型”的时间被压缩到原来的三分之一左右。以前写一个全栈 demo前后端一起差不多要三天我第一次用 t3code 写同类型 demo半天就完成了剩下半天还在琢磨怎么把多余的空闲时间用来完善交互细节。这种效率提升不只来自脚手架本身的模板更多来自 t3code 所强化的那些习惯——统一的技术选型、统一的目录约定、统一的类型流动方式。团队里不需要再开“技术栈统一”的会议因为新项目仓库的结构天然一致新同学入职后的上手成本显著降低因为他们照着 t3code 的惯例走就不会犯大方向错误。6.2 什么时候不建议用 t3code我总结了几类不适合它的情况给大家做参考。第一类老项目重构。老项目通常有自己的技术栈、目录结构和迁移路径直接把 t3code 套上去容易制造两套体系并存的混乱。第二类纯管理后台或纯展示型页面。如果完全没有服务端渲染需求API 也极其简单用 Vite React 就够了硬套 t3code 反而徒增心智负担。第三类团队对 TypeScript 本身还不够熟悉的场景。类型安全是先有“约束”再有“收益”的如果团队连类型报错都理解不了光靠 t3code 改变不了根本问题。6.3 最后分享一个小技巧用 t3code 这种全栈框架时我建议把基础设施相关的代码和业务代码彻底分开。你在src/server/api/routers里写的路由函数尽量保持成“只做业务编排”不要直接操作数据库的细节。把查询、更新、删除这些操作统一封装到一个repository目录里页面、组件和路由就都不需要关心它们调的是 Prisma、接的是第三方 API 还是内存 mock 了。这样做的价值在后期特别明显当你想把单机数据库换成云数据库、把直连改成连接池、把部分查询下沉到专门的查询服务时只需要动 repository 一层其他部分不受影响。t3code 本身已经替你做好了“从零到一”剩下的“一到无穷”就看你这颗 repository 的种子埋得深不深了。