1. 为什么我会折腾出t3code：全栈项目启动的重复劳动
如果你跟我一样，平时不仅要写业务代码，还要负责项目从零到上线的整个链路，那你一定有过这样的体验：每次启动一个新项目，最耗时间的并不是业务逻辑本身，而是那些“基础设施”性质的重复工作——接入数据库、搭认证体系、配环境变量、写API层、设计代理转发、部署流程……这一套做完，往往一两天就没了，还没碰一行真正的业务代码。t3code就是在这样的背景下诞生的：它是一套以T3技术栈为核心的全栈项目脚手架，把“能跑通”这件事前置解决掉，让我和新加入的同事拿到代码就能直接进入业务开发。
1.1 启动新项目时，真正让人头疼的是什么
很多团队的起步方式其实很原始：找一个旧的代码仓库，复制过来，改改名字和数据库连接串，然后把旧功能删掉。这种方法看起来快，但后患无穷——项目里残留着上一代业务的逻辑、过期的依赖、莫名其妙的样式覆盖，甚至还有前任开发者留下的私有密钥。我见过不止一个项目，上线三个月后才发现线上环境还在读着一个早已废弃的数据库账号。
另一种做法是手动搭建，用脚手架工具生成基础工程，再逐项加东西进去。这条路的问题是步骤太多、顺序错了就容易连环报错：先装了ORM，后初始化了数据库，结果迁移脚本里漏了字段类型；认证库配置好了，但中间件路径写错，结果每个请求都多走一层鉴权逻辑。重复做上两三次之后，你会发现这些工作完全值得固化下来，变成一套“开箱即用”的起点。t3code要解决的，就是这个问题。
1.2 T3技术栈为何能把这些痛点一次包掉
T3 Stack并不是一个新的编程语言或者框架，它是一组在各自领域里以“类型安全、开发体验好”著称的工具的组合，核心成员包括Next.js、TypeScript、Prisma和tRPC，再搭配Tailwind CSS处理界面样式。这套组合的逻辑很清晰：Next.js负责页面渲染和API路由的统一入口，TypeScript给全链路的变量做静态约束，Prisma把数据库表变成类型安全的查询模型，tRPC则让前端调用后端接口时不需要手写API定义、不需要维护接口文档。
我最开始接触这套组合时有个疑问：把这么多东西装到同一个项目里，学习成本和维护成本是不是太高了？实际用下来发现正好相反——它们之间是有机配合的。Prisma生成的类型可以直接在tRPC的Router里使用，tRPC的响应类型会被前端useQuery自动推断出来，整条链路上几乎没有“手动同步类型”的动作。写接口的时候改了一个字段，前端的类型检查会立刻告诉你哪里引用了旧结构，这种体验在传统前后端分离项目里很难实现。
1.3 t3code的定位不是什么“新框架”
必须说清楚一点，t3code不是一个试图替代Next.js或Prisma的上层框架，它更像是一套“已经搭好、能直接跑、结构清晰”的起点模板。它限制了一些约定，比如路由必须集中在特定目录、数据库统一走Prisma、接口统一走tRPC，但对业务代码没有任何侵入。你可以在里面按自己的需求加任何库，也可以把其中某个模块替换成你更熟悉的实现。模板最怕的是“锁死”，t3code在这一点上保持了克制。
我给自己定了一条规则：凡是和具体业务无关、但所有项目都要用到的能力，才放进t3code；凡是某个业务特有的逻辑，一律放到项目自己的代码里。认证、用户模型、基础权限、数据库连接管理、API层封装、错误处理、环境变量加载，这些是“通用设施”；推荐算法、订单流程、消息推送，这些是“业务逻辑”。边界清晰之后，模板的复用率才会高，不会变成一个大杂烩。
2. 目录结构、数据库和认证：t3code的三个关键选择
在动手写代码之前，最值得花时间的是想清楚目录怎么分、数据库怎么建模、认证怎么做。这三个选择决定了后面几个月写代码的体验。
2.1 目录结构：把基础设施和业务页面从物理上分开
t3code的目录结构遵循一个简单的原则：让代码的归属一目了然。凡是和Next.js路由相关的文件都放在src/app里，凡是提供数据能力的独立模块放在src/server里，凡是连接前后端的类型与工具放在src/trpc里。这个结构并不是T3 Stack官方强制要求的，但经过几个项目的验证，它能让新人最快找到自己该改的地方。
t3code/ ├── prisma/ │ ├── schema.prisma # 数据模型定义 │ └── migrations/ # 数据库迁移记录 ├── src/ │ ├── app/ │ │ ├── (auth)/ # 登录注册相关页面 │ │ │ ├── login/ │ │ │ └── register/ │ │ ├── (dashboard)/ # 需要登录才能访问的页面 │ │ ├── api/ # Next.js原生API路由，非tRPC的补充入口 │ │ └── layout.tsx # 全局布局 │ ├── server/ │ │ ├── db.ts # Prisma客户端实例 │ │ ├── auth.ts # 认证配置 │ │ └── api/ │ │ ├── root.ts # tRPC根Router │ │ └── routers/ # 各业务域Router │ ├── trpc/ │ │ ├── server.ts # 服务端tRPC初始化 │ │ ├── client.ts # 客户端tRPC实例 │ │ └── caller.ts # 服务端直接调用RPC │ └── styles/ │ └── globals.css ├── public/ ├── .env.example # 环境变量示例 ├── .env # 本地环境变量（不入库） ├── Dockerfile └── next.config.mjs第一次看到这个结构的人可能会问：src/server和src/app/api是不是重复了？其实不重复。tRPC承担的是业务接口的绝大部分工作，因为它天然支持类型推导和参数校验；而app/api只放那些没法用tRPC表达或需要外部回调的接口，比如支付平台的Webhook回调。把这两类接口分开，能在排查问题时快速判断请求走的是哪条链路。
2.2 数据库层为什么最终选了Prisma
在t3code里，数据库访问层我选了Prisma，而不是直接写SQL或者用其他ORM。原因有三条：第一，Prisma Schema的声明式模型读起来非常直观，非后端专业的协作成员也能看懂表结构；第二，迁移流程是工程化的——修改Schema后执行prisma migrate dev，会生成带时间戳的SQL迁移文件，每次结构变更都可追溯、可回滚；第三，Prisma生成的Client自带完整类型，查询结果的结构在编码阶段就能被TypeScript检查到。
使用过程中有几个体验值得单独说。Prisma的嵌套查询能力很强，创建一条记录时能同时创建它的关联记录，比如注册用户时同时建立默认项目和会话信息，这在一个事务里就能完成。但要注意，嵌套写入虽然方便，性能上并不是万能的——如果关联数据量很大，逐条写入会导致数据库压力上升。我在t3code里对“创建”类操作使用了嵌套写入，对“批量更新”类操作则拆成单条处理，这个取舍后面会细说。
另外一个细节是Prisma Client的实例管理。在Next.js开发模式下，每次保存代码都会触发热更新，如果不断新建PrismaClient实例，很快会跑满数据库连接。t3code里的标准做法是用globalThis缓存实例，在开发环境复用同一个实例：
import { PrismaClient } from "@prisma/client"; const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient }; export const db = globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV !== "production") { globalForPrisma.prisma = db; }这套代码看起来简单，但它避免了“连接数爆炸”这个新手最容易踩的坑。
2.3 认证模块的取舍：NextAuth还是自研Session
认证是每个业务系统绕不开的模块，难在方案众多且坑深。t3code默认使用NextAuth（新版为Auth.js）的Credentials登录方式加JWT会话，理由是它足够通用，且能覆盖“邮箱密码登录”这种最常见场景。Credentials方式并不复杂：用户在登录页提交账号密码，服务端校验后签发一个JWT，后续请求通过中间件验证token里携带的用户信息。
考虑到有的项目会走企业微信、GitHub或第三方OAuth登录，我也在t3code里保留了扩展点。具体的做法是在auth.ts里配置providers数组，把环境变量和回调地址准备好，换一个提供商只需要改配置。需要注意的一点是，第三方登录的session持久化策略和Credentials模式不同，如果你需要统计用户在线状态，建议在数据库中记录session记录，而不是完全依赖JWT的无状态特性。
我同样测试过自研Session的实现，用数据库表存sessionId，Redis做缓存。好处是可控性高，坏处是代码量翻倍，而且一旦并发量上来，session表的读写会成为新的瓶颈。对于绝大多数中小型项目，NextAuth的JWT模式已经足够，等到真正需要强制下线、多端互踢这类能力时再去改造，成本也是可控的。
3. 搭建t3code的完整过程：从环境准备到第一个接口联调
这一部分我会把t3code从空目录到跑通一个完整业务路径的过程记录下来，包含所有关键命令和容易报错的环节。如果你只是想复制使用这个模板，完全可以照着执行。
3.1 环境准备：版本不一致会带来很多诡异问题
先说环境。Node.js版本固定在20.x以上，因为Next.js 14和Prisma对旧版本的Node支持不够稳定；包管理器我用的pnpm，它与Next.js的monorepo场景配合更好，安装速度和磁盘占用也比npm有明显优势。如果你之前一直用npm，切到pnpm后别急着删node_modules，最常见的问题是lockfile格式不同导致依赖版本漂移，建议把旧依赖目录清理干净再安装。
初始化完成后，第一步永远是配置环境变量。t3code把项目的环境变量分成三类：本地开发变量（.env）、生产环境变量（部署平台或服务器上设置）、公共可暴露变量（NEXT_PUBLIC_前缀）。一个易错点是，Next.js只会在构建时把NEXT_PUBLIC_开头的变量打进前端代码，如果你把数据库地址或密钥错误地命名为NEXT_PUBLIC_DATABASE_URL，等于把密码发给了所有访问页面的人。我在t3code的.env.example里对每类变量都写了注释，降低误用的概率。
3.2 数据库建模：从需求到Prisma Schema
数据库建模是所有功能的根基。t3code内置了一套最精简的通用模型：用户表、账号表、会话表和项目表。用户表存基本资料，账号表支持多个登录源绑定，项目表是一个示例业务域，用来演示如何做一对多关系的查询。这套模型可以覆盖“注册登录后管理自己资源”的标准流程。
model User { id String @id @default(cuid()) name String? email String @unique emailVerified DateTime? image String? projects Project[] accounts Account[] sessions Session[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Account { id String @id @default(cuid()) userId String type String provider String providerAccountId String refresh_token String? @db.Text access_token String? @db.Text expires_at Int? token_type String? scope String? user User @relation(fields: [userId], references: [id], onDelete: Cascade) @@unique([provider, providerAccountId]) } model Project { id String @id @default(cuid()) name String slug String @unique ownerId String owner User @relation(fields: [ownerId], references: [id], onDelete: Cascade) createdAt DateTime @default(now()) }写完Schema后，执行npx prisma migrate dev --name init，它会帮你生成迁移文件并且同步到数据库。这个命令在首次执行时可能会卡住，大多是网络问题导致Prisma引擎下载失败。遇到这种情况，直接设置环境变量PRISMA_ENGINES_MIRROR指向国内镜像即可解决。
3.3 用tRPC定义接口：Router和Procedure的含义
t3code的接口层统一走tRPC。很多人第一次看到tRPC会觉得它改变了写接口的方式，其实它的核心概念拆开看非常简单：Router是接口的集合，Procedure是单个接口，它分为query（查询）和mutation（写入）两类，再用middleware做公共逻辑的复用。
我以项目管理的接口来举例。创建项目需要登录权限，并且要校验输入参数是否符合规范，对应的代码是：
import { z } from "zod"; import { createTRPCRouter, protectedProcedure } from "../trpc"; export const projectRouter = createTRPCRouter({ create: protectedProcedure .input( z.object({ name: z.string().min(2, "项目名称至少2个字符"), slug: z.string().regex(/^[a-z0-9-]+$/, "slug只能包含小写字母、数字和中划线"), }) ) .mutation(async ({ ctx, input }) => { return ctx.db.project.create({ data: { name: input.name, slug: input.slug, ownerId: ctx.user.id, }, }); }), list: protectedProcedure.query(({ ctx }) => { return ctx.db.project.findMany({ where: { ownerId: ctx.user.id }, orderBy: { createdAt: "desc" }, }); }), });在这里，protectedProcedure是一个通过中间件注入了当前登录用户的Procedure，它背后做的是“读取JWT -> 查询数据库 -> 把用户对象挂到ctx上”这三个动作。如果令牌无效，接口会直接抛出UNAUTHORIZED错误，业务代码里不需要再重复写一堆权限判断。
3.4 前端调用接口与类型推导的联动
tRPC最让人舒服的地方，是前后端类型完全联动。在组件里调用接口时，返回值会被自动推断出来，不需要额外定义接口返回数据的类型。
"use client"; import { api } from "~/trpc/client"; export function ProjectList() { const { data, isLoading } = api.project.list.useQuery(); if (isLoading) return <p>加载中...</p>; return ( <ul> {data?.map((project) => ( <li key={project.id}> <span>{project.name}</span> <code>{project.slug}</code> </li> ))} </ul> ); }这段代码里没有出现任何fetch或者axios，也没有手动声明Project类型，但data.map里的project已经知道有name和slug字段，且slug是字符串类型。这在开发体验上的提升非常明显——以前后端改了返回结构，前端要等到运行时才能发现；现在后端一改，前端的TypeScript编译器当场就报错，问题在写代码的阶段就被拦截了。
当然，前端项目里也存在一些不需要交给tRPC管理的第三方接口请求，t3code同样预留了fetch的封装工具，并没有把所有接口都强制塞进tRPC。
4. 部署上线与性能调优：t3code在生产环境的实测记录
模板本地能跑通只是第一步，真正考验人的是部署。我在部署t3code时选择了自建服务器方案，没有直接用托管服务，因为这样可以更好地控制数据库连接、日志和进程管理。
4.1 自部署方案：Nginx反代加PM2进程管理
t3code的生产运行环境是一台Ubuntu服务器，搭配Nginx做反向代理，PM2托管Node进程。构建流程是：代码推送后，在服务器上拉取最新分支，执行pnpm install和pnpm build，再通过pm2 reload实现无间断更新。Nginx的配置很简单，核心只是把443端口的HTTPS流量转发到Node进程的3000端口。
部署过程中最容易出问题的是环境变量。Next.js的构建过程会读取服务端环境变量，如果你在ServerActions或某些静态生成逻辑里用到数据库连接，而这些变量在构建机（比如CI）上不存在，构建会果断失败。我在实际发布时遇到过一次：CI环境里的.env没有DATABASE_URL，但项目在构建时预渲染了某些涉及数据库的页面，结果整个流水线挂掉。解决办法是，在构建命令前显式加载生产环境变量文件，或者把需要数据库数据的页面改成动态渲染。
4.2 数据库连接数与Prisma的连接池策略
上线第一天，t3code遇到了一个比较典型的性能问题：用户量上来后，数据库CPU飙升，查询延迟变大。查了一圈才发现，PrismaClient默认的连接池上限是10个，而PM2开启了4个进程，每个进程里实例各自维护连接池，叠加起来就是40个连接。MySQL和PostgreSQL默认的max_connections只有100，项目里如果还有其他后台任务也在使用连接，很快就把连接占满了。
解决办法分两层：应用层，把Prisma的连接池上限调低一些，比如connection_limit=5；数据库层，适当提高max_connections，同时给后台脚本单独配置数据库账号，避免共用连接池。调整之后，CPU使用率明显回落。这个优化动作很小，但在上线初期容易被忽略，值得记录在部署清单里。
4.3 包体积与加载速度的实测优化
Next.js应用给自己埋了一个性能地雷，就是客户端包体积容易膨胀。t3code的首页在最开始构建时，主JavaScript bundle达到了220KB（gzip后约78KB），不算大，但后续加入图表库后直接飙到400KB以上。优化手段不外乎几个方向：组件库按需引入，图表类占体积的库使用动态加载；页面尽量拆分路由，而不是把所有逻辑塞进同一个layout；对于非首屏渲染的组件，用next/dynamic开启SSR时不做加载。
我把首页的图表组件改成动态导入后，首屏主bundle从420KB降到了约180KB，LCP时间从3.8秒降到2.1秒。这里想多说一句，性能优化不要只盯着构建报告里的分数，要实际看用户网络环境下的加载时间。t3code里加了一个简单的埋点，记录页面加载耗时的分位数据，后续优化就有据可依。
4.4 冷启动问题的临时对策
Node服务在低流量时段会被系统回收进程，下一次请求进来时PM2会重新拉起进程，这个过程就是冷启动，用户感知到的表现是页面空白了几秒。t3code的应对方式是给PM2设置min_uptime和autorestart参数，并开启--cron-restart定期重启，保证服务不会因为闲置时间太长而进入深度冻结状态。这个方案不算优雅，但胜在简单可靠。如果项目流量持续上涨，后续可以把部署方式迁移到容器平台，利用多实例来消除单机冷启动。
5. 使用t3code期间踩过的坑与规避建议
这些坑不是从文档里读来的，是我在实际建站和运行过程中一步步排查出来的。列在这里，希望后来者能少走弯路。
5.1 交互式事务的锁等待
t3code里曾经有一个批量导入功能，逻辑是遍历一批数据，逐条执行upsert操作。最初我图省事，把它们包在一个交互式事务里：
await db.$transaction(async (tx) => { for (const item of items) { await tx.model.upsert({ ... }); } });数据量小的时候一切正常，数据量上了几千条之后，事务长时间持有连接，其他读写请求被阻塞。排查发现，交互式事务建议控制执行时长，不要在事务里面做耗时的循环操作。最终我把批量导入改成了分批非事务执行，每批100条，配合幂等的业务主键，既保留了正确性，又避开了长事务。
5.2 tRPC的全局错误处理：Zod校验失败的HTTP状态码问题
在v10版本中，tRPC默认把ZodError映射成400还是500，取决于你如何配置errorFormatter。有段时间接口的前端一直拿到500错误，但日志里明显是参数校验失败，定位问题花了不少时间。后来在根Router里配置了一个全局错误格式化函数，把ZodError的校验信息提取出来，并统一映射到400状态码。这样一来，前端能够根据状态码区分参数错误和服务端异常，弹窗提示也更准确。
5.3 Next.js App Router中间件里的session刷新
NextAuth在App Router下的中间件写法与传统Pages Router略有不同，最容易踩的坑是在中间件里直接读取JWT但没做刷新。JWT模式默认有效期较长，用户权限变更之后，要等token过期才会生效。t3code的解法是在中间件里调用getToken拿不到关键信息时，主动重定向到登录页，同时在数据层的protectedProcedure里做二次权限验证。记住一个原则：中间件只做粗粒度的路由保护，细粒度的数据权限必须回到服务端tRPC里判断。
5.4 升级依赖时锁文件冲突
t3code在升级到Next.js 14时遇到过依赖冲突：tRPC需要React 18，而某个UI库需要React 18.2，pnpm的严格依赖模式直接报错。这种情况没有灵丹妙药，建议养成小步升级的习惯，不要把几十个依赖一次性全部升级。升级时重点看三个地方：Next.js是否改动了路由相关API、Prisma是否需要重新生成Client、tRPC是否有破坏性变更。确认这三个方面，升级通常不会脱轨。
6. 如果你也想搭一套自己的t3code，我的建议
与其把t3code当作一个固定产品去使用，我建议你把它当作一份“可以参考的答案”，结合自己手头项目的真实诉求来调整。比如你的业务以内容展示为主，对登录的要求很弱，那完全可以把认证模块拆掉，把省下来的复杂度换成缓存层；如果你的项目需要处理复杂的用户权限，那多研究一下RBAC模型的落地方式，再对Prisma Schema做定制。
还有一个体会是关于协作的。脚手架能约束技术选型，但约束不了团队习惯。如果团队里有人习惯直接改数据库而不写迁移，再好的模板也会慢慢腐化。我在t3code的README里加了一条约定：所有表结构变更必须通过Prisma Migration提交，且必须有专人Review。这份约束比任何技术方案都重要。
从最初为了解决自己重复搭项目的烦躁，到现在t3code成为团队内部启动新业务时默认拉取的起点，这个过程让我确信：所谓高质量的开发效率，不是堆更多代码工具，而是把那些不该重复消耗精力的环节，用工程化的手段一次性解决掉。希望这篇记录对你也有同样的帮助。
