1. 项目概述1.1 为什么会有 t3code 这个项目t3code 是我最近在推进的一个个人项目代号。它来自团队内部的一次技术选型讨论我们在调研 TypeScript 全栈技术方案时注意到 T3 StackNext.js Tailwind CSS tRPC TypeScript这套组合在中小型项目里表现出极高的效率优势于是把一套内部业务从传统的 REST 架构迁移到 T3 Stack 上。团队内部用统一的代码仓库别名来指代这套技术栈t3code 这个名字就这么落下来了。简单说t3code 不是一个产品名称而是一个用 T3 全家桶构建、以类型安全为第一优先级的编码项目代号。它解决的问题非常具体在前后端分离的项目中API 接口的定义、联调、响应校验常常产生大量的重复工作特别是后端字段一改前端就得跟着排查类型报错。t3code 的核心思路是让前后端共用一套类型定义从数据源头消除这类问题。对于一个已经熟悉 React 和 Node.js 的前端团队来说这套技术栈的学习成本不算高。如果你正处于想上 TypeScript 全栈但不知道从哪一步开始的状态或者你受够了前端手动维护接口类型定义、每次联调都要反复对齐字段——那 t3code 这种方式值得参考。本文我会从技术选型的逻辑、核心模块的拆解、具体实现步骤到实际踩过的坑完整梳理一遍。1.2 t3code 的技术栈全景先看整体面貌t3code 的技术组件如下技术组件选型版本在项目中的职责Next.js14.xApp Router前端页面渲染、路由控制、服务端渲染能力支持Tailwind CSS3.4.x原子化 CSS 方案负责全部 UI 样式tRPC10.x端到端类型安全的接口通信层替代传统 REST APITypeScript5.x全项目静态类型检查核心的跨端类型共享载体Prisma5.xORM 层负责数据库表结构定义与数据访问NextAuth.js4.x身份验证方案支持第三方 OAuth 登录这个组合不是随意的拼凑。tRPC 能把接口调用变成类似前端直接调用本地函数的体验所有入参和出参的类型都能从前端代码直接推导出来。对小型团队来说最大的收益是省掉了手工维护 API 文档、接口类型定义和 mock 层的时间。另外这套技术栈还有一个隐性特点它不要求你同时维护两套独立的工程代码。Next.js 本身就能同时承担前端渲染和后端 API 的职责通过 Route Handler 或者 Server Actions再加上 tRPC 提供的服务端调用方法整个应用可以在一个代码仓库里跑起来。t3code 把开发环境、构建流程、代码检查全部整合进一套配置体系大幅降低了工程复杂度。2. 整体设计与核心思路拆解2.1 为什么选择 T3 Stack 而不是传统前后端分离架构在设计 t3code 之初团队内部并不是没有讨论过更主流的方案比如前端 React/Vue 后端 Spring Boot 或 NestJS。最终选择 T3 Stack 背后来有一条很清晰的决策线。传统的 REST 架构中数据契约主要依赖 OpenAPI 文档。前端要从文档中提取类型定义再手工维护一份对应的 TypeScript 类型文件。项目一复杂接口路径和字段数量膨胀得极快这时候最难的就是前后端不同步。后端改了字段名前端如果没有及时更新类型文件运行时不报错但代码逻辑拿到的数据可能已经是 undefined 了排查难度非常大。这类问题在 t3code 的场景里被直接抹平了——tRPC 让类型定义不再是额外维护的东西而是服务端函数签名的一部分前端调函数时自动获得完整的类型推导。另一个重要原因是开发体验。用 tRPC 后调用后端接口在代码层面类似这样// 后端定义查询用户详情的函数 const getUser t.procedure .input(z.object({ id: z.string() })) .query(async ({ input }) { return prisma.user.findUnique({ where: { id: input.id } }); }); // 前端直接调用无需手动指定返回类型 const { data } trpc.getUser.useQuery({ id: abc });前端书写useQuery时编辑器会自动提示id字段类型和getUser的返回类型。如果你传的参数不对或者误用了返回结构里不存在的字段编译阶段就会直接报错。这种代码即契约的能力是整个 t3code 项目最后能坚持下来的核心原因。当然没有任何方案是万能的。T3 Stack 更适合中小型项目或快速迭代期的产品如果业务逻辑非常复杂、涉及大量异步消息、需要多语言异构服务配合那传统架构反而更合适。t3code 的定位从一开始就是轻量、快速、类型安全这个定位后来证明非常精准。2.2 目录结构与分层设计一个项目的长期可维护性往往在目录结构设计时就已经决定了。t3code 的分层逻辑借鉴了业界常见的按业务领域划分思路但做了简化保持小团队能够快速上手。t3code/ ├── prisma/ │ └── schema.prisma # 数据库表结构定义 ├── src/ │ ├── pages/ # 页面路由 │ │ ├── _app.tsx │ │ ├── api/ # Next.js API 路由tRPC 挂载点 │ │ ├── index.tsx # 首页 │ │ └── dashboard/ │ ├── server/ │ │ ├── api/ # tRPC 路由注册与上下文 │ │ │ ├── trpc.ts # tRPC 实例初始化 │ │ │ ├── root.ts # 汇总所有子路由 │ │ │ └── routers/ # 按业务划分的子路由文件 │ │ └── db.ts # Prisma 客户端单例 │ ├── styles/ │ │ └── globals.css # Tailwind 样式入口 ├── types/ # 跨业务模块共享的通用类型 ├── public/ ├── tailwind.config.ts ├── next.config.js └── package.json这个结构最核心的要点是src/server/目录。tRPC 官方推荐的写法是让 Next.js 的所有接口请求都聚集到同一个 API 端点然后由root.ts里的路由分发表统一分发。这样做的优势在于后端逻辑不需要关心路由地址的匹配规则所有函数都是被调用而不是被请求。如果你曾经维护过传统 REST 接口会明显感觉到这种分层的差异。原来新增一个接口要处理 HTTP 方法、路径、鉴权中间件、参数解析而现在只需要在 routers 里新增一个子路由文件注册到 root 就可以了。整个过程不涉及任何 URL 字符串拼接。2.3 类型安全如何贯穿整个数据链路类型安全是 t3code 的第一性原则理解这一点就能理解项目里面很多形式感很强的代码。传统架构里类型检查只是前端/后端各自代码内部的工具。但在 t3code 中类型系统实际上升级成了团队协作的数据协议。一条数据从数据库出发到最终 UI 渲染类型穿透路径大致是Prisma 根据schema.prisma生成数据库类型定义server/routers中的 tRPC 查询函数直接返回这些类型或派生类型tRPC 客户端在任何调用点自动推导出返回类型不需要手写Next.js 组件的 state / props 使用这些推导类型进行约束从最终效果来说你改schema.prisma里某个字段Prisma 生成新的类型后所有相关的调用点会自动同步更新类型推导。前端代码如果访问了被删除的字段编译立刻报错不用等运行时才发现。这里有一个重要提示因为 Prisma 生成的类型是编译时依赖改完 schema 后务必执行npx prisma generate很多新人会卡在这一步导致明明改了 schema 却看不到类型变化。在最理想的状态下团队成员甚至不需要知道具体某一项业务接口返回什么字段直接跟着编辑器的类型提示写就行。这就是 t3code 想带来的开发体验把接口对接这件事从沟通问题变成编译器问题。3. 核心细节解析与实操要点3.1 tRPC 路由设计的三个关键步骤在 t3code 中tRPC 层的设计质量几乎直接决定后续开发的体验。我把它拆成三个步骤每一步都有对应的代码和注意事项。第一步是初始化 tRPC 实例。这个实例的作用是定义上下文类型、错误格式化器、程序处理器等基础能力。项目里新建src/server/api/trpc.tsimport { initTRPC, TRPCError } from trpc/server; import superjson from superjson; import type { Context } from ./context; const t initTRPC.contextContext().create({ transformer: superjson, }); export const router t.router; export const publicProcedure t.procedure; export const protectedProcedure t.procedure.use(isAuthenticated);这里的superjson是为了让 tRPC 能序列化 Date、Map 等特殊类型。我们有一个模块的返回结果包含日期对象如果没有配置 transformer序列化到前端时Date会变成字符串很多时间格式处理逻辑就会出错。这是比较经典的一个配置点建议从一开始就加上。第二步是定义上下文Context。上下文对象在每次请求预处理阶段生成通常携带当前用户身份和数据库连接。t3code 的实现是从 NextAuth 的 session 中读取当前用户信息挂载到 context 上这样受保护的接口就能直接获取用户身份不用在自己的逻辑里再处理鉴权。export const createContext async (opts: CreateNextContextOptions) { const session await getServerSession(); return { session, db: prisma, }; };第三步是创建子路由。子路由管理是业务模块划分的关键t3code 按照用户、项目、评论三个核心领域来拆。每个子路由内部可以继续用createCallerFactory来合并更细的接口但保持小团队够用的粒度就好——不要拆得过多否则光看文件列表就看晕了。3.2 Prisma 数据建模与迁移的实操细节数据层设计上t3code 使用 Prisma 作为数据库访问工具。选择 Prisma 而不是 TypeORM 或 Drizzle主要是看中它的类型生成体验和 migration 工作流。以下是一个用户与项目关联的简化模型model User { id String id default(cuid()) name String? email String unique projects Project[] createdAt DateTime default(now()) } model Project { id String id default(cuid()) name String description String? author User relation(fields: [authorId], references: [id]) authorId String createdAt DateTime default(now()) }这里要强调一个实操细节主键尽量用cuid()或uuid()不要用自增数字。自增主键容易在数据迁移、多环境同步时产生冲突。cuid 是字符串类型既能排序也能防止因为导出导入导致的 ID 碰撞。在匹配数据库结构时直接运行npx prisma migrate dev --name init这个命令会生成迁移 SQL并自动执行到本地开发数据库。每次修改 schema 后务必手动运行npx prisma generate我是吃了好几次亏才记住这一点。你加了新字段没重新生成编辑器写代码时不报错但实际查询时返回的数据没有该字段排查起来极为痛苦。3.3 Next.js App Router 与服务端组件如何配合 tRPCt3code 采用的 Next.js 14 支持 App Router它有新的服务端组件模型。这里和 tRPC 的配合有一些讲究新手容易在服务端组件能否用 useQuery这个问题上犯糊涂。服务端组件不能使用 React Hooks因此常规的 tRPCuseQuery只能用于客户端组件。如果想在服务端组件里直接读取数据正确的姿势是使用 tRPC 的 server call 能力也就是createCallerimport { createCaller } from ~/server/api/root; import { createContext } from ~/server/api/context; const caller createCaller(await createContext({})); const projects await caller.project.list();这样既能在服务端组件里获取数据又不破坏类型安全。前端页面需要的展示数据如果不需要交互优先走这种方式因为服务端渲染可以减少一次额外的客户端请求。另外要注意在服务端组件中调用createContext时不会像 HTTP 请求那样自动附带 session需要手动获取getServerSession()后传入。我在一开始实现时没处理这一步服务端渲染出来的页面永远显示未登录排查了两天才意识到是 context 里的 session 为空。对于需要交互的部分比如评论区点赞、动态表单提交才在客户端组件里使用useQuery和useMutation。这样做的分工逻辑是静态展示走服务端动态操作用客户端各取所长。3.4 Tailwind CSS 在项目中的配置与约定样式部分t3code 几乎完全依赖 Tailwind CSS。这套方案的核心优点是可以不离开 HTML 结构完成整套样式开发但对团队约束有隐性的要求设计规范必须统一。t3code 在tailwind.config.ts中扩展了一些自定义色彩和间距token目的是约束设计的一致性。比如主色调用 primary 而不是直接写蓝色 hex 值避免团队一半的人用蓝色一半人用紫色最后新老页面风格割裂。import type { Config } from tailwindcss; export default { content: [./src/**/*.{js,ts,jsx,tsx}], theme: { extend: { colors: { primary: #4F46E5, accent: #0EA5E9, }, }, }, plugins: [], } satisfies Config;如果项目变得复杂可以考虑引入tailwindcss/forms这类官方插件来规范表单样式减少手写基础样式的时间。但注意Tailwind 的原子类写法很容易让 JSX 变得很长推荐结合clsx或tailwind-merge来做条件类名拼接我后续在实际开发中越来越依赖这两个小工具。4. 实操过程与核心环节实现4.1 初始化 T3 App 并完成基础配置t3code 的搭建不是完全从零手写。T3 Stack 提供了一个脚手架命令create-t3-app我建议先从这里起步它会自动把 Next.js、Tailwind、tRPC、Prisma、NextAuth 串联好减少百分之八十的前期配置工作。npx create-t3-applatest t3code脚手架生成的过程中需要选择需要的功能模块构建 t3code 时我勾选了 Next.js 的 App Router、Tailwind CSS、tRPC、Prisma、NextAuth.js。TypeScript 是强制安装的不需要额外选择。初始化完成之后最重要的第一步是配置环境变量。根目录下.env文件的示例如下DATABASE_URLpostgresql://user:passwordlocalhost:5432/t3code NEXTAUTH_SECRET生成一个随机字符串 NEXTAUTH_URLhttp://localhost:3000DATABASE_URL是数据库连接串NEXTAUTH_SECRET是 NextAuth 的加密密钥可以用openssl rand -base64 32生成。这里要格外注意.env文件不要提交到 Git 仓库需要加入.gitignore。4.2 关键配置文件逐个过一遍脚手架生成的项目里有几个核心配置文件决定了整个项目的工程质量逐个过一遍会让你心里有底。第一个是next.config.js。t3code 中它承担了路径别名配置和作用域包名的 transpile 处理。重点配置路径别名可以帮助代码更简洁同时不影响编辑器跳转。/** type {import(next).NextConfig} */ const nextConfig { reactStrictMode: true, transpilePackages: [t3code/ui], images: { remotePatterns: [ { protocol: https, hostname: **.mycdn.example, }, ], }, };这里transpilePackages的配置很有用如果你的项目用了 monorepo 或者本地共享 UI 包没有这个配置会导致 Next.js 编译时无法正确解析包内的代码。第二个关键配置是tsconfig.json的路径映射。脚手架已经配置了~/*别名但建议统一一下所有业务代码放在src/下用~/引入避免出现../../../components这种多层相对路径满天飞的情况。第三个容易被忽略的是src/server/db.ts中的 Prisma 客户端单例。开发模式下 Next.js 的热重载会导致模块重复执行如果没有做全局缓存会创建大量数据库连接很快把本地数据库连接池打满。标准的单例写法如下import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient | undefined; }; export const prisma globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) globalForPrisma.prisma prisma;这段代码看着不起眼却是生产环境稳定性非常关键的一环。4.3 从 0 到 1 实现用户注册与资料查询为了把 tRPC 完整的开发链路走通我用一个最典型的用户注册 个人资料查询功能作为示例。这一段会完整展示 schema、后端路由、前端调用的三部分代码。第一步在schema.prisma中添加用户资料模型model User { id String id default(cuid()) name String? email String unique bio String? createdAt DateTime default(now()) }第二步创建src/server/api/routers/user.ts文件import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure, } from ~/server/api/trpc; export const userRouter createTRPCRouter({ register: publicProcedure .input( z.object({ email: z.string().email(), name: z.string().min(2), bio: z.string().max(200).optional(), }) ) .mutation(async ({ ctx, input }) { return ctx.db.user.create({ data: { email: input.email, name: input.name, bio: input.bio, }, }); }), getProfile: protectedProcedure.query(async ({ ctx }) { const userId ctx.session.user.id; return ctx.db.user.findUnique({ where: { id: userId }, select: { id: true, email: true, name: true, bio: true, createdAt: true, }, }); }), });这里zod承担了运行时参数校验的职责与 TypeScript 编译期检查形成双保险。尤其要注意tRPC 官方推荐的校验方式就是 zod因为它能生成校验规则在边缘情况下能兜住一些类型系统放松的地方。第三步前端页面调用。注册页面里直接调用register函数实现表单提交import { api } from ~/utils/api; const registerUser api.user.register.useMutation(); const onSubmit async (values: { email: string; name: string; bio?: string }) { await registerUser.mutateAsync({ email: values.email, name: values.name, bio: values.bio, }); };在编辑器中你会看到mutateAsync的参数类型已经完全从 tRPC 路由声明中推导出来。如果传入了 schema 之外的字段编译会直接标红。这一步代码即契约的体验是 t3code 开发模式下最让人上头的时刻。4.4 如何通过 NextAuth 接入 GitHub 登录身份验证是 t3code 不可缺少的一环。我选用 NextAuth.js 来接入 GitHub OAuth它的配置非常直接。在src/server/auth.ts中配置import NextAuth from next-auth; import GitHub from next-auth/providers/github; export const { handlers, auth } NextAuth({ providers: [ GitHub({ clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, }), ], callbacks: { async session({ session, user }) { if (session.user) { session.user.id user.id; } return session; }, }, });要使用 GitHub 登录需要先在 GitHub 的 OAuth Apps 配置页面创建一个应用把回调地址设置为http://localhost:3000/api/auth/callback/github。GITHUB_CLIENT_ID和GITHUB_CLIENT_SECRET分别填入.env。整个配置流程中有一个常见坑位如果NEXTAUTH_SECRET没有配置开发环境下 NextAuth 会生成一个临时密钥功能仍然可用但每次重启服务器旧 session 就全部失效了。生产环境必须固定这个密钥否则用户会被频繁登出。导航栏中的登录状态逻辑使用useSession钩子配合条件渲染即可。t3code 的应用场景是内部工具登录鉴权优先级很高所以protectedProcedure使用了拦截中间件const isAuthenticated t.middleware(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: ctx.session, }, }); });4.5 构建、环境变量与生产部署要点项目开发完成后部署到生产环境前一定要做好构建验证。执行npm run buildNext.js 在构建阶段会执行 TypeScript 类型检查和 ESLint 检查。如果代码中有类型问题构建会直接失败。这是好事它把大部分错误提前拦截在了部署之前。构建成功之后使用npm run start可以启动生产服务。这一步我之前掉过坑本地开发环境用npm run dev好好的一执行 production 构建就报错大概率是暴露了某些只在 development 下生效的隐式行为。例如在服务端组件中隐式访问process.env.NEXTAUTH_URL开发的时候 NextAuth 自己商量好了构建时就提示缺变量。生产环境部署前务必将所有环境变量核对完毕并确保它们全部能在部署平台设置到位。t3code 目前部署在容器环境Dockerfile 的关键是多阶段构建。Node 版本建议锁死为 20npm ci替代npm install这样能保证构建环境的依赖和本地完全一致。如果部署平台是 Vercel可以直接复用平台的默认构建流程它本身针对 Next.js 做了大量优化相对省心一些。5. 常见问题与排查技巧实录5.1 典型报错与解决方案速查表我在 t3code 的开发和后续维护中积累了下面这些高频问题整理成速查表会很有帮助症状可能原因解决方案tRPC 调用返回 500但没看到具体报错tRPC 默认不会返回堆栈信息开发环境开启onError回调打印完整错误生产只记录 IDPrisma 查询结果缺少刚加的字段忘记执行prisma generate修改 schema 后立即运行npx prisma generate并重启 dev serverNextAuth 登录后 session 偶尔丢失多个实例共享了不正确的 secret统一设置NEXTAUTH_SECRET不要在代码里写死Tailwind 样式生成不出预期content 配置路径不正确确认tailwind.config.ts中content覆盖了所有用到类名的文件部署后页面一直转圈数据库连接串不可访问在服务端日志里检查DATABASE_URL特别注意 IP 白名单限制客户端组件和服务端组件混用时 hydration 报错读取的数据在两端生成不一致避免在服务端组件调用内部随机性的内容保持渲染内容确定这张表覆盖了 t3code 上线以来的大部分线上问题建议直接收藏保存。5.2 大型重构时的类型排查思路t3code 经历了一次从页面级路由到业务模块化路由的重构。在重构过程中最大的难点不是改代码而是处理一起被牵扯出来的类型报错。我的排查思路分三步可以复用到同类场景第一步先看报错文件里是否出现Type X is not assignable to type Y。这个报错信息其实很有价值它表明某个函数的返回值类型和定义的类型不一致。优先研究目标类型是从哪个 tRPC 路由推导出来的——如果是trpc.xxx.useQuery()的返回类型那说明要回到routers目录找对应函数检查。第二步关注 tRPC 的input类型。如果旧页面传的参数结构和新的 zod schema 不一致都能在编译阶段报出来。这时候不要为了快速通过编译就加as any这类逃逸手段会在后续重构中积累成更大的债务。正确做法是找到所有调用点逐个修改参数结构。第三步排查通过后运行npm run type-check做全量检查确保整个项目不再有隐藏的类型告警。光改当前文件是不够的因为一个类型声明变动可能会波及下游若干个组件。我强烈建议从一开始就给 tRPC 的procedure加上完整的 zod schema不偷懒写z.any()。运行时校验和编译期类型是双保险少了任何一道都会给排查增加明显成本。5.3 性能优化经验分享t3code 的初始版本在数据量变大后几个列表页面出现了明显的响应延迟。定位后主要做了三类优化每个都有实际效果。第一类是数据库层的 N1 查询优化。在 Prisma 中使用include预加载关联数据避免了循环中逐个查询数据库的问题。例如const projects await ctx.db.project.findMany({ include: { author: { select: { name: true, email: true, }, }, }, });第二类是 tRPC 查询的缓存策略。tRPC 已经支持useQuery的staleTime配置对变化不频繁的数据我会设置合理的过期时间1到5分钟大幅减少对数据库的压力。第三类是列表页的分页。tRPC 配合 zod input 校验接收page和pageSize两个字段数据库层用take和skip实现物理分页避免一次性查出几万条数据在内存里做剔除。这一点做到之后页面的加载速度已经从原来的七八秒降到了两秒以内体感提升非常明显。6. 写在最后的个人体会t3code 这个项目的完整落地让我最深刻的体会是技术栈的收益是锦上添花真正决定项目体验的是整体数据流设计的清楚和团队对自己业务模型的把握。T3 Stack 也好任何全栈方案也好做得好坏很大程度上取决于两件事——类型设计是否符合实际业务以及团队成员是否愿意遵守项目里约定的规范。我在实际推进过程中还有一个小小的建议如果你的项目是团队协作建议在第一天就把 tRPC 路由的文件划分规则、zod schema 的命名规则和 Prisma 模型的命名规范定好。这些约定在前期的确会花一点时间但到了项目后期每个模块之间的边界是否清晰直接决定了你花在翻代码上的时间而不是写代码的时间。最后再分享一个小技巧t3code 的开发环境里我给next dev配了--turbo参数在 Next.js 14 中启动速度和热更新体验都有明显提升。偶尔遇到模棱两可的配置问题先试着打开浏览器开发者工具的 Network 面板看一眼 tRPC 请求的具体响应再回到代码里找原因比盲目猜快得多。t3code 还有很多可以扩展的方向比如引入 WebSocket 实时推送、迁移到 Turborepo 多包架构、加入单元测试等这些内容留待后面有机会再继续展开。