1. t3code到底是什么先聊清楚这个项目要解决的问题我最初看到“t3code”这个名字的时候第一反应是它跟T3 Stack有关。实际接触下来这个名字确实不是一个独立框架而是一套围绕TypeScript全栈开发的最佳实践集合。更准确地说t3code是我一直在维护的一个基于T3 Stack思想的开源模板项目它的核心目标就一句话让我们能用TypeScript从数据库到前端UI全部打通全程享受类型提示和编译期检查尽量减少“改了后端类型导致前端不知不觉就崩了”这类破事。先解释一下T3这个名词避免有朋友听得一头雾水。T3 TypeScript Tailwind CSS tRPC。这套组合在2023年到2024年间热度涨得很快原因也不复杂它把“全栈类型安全”这件事做到了一个非常舒服的平衡点。你写数据库查询拿到的是类型明确的结果你调API请求参数和响应结构的类型自动从前端标注出来你改一个字段名TypeScript编译器会瞬间告诉你哪里忘了同步。这个体验一旦适应了再回去写传统的前后端分离项目多少会觉得有些钝。t3code这套模板解决了什么问题呢它的定位不是从零教你“Hello World”而是提供一个在生产环境真正能直接用的起步结构。我见过太多脚手架项目GitHub星星倒是不少真正clone下来跑起来才发现缺东少西没有鉴权、没有数据库迁移脚本、没有错误处理中间件、没有SEO配置、没有通用的响应包装结构。等你把这一堆东西补完热情基本也耗光了。用t3code上手的话你的项目一开始就有这些东西Next.js 14的App Router结构、tRPC路由和API层、Prisma ORM与数据库迁移配置、NextAuth的GitHub和Google登录、Tailwind的原子化样式体系外加一套我已经在真实业务里跑过几个月的基础目录规范和错误处理方案。你可以直接在这个基础上开发自己的业务代码不用再重复造轮子。这套东西适合谁两类人最合适一类是受够了前后端联调时“你等一下我改个字段”的团队想试试全栈TypeScript的开发节奏另一类是正在学Next.js和tRPC需要一个相对完整、代码质量说得过去的项目作为参照的开发者。如果你本来就是传统Spring Boot加Vue的忠实用户那t3code可能对你吸引力不大因为整套技术体系的思路跟Java后端那一套差别还是比较远的。2. 核心设计思路为什么选择TypeScript全栈这条路2.1 类型安全到底“安全”在哪里很多朋友一听到“类型安全”就觉得是噱头觉得写好测试就完事了。我自己以前也这样想直到在一次项目迭代里真的被坑惨了。当时后端返回的user.createdAt字段从字符串改成了时间戳数字前端那个页面用来做日期排序结果排序逻辑全部失效而且是运行时才暴露。这种问题在传统前后端分离架构里太常见了接口的契约靠文档——文档一过期契约就散了错误只能靠跑起来才知道。t3code这套方案不搞文档同步因为根本不需要文档。数据模型定义在Prisma Schema里Prisma会根据这个Schema生成完整的TypeScript类型。tRPC把后端路由的函数输入输出类型直接暴露给前端Next.js组件里调api.user.getById.useQuery()返回的data.username如果字段写错了编辑器里直接飘红根本编译不过。也就是说出现我之前说的那种日期字段类型变更的问题时在前端代码编译的这一瞬间就会被发现根本不会带上线。这背后的原理说穿了也很朴素TypeScript是结构类型系统两个对象只要结构形状匹配类型就兼容。tRPC利用泛型把后端路由的输入输出类型信息一路传递到前端调用端。Prisma也一样数据库表结构通过代码生成器变成TS类型。这三层叠加起来数据库、API、页面UI全部被同一张类型网络覆盖住数据流走到哪一步类型检查就检查到哪一步。2.2 技术选型的取与舍T3 Stack之所以把tRPC放进来而不是选REST或GraphQL有一个很实际的理由tRPC简单。GraphQL确实强大但GraphQL的Schema定义、Resolver编写、客户端缓存策略、codegen配置这一套玩下来学习成本相当可观很多中小项目根本不需要那么强的灵活性。REST也还行但写接口路径、处理参数校验、维护跨端类型明显更费劲。tRPC的做法是直接基于TypeScript函数后端写一个函数前端调用这个函数不需要URL构造不需要手写请求逻辑参数和返回值的类型自动同步。当然tRPC也不是没有代价。它跟Next.js的Server Components配合时需要处理好服务端调用和客户端调用的边界这个稍后我会在实操部分详细演示。另外如果你的前端客户端不是TypeScript项目比如小程序用纯JavaScript那tRPC那套类型推导就发挥不出威力了。好在t3code的目标场景就是全TypeScript所以基本不存在这个问题。数据库层选了Prisma而不是TypeORM或者Drizzle原因也简单Prisma的Schema语法清晰迁移工具成熟类型生成直接集成在workflow里。写一次Schema建表脚本、TS类型、CRUD操作全部都有了内置的类型安全做得是整个Node生态里最好的那一档。对于我这种不喜欢反复切换上下文的人来说这个体验流畅得就像在IDE里有一个隐形的翻译助手。样式层选Tailwind CSS就不用多说理由了原子化CSS在组件化开发中的效率优势当年撸过一遍就能体会到。特别是在t3code这种组件多、迭代快的场景里不用为了一个按钮写一堆CSS类名然后反复切文件inline的样式工具类直观又高效。2.3 目录结构的一次到位t3code的项目结构是经过几轮实战调优的不是脚手架默认生成的那套原始布局。核心思路是按模块划分而不是按技术类型划分。你可以理解成“这个功能的所有代码放同一个文件夹”而不是“所有的组件放一个文件夹所有的API放另一个文件夹”。比如用户模块在src/server/api/routers/user.ts里配置tRPC路由src/server/db/schema.prisma里定义用户表前端组件文件里直接调用useQuery来取数据。增删改查的过程中不用去十几层深的目录里找文件所有关联代码都围绕功能模块就近摆放。这样做最大的好处是代码交接成本低——新同事看项目顺着路由文件的引用往上翻很容易理解业务逻辑是怎么串起来的。3. 实操步骤从clone t3code到跑通第一个业务接口3.1 环境准备与前五分钟跑通这个模板要求Node.js 18以上包管理器推荐pnpm因为pnpm的依赖安装速度比npm快而且磁盘占用小很多。第一步clone项目后首先要做的事情是安装依赖并把环境变量配好。模板里有一个.env.example文件复制一份改成.env然后填入两个关键配置数据库连接字符串和一个随机生成的安全密钥。git clone https://github.com/yourname/t3code.git my-project cd my-project pnpm install cp .env.example .env我这里以PostgreSQL为例连接字符串长这样DATABASE_URLpostgresql://postgres:postgreslocalhost:5432/t3code?schemapublic NEXTAUTH_SECRETyour-random-secret-key NEXTAUTH_URLhttp://localhost:3000安全密钥可以直接用openssl rand -base64 32生成别随便输入一串短密码完事那是很多朋友上线后被攻击的根源。依赖装好后跑一次数据库迁移pnpm db:push pnpm db:generate第一条命令是把Prisma Schema同步到数据库建表建约束第二条是重新生成Prisma Client的类型代码。跑完之后pnpm dev启动开发服务器浏览器打开http://localhost:3000能看到首页样式跑起来说明模板已经活了。3.2 从零添加一个“文章”模块的完整流程好演示一下真正上手之后怎么做业务开发。这里用最简单的“文章”功能为例一篇文章有标题、正文、作者和发布时间。第一步改Prisma Schema。打开src/server/db/schema.prisma在User模型下方新增一个模型model Post { id String id default(cuid()) title String content String author User relation(fields: [authorId], references: [id]) authorId String createdAt DateTime default(now()) updatedAt DateTime updatedAt }代码写好后回到终端跑pnpm db:push完成表结构同步。第二步写tRPC路由。打开src/server/api/routers/post.ts创建一个新的tRPC routerimport { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure.query(async ({ ctx }) { const posts await ctx.db.post.findMany({ include: { author: { select: { name: true } } }, orderBy: { createdAt: desc }, }); return posts; }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1), })) .mutation(async ({ ctx, input }) { const post await ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); return post; }), });有几个细节我想特别说一下。列表接口我用了publicProcedure因为是公告类内容游客也能看创建文章用了protectedProcedure这个模板自带登录校验逻辑未登录直接抛错不用你自己写鉴权代码。入参校验用的是Zodz.string().min(1)的意思是必须是非空字符串如果前端传了个空标题过来tRPC返回的报错信息会包含精确的校验提示。第三步把路由注册到根路由。打开src/server/api/root.ts把postRouter挂载到appRouter上export const appRouter createTRPCRouter({ post: postRouter, user: userRouter, // ...其他路由 });第四步写前端页面。在App Router的src/app/posts/page.tsx里use client; import { api } from ~/trpc/react; export default function PostsPage() { const { data: posts, isLoading } api.post.list.useQuery(); const utils api.useUtils(); const createPost api.post.create.useMutation({ onSuccess: () utils.post.list.invalidate(), }); if (isLoading) return div加载中.../div; return ( div h1文章列表/h1 {posts?.map((post) ( div key{post.id} h2{post.title}/h2 p{post.content}/p span{post.author.name}/span /div ))} button onClick{() createPost.mutate({ title: 测试标题, content: 测试正文, }) } 发布文章 /button /div ); }注意“use client”这行声明因为tRPC的useQuery是Hooks用法必须在客户端组件里使用。如果这个页面同时需要服务端渲染的SEO效果可以参考t3code模板里专门做的src/app/posts/page.server.tsx和page.client.tsx组合模式核心思路是页面主体用客户端组件调HooksSEO内容放在服务端组件里。最后也是很容易被忽略的一步在src/server/db/schema.prisma里把Post模型跟User模型的posts字段关联起来model User { id String id default(cuid()) name String? posts Post[] }这样整套流程就跑通了。浏览器里点击发布按钮新文章立即写入数据库页面列表自动刷新全程类型安全。字段名拼错、参数类型不匹配都是编译时直接报错连跑起来这个步骤都省了。3.3 给新模块加权限和错误处理一个写进的模块如果没有权限控制基本等于裸奔。t3code模板默认提供的protectedProcedure只能保证用户登录但要实现“只有作者本人能编辑自己的文章”还得靠自定义中间件。t3code里可以用tRPC的middleware机制实现import { TRPCError } from trpc/server; const canEditPost t.middleware(async ({ ctx, input, next }) { const { id } input as { id: string }; const post await ctx.db.post.findUnique({ where: { id } }); if (!post || post.authorId ! ctx.session?.user?.id) { throw new TRPCError({ code: FORBIDDEN }); } return next({ ctx: { post } }); }); export const protectedPostProcedure protectedProcedure.use(canEditPost);这个中间件的思路不太复杂拿到文章ID之后先把文章查出来判断作者是不是当前登录用户是就继续走不是就抛出403错误。它的意义在于把鉴权逻辑收拢到路由层业务方法里不掺杂权限判断代码后面要加“管理员也能编辑别人文章”的规则时只需要在这个中间件里加一个分支判断。错误处理方面t3code里我封装了一个统一错误体任何路由抛出的异常都被src/server/api/trpc.ts里的onError钩子捕获按INTERNAL_SERVER_ERROR和UNAUTHORIZED等不同code返回不同提示。这么做的好处是前端拿到的错误信息结构永远是一致的做全局toast提示时非常顺手。4. 部署与上线从本地到生产环境的关键配置4.1 用Docker把后端跑起来t3code里我写了一个可以直接用的docker-compose.yml开发环境下它会启动一个PostgreSQL容器和可选的MinIO对象存储容器。很多人本地开发的时候数据库用的是SQLite上线前再切换成PostgreSQL这种做法其实隐患不小。SQLite的锁机制和并发行为跟正式环境完全不同排查起来浪费的时间远比一开始就配好数据库要多。我的做法是从第一天就用PostgreSQL在Docker里跑开发环境和生产环境的环境变量保持一致。docker compose up -d postgres跑起来之后再看Prisma的迁移。模板里的schema文件已经定义好了所有模型直接用pnpm db:push同步即可。真要上线的话推荐使用prisma migrate deploy它只执行未应用过的迁移文件不会重跑已经执行过的脚本。4.2 部署到Vercel或自建服务器Next.js项目部署到Vercel基本是零配置的GitHub上连好仓库选择根目录Vercel自动识别Next.js框架环境变量填上即可。但我需要提醒一个问题如果你用了tRPC的服务端渲染查询Vercel的Serverless环境里函数冷启动的延迟会变得更量级显眼。白屏等待的一秒多钟有时候会直接影响用户体验尤其对To B系统来说体感差别还挺明显的。我的建议是部署目标如果是国内用户群更稳定的选择是自建一台服务器用Nginx加PM2或者Docker Compose跑。t3code模板里也带了一份生产环境的docker-compose.prod.yml里面配了Nginx反代、Next.js容器、PostgreSQL容器三个服务数据卷持久化也做了。直接在自己的服务器上执行docker compose -f docker-compose.prod.yml up -d --build就能跑起来。如果服务器内存只有1G记得给Node容器加NODE_OPTIONS--max-old-space-size512这样的限制不然构建时经常被OOM杀掉这算是新手最容易踩的坑。4.3 谈谈构建性能的一些经验t3code这个模板包含的依赖不算少Next.js生产构建大概需要2分多钟。第一次跑如果发现构建机器挂了先检查内存。我遇到过一台512M内存的机器跑Next.js build直接OOM崩溃加了swap之后勉强能过。提升构建速度的另外一个思路是开启tRPC的babel插件替代方案——直接用SWC这个Next.js 14默认就是不需要额外配置。模板里没有引入任何多余的babel插件这一点对于构建时间的控制相当重要。最后再提一下环境变量管理的经验。t3code把环境变量都收在.env里但如果你用了Vercel或者GitHub Actions这样的平台不要把密钥直接提交到Git仓库的vercel.json里。建议用平台的Secret管理功能或类似方式独立存储部署时注入进容器环境变量这样代码仓库里就算别人拿到源码也拿不到线上数据库的真实密钥。5. 常见问题与排查技巧我踩过的坑你可能也会遇到5.1 tRPC调用404或者路由不生效这个问题最容易出现在刚clone完t3code后我自己也遇到过。查的时候别急着改代码先确认root.ts里的appRouter是否包含了新加的router以及src/app/api/trpc/[trpc]/route.ts这个文件是否还保留着默认配置。某些版本的脚手架会生成一个旧的API入口文件跟App Router的路径冲突导致tRPC路由没有注册到HTTP Handler上。出现404时先看网络面板里实际请求的URL是否跟tRPC Route配置一致再看route.ts有没有被意外删除。5.2 Prisma的Schema变更之后前端类型没更新改了schema.prisma之后光跑db:push还不够必须再跑一次pnpm db:generate。这个命令会重新生成node_modules/.prisma/client下面的类型声明。很多朋友改了字段名之后编辑器里前端代码没报错以为类型没问题结果一启动就报无法解析十有八九就是忘了跑generate。另外如果你开了多个终端窗口新类型生成后编辑器可能需要重新加载TypeScript服务才会感知到。VS Code里按下CtrlShiftP执行“TypeScript: Restart TS Server”就能解决这个操作我每个月都得用好几次。5.3 NextAuth的Session在tRPC里拿不到用户信息这个坑比较隐蔽。t3code的tRPC上下文创建是在createTRPCContext函数里模板代码里已经用auth()拿了Session。如果自定义调试的时候发现ctx.session是null先确认两件事一是浏览器里有没有正确的cookie二是NextAuth的NEXTAUTH_SECRET有没有配。Node环境里Session拿不到多数是因为Secret不一致导致JWT验证失败session直接被视为无效。还有一点需要记住protectedProcedure依赖的是ctx.session.user存在如果你的NextAuth配置里没有设置callbacks.session把用户ID塞进去那么Prisma查询的时候ctx.session.user.id会是undefined这个时候数据操作可能报错但报错位置并不直观查起来很容易怀疑到数据库头上。5.4 样式失效或Tailwind的类名不生成Tailwind JIT模式扫描的是模板文件里出现过的类名。如果你的类名是通过字符串拼接或者外层变量动态生成的比如const cls bg- colorTailwind在编译时就抓不到这个类名页面样式就会莫名其妙消失。解决方案也很简单——把完整类名写出来不要拼接。这个属于Tailwind使用的老生常谈但确实很多人被卡过。5.5 线上数据库连接数被打爆PostgreSQL默认连接数上限是100Prisma的连接池默认大小跟连接字符串里的参数有关。t3code的模板里DATABASE_URL没有配连接池参数如果同一时间并发比较高很容易撞到连接数上限。在生产环境建议在连接串后面加上?connection_limit5pool_timeout10这样来限制连接池或者在prisma.ts里显式声明pool配置。不要盲目调大Prisma连接池数据库的承受能力总是有限的过大的池子反而会导致连接风暴。6. 从一个模板到一个习惯我对t3code的持续维护心得t3code这个项目我从最早的单仓库模板做到现在最大的体会是技术栈本身只是表象真正有价值的是背后那一整套关于“如何组织全栈TypeScript项目”的认知。最开始我也觉得tRPC只是个RPC工具用久了才发现它逼着你把前后端的数据边界想清楚。哪个数据是服务端拿的哪个数据是客户端本地缓存的哪个状态需要实时同步这些在传统REST下常常被URL模糊掉的问题在tRPC里反而会因为每个API都是一个函数而变得好梳理。再加上Prisma的类型生成和Next.js的渲染模型整个项目的数据流是透明的从数据库表结构到前端页面显示你完全可以在一张图里画清楚。还有一点心得是关于“模板应该厚到什么程度”的。t3code之所以带了登录、数据库、错误处理、SEO这些基础设施是因为绝大多数业务项目根本不需要把这些东西再从头实现一遍。你核心的竞争力一定在业务逻辑里不在鉴权代码里。快速起一个带完整基础设施的项目把时间腾出来做业务是我觉得这个模板存在的最大价值。最后一个小建议不管你用什么模板起步一定花半天时间把模板里每个文件都读一遍。t3code里的代码注释写得比较详细但框架更新迭代很快比如Next.js每个大版本都有一些API变动如果你不主动跟进半年后再回头跑这个项目大概率会碰到一堆版本兼容问题。我的经验是给项目固定一个技术栈版本——t3code在根目录的package.json里锁了依赖版本团队协作时避免“谁能跑谁不能跑”的魔幻局面。你如果自己fork了一套记得跟着做版本锁定否则团队成员装依赖的时候很容易装出各不相同的结果来。 
长河君 · 2026/10/27 16:04:43 · 阅读 1.2k t3code：基于T3 Stack的全栈TypeScript类型安全开发模板
1. t3code到底是什么先聊清楚这个项目要解决的问题我最初看到“t3code”这个名字的时候第一反应是它跟T3 Stack有关。实际接触下来这个名字确实不是一个独立框架而是一套围绕TypeScript全栈开发的最佳实践集合。更准确地说t3code是我一直在维护的一个基于T3 Stack思想的开源模板项目它的核心目标就一句话让我们能用TypeScript从数据库到前端UI全部打通全程享受类型提示和编译期检查尽量减少“改了后端类型导致前端不知不觉就崩了”这类破事。先解释一下T3这个名词避免有朋友听得一头雾水。T3 TypeScript Tailwind CSS tRPC。这套组合在2023年到2024年间热度涨得很快原因也不复杂它把“全栈类型安全”这件事做到了一个非常舒服的平衡点。你写数据库查询拿到的是类型明确的结果你调API请求参数和响应结构的类型自动从前端标注出来你改一个字段名TypeScript编译器会瞬间告诉你哪里忘了同步。这个体验一旦适应了再回去写传统的前后端分离项目多少会觉得有些钝。t3code这套模板解决了什么问题呢它的定位不是从零教你“Hello World”而是提供一个在生产环境真正能直接用的起步结构。我见过太多脚手架项目GitHub星星倒是不少真正clone下来跑起来才发现缺东少西没有鉴权、没有数据库迁移脚本、没有错误处理中间件、没有SEO配置、没有通用的响应包装结构。等你把这一堆东西补完热情基本也耗光了。用t3code上手的话你的项目一开始就有这些东西Next.js 14的App Router结构、tRPC路由和API层、Prisma ORM与数据库迁移配置、NextAuth的GitHub和Google登录、Tailwind的原子化样式体系外加一套我已经在真实业务里跑过几个月的基础目录规范和错误处理方案。你可以直接在这个基础上开发自己的业务代码不用再重复造轮子。这套东西适合谁两类人最合适一类是受够了前后端联调时“你等一下我改个字段”的团队想试试全栈TypeScript的开发节奏另一类是正在学Next.js和tRPC需要一个相对完整、代码质量说得过去的项目作为参照的开发者。如果你本来就是传统Spring Boot加Vue的忠实用户那t3code可能对你吸引力不大因为整套技术体系的思路跟Java后端那一套差别还是比较远的。2. 核心设计思路为什么选择TypeScript全栈这条路2.1 类型安全到底“安全”在哪里很多朋友一听到“类型安全”就觉得是噱头觉得写好测试就完事了。我自己以前也这样想直到在一次项目迭代里真的被坑惨了。当时后端返回的user.createdAt字段从字符串改成了时间戳数字前端那个页面用来做日期排序结果排序逻辑全部失效而且是运行时才暴露。这种问题在传统前后端分离架构里太常见了接口的契约靠文档——文档一过期契约就散了错误只能靠跑起来才知道。t3code这套方案不搞文档同步因为根本不需要文档。数据模型定义在Prisma Schema里Prisma会根据这个Schema生成完整的TypeScript类型。tRPC把后端路由的函数输入输出类型直接暴露给前端Next.js组件里调api.user.getById.useQuery()返回的data.username如果字段写错了编辑器里直接飘红根本编译不过。也就是说出现我之前说的那种日期字段类型变更的问题时在前端代码编译的这一瞬间就会被发现根本不会带上线。这背后的原理说穿了也很朴素TypeScript是结构类型系统两个对象只要结构形状匹配类型就兼容。tRPC利用泛型把后端路由的输入输出类型信息一路传递到前端调用端。Prisma也一样数据库表结构通过代码生成器变成TS类型。这三层叠加起来数据库、API、页面UI全部被同一张类型网络覆盖住数据流走到哪一步类型检查就检查到哪一步。2.2 技术选型的取与舍T3 Stack之所以把tRPC放进来而不是选REST或GraphQL有一个很实际的理由tRPC简单。GraphQL确实强大但GraphQL的Schema定义、Resolver编写、客户端缓存策略、codegen配置这一套玩下来学习成本相当可观很多中小项目根本不需要那么强的灵活性。REST也还行但写接口路径、处理参数校验、维护跨端类型明显更费劲。tRPC的做法是直接基于TypeScript函数后端写一个函数前端调用这个函数不需要URL构造不需要手写请求逻辑参数和返回值的类型自动同步。当然tRPC也不是没有代价。它跟Next.js的Server Components配合时需要处理好服务端调用和客户端调用的边界这个稍后我会在实操部分详细演示。另外如果你的前端客户端不是TypeScript项目比如小程序用纯JavaScript那tRPC那套类型推导就发挥不出威力了。好在t3code的目标场景就是全TypeScript所以基本不存在这个问题。数据库层选了Prisma而不是TypeORM或者Drizzle原因也简单Prisma的Schema语法清晰迁移工具成熟类型生成直接集成在workflow里。写一次Schema建表脚本、TS类型、CRUD操作全部都有了内置的类型安全做得是整个Node生态里最好的那一档。对于我这种不喜欢反复切换上下文的人来说这个体验流畅得就像在IDE里有一个隐形的翻译助手。样式层选Tailwind CSS就不用多说理由了原子化CSS在组件化开发中的效率优势当年撸过一遍就能体会到。特别是在t3code这种组件多、迭代快的场景里不用为了一个按钮写一堆CSS类名然后反复切文件inline的样式工具类直观又高效。2.3 目录结构的一次到位t3code的项目结构是经过几轮实战调优的不是脚手架默认生成的那套原始布局。核心思路是按模块划分而不是按技术类型划分。你可以理解成“这个功能的所有代码放同一个文件夹”而不是“所有的组件放一个文件夹所有的API放另一个文件夹”。比如用户模块在src/server/api/routers/user.ts里配置tRPC路由src/server/db/schema.prisma里定义用户表前端组件文件里直接调用useQuery来取数据。增删改查的过程中不用去十几层深的目录里找文件所有关联代码都围绕功能模块就近摆放。这样做最大的好处是代码交接成本低——新同事看项目顺着路由文件的引用往上翻很容易理解业务逻辑是怎么串起来的。3. 实操步骤从clone t3code到跑通第一个业务接口3.1 环境准备与前五分钟跑通这个模板要求Node.js 18以上包管理器推荐pnpm因为pnpm的依赖安装速度比npm快而且磁盘占用小很多。第一步clone项目后首先要做的事情是安装依赖并把环境变量配好。模板里有一个.env.example文件复制一份改成.env然后填入两个关键配置数据库连接字符串和一个随机生成的安全密钥。git clone https://github.com/yourname/t3code.git my-project cd my-project pnpm install cp .env.example .env我这里以PostgreSQL为例连接字符串长这样DATABASE_URLpostgresql://postgres:postgreslocalhost:5432/t3code?schemapublic NEXTAUTH_SECRETyour-random-secret-key NEXTAUTH_URLhttp://localhost:3000安全密钥可以直接用openssl rand -base64 32生成别随便输入一串短密码完事那是很多朋友上线后被攻击的根源。依赖装好后跑一次数据库迁移pnpm db:push pnpm db:generate第一条命令是把Prisma Schema同步到数据库建表建约束第二条是重新生成Prisma Client的类型代码。跑完之后pnpm dev启动开发服务器浏览器打开http://localhost:3000能看到首页样式跑起来说明模板已经活了。3.2 从零添加一个“文章”模块的完整流程好演示一下真正上手之后怎么做业务开发。这里用最简单的“文章”功能为例一篇文章有标题、正文、作者和发布时间。第一步改Prisma Schema。打开src/server/db/schema.prisma在User模型下方新增一个模型model Post { id String id default(cuid()) title String content String author User relation(fields: [authorId], references: [id]) authorId String createdAt DateTime default(now()) updatedAt DateTime updatedAt }代码写好后回到终端跑pnpm db:push完成表结构同步。第二步写tRPC路由。打开src/server/api/routers/post.ts创建一个新的tRPC routerimport { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure.query(async ({ ctx }) { const posts await ctx.db.post.findMany({ include: { author: { select: { name: true } } }, orderBy: { createdAt: desc }, }); return posts; }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1), })) .mutation(async ({ ctx, input }) { const post await ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); return post; }), });有几个细节我想特别说一下。列表接口我用了publicProcedure因为是公告类内容游客也能看创建文章用了protectedProcedure这个模板自带登录校验逻辑未登录直接抛错不用你自己写鉴权代码。入参校验用的是Zodz.string().min(1)的意思是必须是非空字符串如果前端传了个空标题过来tRPC返回的报错信息会包含精确的校验提示。第三步把路由注册到根路由。打开src/server/api/root.ts把postRouter挂载到appRouter上export const appRouter createTRPCRouter({ post: postRouter, user: userRouter, // ...其他路由 });第四步写前端页面。在App Router的src/app/posts/page.tsx里use client; import { api } from ~/trpc/react; export default function PostsPage() { const { data: posts, isLoading } api.post.list.useQuery(); const utils api.useUtils(); const createPost api.post.create.useMutation({ onSuccess: () utils.post.list.invalidate(), }); if (isLoading) return div加载中.../div; return ( div h1文章列表/h1 {posts?.map((post) ( div key{post.id} h2{post.title}/h2 p{post.content}/p span{post.author.name}/span /div ))} button onClick{() createPost.mutate({ title: 测试标题, content: 测试正文, }) } 发布文章 /button /div ); }注意“use client”这行声明因为tRPC的useQuery是Hooks用法必须在客户端组件里使用。如果这个页面同时需要服务端渲染的SEO效果可以参考t3code模板里专门做的src/app/posts/page.server.tsx和page.client.tsx组合模式核心思路是页面主体用客户端组件调HooksSEO内容放在服务端组件里。最后也是很容易被忽略的一步在src/server/db/schema.prisma里把Post模型跟User模型的posts字段关联起来model User { id String id default(cuid()) name String? posts Post[] }这样整套流程就跑通了。浏览器里点击发布按钮新文章立即写入数据库页面列表自动刷新全程类型安全。字段名拼错、参数类型不匹配都是编译时直接报错连跑起来这个步骤都省了。3.3 给新模块加权限和错误处理一个写进的模块如果没有权限控制基本等于裸奔。t3code模板默认提供的protectedProcedure只能保证用户登录但要实现“只有作者本人能编辑自己的文章”还得靠自定义中间件。t3code里可以用tRPC的middleware机制实现import { TRPCError } from trpc/server; const canEditPost t.middleware(async ({ ctx, input, next }) { const { id } input as { id: string }; const post await ctx.db.post.findUnique({ where: { id } }); if (!post || post.authorId ! ctx.session?.user?.id) { throw new TRPCError({ code: FORBIDDEN }); } return next({ ctx: { post } }); }); export const protectedPostProcedure protectedProcedure.use(canEditPost);这个中间件的思路不太复杂拿到文章ID之后先把文章查出来判断作者是不是当前登录用户是就继续走不是就抛出403错误。它的意义在于把鉴权逻辑收拢到路由层业务方法里不掺杂权限判断代码后面要加“管理员也能编辑别人文章”的规则时只需要在这个中间件里加一个分支判断。错误处理方面t3code里我封装了一个统一错误体任何路由抛出的异常都被src/server/api/trpc.ts里的onError钩子捕获按INTERNAL_SERVER_ERROR和UNAUTHORIZED等不同code返回不同提示。这么做的好处是前端拿到的错误信息结构永远是一致的做全局toast提示时非常顺手。4. 部署与上线从本地到生产环境的关键配置4.1 用Docker把后端跑起来t3code里我写了一个可以直接用的docker-compose.yml开发环境下它会启动一个PostgreSQL容器和可选的MinIO对象存储容器。很多人本地开发的时候数据库用的是SQLite上线前再切换成PostgreSQL这种做法其实隐患不小。SQLite的锁机制和并发行为跟正式环境完全不同排查起来浪费的时间远比一开始就配好数据库要多。我的做法是从第一天就用PostgreSQL在Docker里跑开发环境和生产环境的环境变量保持一致。docker compose up -d postgres跑起来之后再看Prisma的迁移。模板里的schema文件已经定义好了所有模型直接用pnpm db:push同步即可。真要上线的话推荐使用prisma migrate deploy它只执行未应用过的迁移文件不会重跑已经执行过的脚本。4.2 部署到Vercel或自建服务器Next.js项目部署到Vercel基本是零配置的GitHub上连好仓库选择根目录Vercel自动识别Next.js框架环境变量填上即可。但我需要提醒一个问题如果你用了tRPC的服务端渲染查询Vercel的Serverless环境里函数冷启动的延迟会变得更量级显眼。白屏等待的一秒多钟有时候会直接影响用户体验尤其对To B系统来说体感差别还挺明显的。我的建议是部署目标如果是国内用户群更稳定的选择是自建一台服务器用Nginx加PM2或者Docker Compose跑。t3code模板里也带了一份生产环境的docker-compose.prod.yml里面配了Nginx反代、Next.js容器、PostgreSQL容器三个服务数据卷持久化也做了。直接在自己的服务器上执行docker compose -f docker-compose.prod.yml up -d --build就能跑起来。如果服务器内存只有1G记得给Node容器加NODE_OPTIONS--max-old-space-size512这样的限制不然构建时经常被OOM杀掉这算是新手最容易踩的坑。4.3 谈谈构建性能的一些经验t3code这个模板包含的依赖不算少Next.js生产构建大概需要2分多钟。第一次跑如果发现构建机器挂了先检查内存。我遇到过一台512M内存的机器跑Next.js build直接OOM崩溃加了swap之后勉强能过。提升构建速度的另外一个思路是开启tRPC的babel插件替代方案——直接用SWC这个Next.js 14默认就是不需要额外配置。模板里没有引入任何多余的babel插件这一点对于构建时间的控制相当重要。最后再提一下环境变量管理的经验。t3code把环境变量都收在.env里但如果你用了Vercel或者GitHub Actions这样的平台不要把密钥直接提交到Git仓库的vercel.json里。建议用平台的Secret管理功能或类似方式独立存储部署时注入进容器环境变量这样代码仓库里就算别人拿到源码也拿不到线上数据库的真实密钥。5. 常见问题与排查技巧我踩过的坑你可能也会遇到5.1 tRPC调用404或者路由不生效这个问题最容易出现在刚clone完t3code后我自己也遇到过。查的时候别急着改代码先确认root.ts里的appRouter是否包含了新加的router以及src/app/api/trpc/[trpc]/route.ts这个文件是否还保留着默认配置。某些版本的脚手架会生成一个旧的API入口文件跟App Router的路径冲突导致tRPC路由没有注册到HTTP Handler上。出现404时先看网络面板里实际请求的URL是否跟tRPC Route配置一致再看route.ts有没有被意外删除。5.2 Prisma的Schema变更之后前端类型没更新改了schema.prisma之后光跑db:push还不够必须再跑一次pnpm db:generate。这个命令会重新生成node_modules/.prisma/client下面的类型声明。很多朋友改了字段名之后编辑器里前端代码没报错以为类型没问题结果一启动就报无法解析十有八九就是忘了跑generate。另外如果你开了多个终端窗口新类型生成后编辑器可能需要重新加载TypeScript服务才会感知到。VS Code里按下CtrlShiftP执行“TypeScript: Restart TS Server”就能解决这个操作我每个月都得用好几次。5.3 NextAuth的Session在tRPC里拿不到用户信息这个坑比较隐蔽。t3code的tRPC上下文创建是在createTRPCContext函数里模板代码里已经用auth()拿了Session。如果自定义调试的时候发现ctx.session是null先确认两件事一是浏览器里有没有正确的cookie二是NextAuth的NEXTAUTH_SECRET有没有配。Node环境里Session拿不到多数是因为Secret不一致导致JWT验证失败session直接被视为无效。还有一点需要记住protectedProcedure依赖的是ctx.session.user存在如果你的NextAuth配置里没有设置callbacks.session把用户ID塞进去那么Prisma查询的时候ctx.session.user.id会是undefined这个时候数据操作可能报错但报错位置并不直观查起来很容易怀疑到数据库头上。5.4 样式失效或Tailwind的类名不生成Tailwind JIT模式扫描的是模板文件里出现过的类名。如果你的类名是通过字符串拼接或者外层变量动态生成的比如const cls bg- colorTailwind在编译时就抓不到这个类名页面样式就会莫名其妙消失。解决方案也很简单——把完整类名写出来不要拼接。这个属于Tailwind使用的老生常谈但确实很多人被卡过。5.5 线上数据库连接数被打爆PostgreSQL默认连接数上限是100Prisma的连接池默认大小跟连接字符串里的参数有关。t3code的模板里DATABASE_URL没有配连接池参数如果同一时间并发比较高很容易撞到连接数上限。在生产环境建议在连接串后面加上?connection_limit5pool_timeout10这样来限制连接池或者在prisma.ts里显式声明pool配置。不要盲目调大Prisma连接池数据库的承受能力总是有限的过大的池子反而会导致连接风暴。6. 从一个模板到一个习惯我对t3code的持续维护心得t3code这个项目我从最早的单仓库模板做到现在最大的体会是技术栈本身只是表象真正有价值的是背后那一整套关于“如何组织全栈TypeScript项目”的认知。最开始我也觉得tRPC只是个RPC工具用久了才发现它逼着你把前后端的数据边界想清楚。哪个数据是服务端拿的哪个数据是客户端本地缓存的哪个状态需要实时同步这些在传统REST下常常被URL模糊掉的问题在tRPC里反而会因为每个API都是一个函数而变得好梳理。再加上Prisma的类型生成和Next.js的渲染模型整个项目的数据流是透明的从数据库表结构到前端页面显示你完全可以在一张图里画清楚。还有一点心得是关于“模板应该厚到什么程度”的。t3code之所以带了登录、数据库、错误处理、SEO这些基础设施是因为绝大多数业务项目根本不需要把这些东西再从头实现一遍。你核心的竞争力一定在业务逻辑里不在鉴权代码里。快速起一个带完整基础设施的项目把时间腾出来做业务是我觉得这个模板存在的最大价值。最后一个小建议不管你用什么模板起步一定花半天时间把模板里每个文件都读一遍。t3code里的代码注释写得比较详细但框架更新迭代很快比如Next.js每个大版本都有一些API变动如果你不主动跟进半年后再回头跑这个项目大概率会碰到一堆版本兼容问题。我的经验是给项目固定一个技术栈版本——t3code在根目录的package.json里锁了依赖版本团队协作时避免“谁能跑谁不能跑”的魔幻局面。你如果自己fork了一套记得跟着做版本锁定否则团队成员装依赖的时候很容易装出各不相同的结果来。