t3code 这个名字是我自己给一套全栈开发模板起的代号。说白了它就是基于社区里很成熟的 T3 Stack 搭起来的一整套代码骨架包含 Next.js、TypeScript、Tailwind CSS、tRPC 这些核心成员再加上 Prisma 和 NextAuth 做数据与认证。我把它叫作 t3code是因为这已经不只是一个脚手架而是一套我反复打磨过的工程实践。如果你最近正好在研究 T3 Stack也在纠结要不要把这一套引到自己的项目里那这篇分享应该能帮上不少忙。我会从零开始拆解 t3code 的初始化、配置、业务开发、部署和排坑全程用我真正实操过的命令和踩过的坑说话不整虚的。1. t3code 初印象它到底帮你解决了什么问题1.1 一句话解释 t3code 是什么T3 Stack 常被解释为 TypeScript、Tailwind CSS 和 tRPC 的组合核心是追求端到端类型安全。在实际的 create-t3-app 模板里它还默认整合了 Next.js 作为应用框架并且让你可以自由选择是否接入 Prisma、NextAuth.js 等配套。t3code 就是围绕这个官方模板二次整理出来的产物对我而言它是“技术栈 目录规范 常用封装”的一整套综合体。直接把 T3 Stack 理解为“Next.js 全家桶”其实不太精确因为它最大的特点在于 tRPC 这种 RPC 方案。以前我们写前后端分离项目前端调后端接口得手动维护 OpenAPI 文档、手动定义类型、手动处理序列化一旦接口变动类型不同步的问题层出不穷。t3code 里tRPC 直接让后端 router 的类型被前端自动继承改一个字段前端代码立刻在编辑器里报错这类问题当场就能被发现。配合 TypeScript 严格模式这种安全感是以前写 Node.js 接口完全体会不到的。这套方案特别适合两类人一类是想要快速验证想法、又不愿意在前后端类型上反复折腾的全栈开发者另一类是从纯前端转后端、希望用最少的心智负担把数据库和 API 层跑起来的人。它的学习曲线并不算陡前提是你最好已经对 React 和 TypeScript 有基础了解。如果完全没接触过 TypeScript建议先花一周补一下泛型和类型推断不然你会被 tRPC 的类型魔法绕晕。1.2 为什么选 t3code 而不是传统 REST 方案早期做全栈应用最常见的做法是前端 Next.js后端单独写一个 Express 或 NestJS然后通过 axios 调接口。这样做本身没什么问题但项目一复杂就会出现几个让人头疼的点。第一接口文档经常和实际代码脱节改接口后忘了改文档协作者只能靠猜。第二前后端类型定义是两份存在重复的 interface一旦不同步联调期就变成了“排查 TypeScript 报错期”。第三简单的 CRUD 也要写很多样板代码比如 controller、service、路由注册、参数校验一个人干的时候还好团队协作时效率会被明显拖慢。t3code 对这些问题几乎是精准打击。tRPC 让前后端共用一个类型源不需要额外生成 schema 文件也不用手动写请求封装Zod 直接嵌入在 procedure 里做输入校验和 TypeScript 类型推导天然配合Prisma 的 schema 又是数据库层的唯一事实来源从表结构到客户端类型一步到位。换句话说整个项目的类型链路是通着的从数据库到后端路由再到前端组件改动都是连锁反应而不是四处失控。拿我自己的经验来说之前用 REST 写一个用户管理系统光接口定义和类型维护就花掉大概三分之一的开发时间。换到 t3code 之后同样功能的开发时间压缩了接近一半。当然它也不是银弹比如如果是纯后端服务或者要做非常复杂的第三方 API 聚合传统 REST 反而更通用。但如果你做的是 Next.js 内部的 BFF 层或者一个业务逻辑集中、页面交互复杂的应用T3 Stack 这套思路确实值得认真尝试。2. 环境准备与项目初始化5分钟先跑起来骨架2.1 准备阶段要装什么、用什么版本在动手之前先确认本机环境。t3code 基于 Next.js 14 开发Node.js 版本建议至少 18.17我自己用的是 Node 20 LTS开发过程很稳。包管理器方面pnpm 优先因为 create-t3-app 对 pnpm 的兼容性很好依赖安装速度和磁盘占用也比 npm 更理想。如果你不喜欢装额外的全局工具直接用 npm 或 yarn 也可以只是后续装依赖时注意保持统一即可。数据库的选择初期强烈建议先用 SQLite 跑通流程。它的好处是零配置、单文件特别适合做本地开发和测试等你要部署上线时再切换到 PostgreSQL。Prisma 对数据库的抽象做得很好理论上改一下 provider 和连接串大部分代码都不用动。不过如果你一开始就打算上云直接配 PostgreSQL 或者 MySQL 也没问题create-t3-app 里会要求你同时提供数据库连接地址提前准备好一个连接串就行。2.2 用 create-t3-app 初始化 t3code初始化命令非常简单直接在终端里执行pnpm create t3-applatest t3code交互式界面会问你几个问题依次是:是否使用 TypeScript、是否使用 Tailwind CSS、是否使用 tRPC、是否使用 NextAuth.js、是否使用 Prisma。因为我需要完整还原 t3code 的形态这里我全部选择 Yes。还有一个问题是是否需要 import alias选默认的/*别名就行后面写代码时会非常方便。等待依赖安装完成后进入项目目录先执行一次数据库迁移把初始的 User 表和 Session 表建出来cd t3code pnpm db:push这个命令实际上是执行prisma db push它会根据 schema.prisma 里的定义把表结构直接同步到数据库免去手动写 SQL 的步骤。然后再启动开发服务器pnpm dev打开http://localhost:3000能看到默认的欢迎页和登录入口说明骨架已经跑通了。整个初始化过程顺利的话五分钟之内就能完成如果你被卡在网络或者 Node 版本问题上优先排查是不是源的问题、版本是不是太老。2.3 初始化后的目录结构怎么理解跑起来之后先别急着改页面花几分钟把目录结构过一遍。t3code 的核心目录是src/下面有几个关键位置。src/app是 Next.js App Router 的页面路由目录文件即路由页面组件都放这里。src/server是纯后端逻辑区其中api/trpc.ts负责创建 tRPC 的上下文和根路由api/routers/存放所有子路由比如post.ts、user.ts最终在根路由里合并。src/trpc/server.ts和react.ts则是给服务端组件和客户端组件使用的 tRPC 封装前端调用接口全靠它们。另一个必看目录是prisma/里面只有一个schema.prisma这是数据模型的定义文件。所有数据库表结构、字段、关联关系都在这里声明然后通过 Prisma 生成客户端代码。整个设计的分层逻辑很清晰App Router 负责页面和布局Server 层的 tRPC 负责接口和业务逻辑Prisma 层只关心数据库。这种单向依赖让代码很容易追踪你看到一个页面组件能快速定位它调用了哪个 tRPC query再去对应的 router 里找到具体实现。这套结构对熟悉 MVC 的老开发来说可能有点反直觉但适应之后你会觉得比 Controller 那套轻快得多。3. 核心配置与数据链路把数据库、认证和 API 焊死在一起3.1 Prisma 数据模型设计与迁移流程既然要做真实业务数据模型肯定得先定。t3code 初始模板里已经带了 User 和相关的 NextAuth 表但实际开发时通常要扩展业务表。举个例子在我的 Todo 应用里我在schema.prisma里增加了这么一段model Todo { id String id default(cuid()) title String done Boolean default(false) createdAt DateTime default(now()) userId String user User relation(fields: [userId], references: [id]) } model User { id String id default(cuid()) name String? email String unique todos Todo[] }这里用cuid()而不是自增 ID好处是分布式环境不容易冲突而且不暴露数据库行数。修改完 schema 后执行迁移命令npx prisma migrate dev --name add_todo这个命令会自动生成迁移文件并且重新生成 Prisma Client。有一点要注意Prisma Client 的类型是根据 schema 实时生成的所以改了模型之后一定要重新跑一次迁移或者prisma generate否则前端类型还是旧有的编辑器会把新字段标红。我早期经常漏掉这一步折腾了半小时才发现是生成的 client 没更新。另外生产环境千万别再用db push改 schema因为它不产生迁移历史团队协作或回滚时会很被动。开发环境可以用但到了正式阶段一定走migrate deploy。3.2 NextAuth 接入要点配置环境变量与 Providercreate-t3-app 默认集成了 NextAuth.js初始化时如果选了它src/server/auth.ts就已经准备好了配置骨架。默认配置用的是 Discord Provider因为它不需要审核可以直接拿到 client ID 和 secret。如果你要做 GitHub 登录需要先去 GitHub OAuth Apps 页面创建一个应用然后把回调地址填到 Authorization callback URL一般是http://localhost:3000/api/auth/callback/github拿到 ID 和 secret 后把它们写进.envGITHUB_CLIENT_IDxxx GITHUB_CLIENT_SECRETxxx NEXTAUTH_SECRETxxxNEXTAUTH_SECRET是必填项这个是用作 session 加密签名的密钥可以直接用openssl rand -base64 32生成一个。忘了设这个本地可能还能开但部署到线上每次重启 session 都会失效用户会被强制登出。如果你只是做内部工具不想接第三方 OAuth也可以改成 Credentials Provider自己控制用户名密码验证。不过我不太建议这么快就自己实现密码哈希因为涉及 salt、轮数、重置密码等一堆安全细节先用 OAuth 跑通后面再加自己的登录体系会更稳。3.3 tRPC 路由组织和权限控制tRPC 的根路由在src/server/api/root.ts里所有子路由都要在这里合并export const appRouter createTRPCRouter({ todo: todoRouter, post: postRouter, user: userRouter, });每个子路由都是一组 procedure 的集合procedure 相当于传统后端的一个接口。核心在于它天然支持 query 和 mutation 的区分query 表示查数据mutation 表示写数据。比如查询 Todo 列表可以这样写export const todoRouter createTRPCRouter({ getAll: publicProcedure .input(z.object({ userId: z.string() })) .query(async ({ ctx, input }) { return ctx.prisma.todo.findMany({ where: { userId: input.userId, done: false }, orderBy: { createdAt: desc }, }); }), });如果某些接口要求登录模板里已经准备了protectedProcedure它会先检查 session 是否存在没有就直接抛异常。这种做法比传统 REST 里自己写if (!req.user)要干净得多因为它是通过中间件抽象做到的业务代码里根本不需要再关心用户的登录态。另一个很有用的设计是createTRPCContext它在每个请求进来时顺手把当前 session 和 Prisma client 塞进ctx后续所有 procedure 可以直接取用等价于帮你把依赖注入的活干完了。4. 实操从零写一个带权限的 Todo CRUD4.1 后端接口只写核心逻辑不写重复代码继续用 Todo 业务来看完整流程。假设我们的需求是用户登录后能创建 Todo、查看自己的 Todo 列表、标记完成、删除 Todo。这四个操作对应的 tRPC router 已经可以覆盖全部不需要额外再建 REST 路由。创建接口可以这样写create: protectedProcedure .input(z.object({ title: z.string().min(1).max(100) })) .mutation(async ({ ctx, input }) { return ctx.prisma.todo.create({ data: { title: input.title, userId: ctx.session.user.id, }, }); }),这里两个细节值得注意。第一是protectedProcedure它本身就保证了必须有登录用户所以后端不用再做一次“当前用户是谁”的判断。第二是 Zod 的输入校验字符串最短 1、最长 100前端就算传一个超级长的字符串进来也是先被这里拦截不会打到数据库。这些逻辑放在 REST 项目里通常要写在中间件或者 service 层但在 t3code 里就是 procedure 的一个属性简洁明了不少。更新和删除接口类似但删除时一定要加一个where条件的双重校验保证用户只能删自己的数据remove: protectedProcedure .input(z.object({ id: z.string() })) .mutation(async ({ ctx, input }) { const result await ctx.prisma.todo.deleteMany({ where: { id: input.id, userId: ctx.session.user.id }, }); return { deleted: result.count 0 }; }),用deleteMany而不是delete是因为 Prisma 的delete如果找不到记录会直接抛异常而deleteMany会返回影响的行数更适合这种“允许删除失败但不希望报错”的场景。这个是我踩过坑之后总结出来的初期用delete实现前端频繁报 500改掉之后逻辑干净多了。4.2 前端调用类型自动联动组件里直接写 hook后端 router 写完前端就可以无缝开调。因为 tRPC 的类型推导关系api.todo.getAll等方法的入参和出参类型在编辑器里是直接提示的写错了甚至有红线标出。组件里调用 query 和 mutation 的写法类似 React Query拿创建 Todo 举例const utils api.useUtils(); const createTodo api.todo.create.useMutation({ onSuccess: async () { await utils.todo.getAll.invalidate(); }, }); function handleSubmit() { createTodo.mutate({ title }); }这里有一个非常重要的细节onSuccess里一定要调用invalidate()让列表重新拉取。很多人第一次用 tRPC 会觉得奇怪“为什么我创建完列表没刷新”。因为 tRPC 的 query 默认有缓存mutation 成功之后如果不主动失效缓存旧数据会一直留在页面上。这个行为和数据请求库是一致的理解了这一点就不会抱怨“接口没生效”了。另一个常见操作是分页列表和无限滚动tRPC 也提供了useInfiniteQuery配合 cursor 参数可以做游标分页。如果你之前只用过 REST 加 page/pageSize临时换成这种写法可能会不太习惯但游标分页在数据量上来之后性能明显更好推荐试试。4.3 错误处理与加载态像给用户交代一样处理异常tRPC 的错误处理也很有特色。后端如果抛一个TRPCError前端 hook 的error对象里会带上 code 和 message你可以直接判断是什么错误类型来展示不同文案。比如查询详情时数据不存在可以抛NOT_FOUND前端就能显示“这条记录不存在”而不是笼统的“请求失败”。我在 t3code 里封装了一个统一的错误提示组件把error映射成中文消息避免每个页面都写一套类似的判断逻辑。做法也不复杂在根布局或者页面组件里加一个ErrorBoundary捕获 tRPC 抛出来的错误并展示。实际上 Next.js 的error.tsx文件也能做这事按页面目录建一个就好。另外要提醒一句不要把后端的错误 message 原样展示给用户特别是包含 SQL 片段或者堆栈信息的那种有信息泄露风险。最好在后端统一转成友好的 public message内部详细日志通过控制台或日志服务记录。加载态方面tRPC 的 hook 会自动管理isLoading、isFetching这些状态不需要手动维护一个全局 loading。但要注意区分isLoading代表首次加载没有数据适合显示骨架屏isFetching代表后台刷新不一定需要打断用户操作。如果你在编辑页和列表页之间切换合理利用这些状态用户体验会自然很多。5. 部署上线与排坑记录把 t3code 推到生产环境前必看5.1 部署 Vercel 时数据库和环境的配置t3code 部署到 Vercel 本身不复杂但因为默认开发环境用的是 SQLite上线前必须换成 PostgreSQL 这类远程数据库。我的做法是先在本地启动一个 PostgreSQL 实例或者直接用云数据库然后在.env.production里把DATABASE_URL指向远程连接串。要注意 Prisma 在 Vercel 的构建阶段需要跑prisma generate项目模板里通常已经配好了 Vercel 的构建命令但如果你自己改了脚本记得加上这一步否则部署时会提示找不到 Prisma Client。Vercel 的环境变量页面里需要配置DATABASE_URL、NEXTAUTH_SECRET、OAuth 相关的 client 和 secret。最常见的一个坑是本地跑通了但线上登录永远报 OAuth 回调错误。原因多半是 OAuth Provider 里的回调地址填的是 localhost没有把线上的域名加进去。GitHub OAuth 里可以填多个 callback URL记得把https://你的域名/api/auth/callback/github也加上。如果你用 Docker 自建部署那就更简单了直接把环境变量传进容器就行。比较推荐的方式是构建镜像时执行prisma generate启动时执行prisma migrate deploy保证数据库结构和代码版本匹配。5.2 常见报错速查我踩过的坑和解决思路把 t3code 从开发到部署过程中遇到的高频问题整理成了一张速查表方便你直接对照排查。现象常见原因解决建议启动时报DATABASE_URL缺失.env文件没建立或环境变量名不对复制.env.example为.env填好配置修改 schema 后前端新字段报错忘记重新生成 Prisma Client执行npx prisma generate再重启 dev servertRPC 请求返回 401当前用户未登录调用了 protectedProcedure检查 NextAuth 登录状态或改用 publicProcedureVercel 部署后数据库连不上远程数据库 IP 白名单没放行在数据库控制台放行 Vercel 的部署 IP或改私网连接OAuth 登录回调失败回调 URL 未配置到线上域名在 OAuth Provider 里补充线上回调地址页面刷新后 404App Router 的动态路由写错文件名确认动态路由文件夹使用[param]命名查询很慢N1 查询问题使用 Prisma 的include或select提前关联数据排查这些问题的总原则是先看服务端日志再看 tRPC 的 error code最后看网络面板。t3code 的日志本身不多所以遇到奇怪问题我通常会在 procedure 里临时加一段console.log打印入参和 session基本能定位出来是权限问题还是数据问题。5.3 性能优化与日常维护心得t3code 这种类型安全架构日常维护其实比传统 REST 项目舒服很多但也有一些性能细节值得注意。Prisma 的查询尽量只查需要的字段不要一上来就findMany({ include: { todos: true } })这样会把不相关的关联数据全部带出来。用select明确字段网络传输和数据库压力都会有明显改善。如果你要对大量行做统计优先用count操作而不是查全表再在前端算这点谁用谁知道。另一个值得优化的地方是查询缓存。tRPC 的 query 默认是无限缓存的适合不常变的数据但对于 Todo 这类实时性较强的数据可以在 query 里配staleTime和refetchOnWindowFocus让页面在重新聚焦时自动刷新。合理利用这些配置比上缓存服务要省心得多。依赖升级也是日常维护的一部分。create-t3-app 的社区更新频率不低偶尔会有一些破坏性变更。我的建议是每两周做一次pnpm update升级前仔细看 release notes特别是 Next.js 和 tRPC 的 major 版本更新别着急追新先在小分支上测试。最后再分享一个实用技巧在 t3code 里做功能开发时尽量遵循“先定义 need再写 schema再写 router再写页面”的顺序。这条流程看起来慢但每个环节都有明确的类型检查卡点越往后越省力。我一开始经常跳步骤先写页面再补接口结果不是这里类型对不上就是那里入参缺失反而返工更多。现在老老实实按顺序走t3code 项目的开发效率已经稳定在我的工具链第一梯队了。
