t3code 这个项目名第一次看到的人可能以为是个代码编辑器或者代码生成器实际上它是我整理的一个全栈项目模板核心技术栈是 The T3 Stack 那一套Next.js、TypeScript、tRPC、Prisma、Tailwind CSS。t3code 这个名字既点明了 T3 技术栈又暗含“代码怎么写才更舒服”的意思所以我把平时做业务项目里重复性最高的认证、数据库建模、API 路由、样式封装全部整合到了一起。这篇东西会围绕 t3code 展开从选型逻辑讲到落地实现再讲到部署和排坑完全按照我自己实操时的状态来写。t3code 适合谁如果你已经会基础的 React 和 Node.js下一步想自己搭一个类型安全的全栈应用又不想每次手动把 Next.js、Prisma、tRPC 黏在一起那这个项目就是一个可以直接照着抄的完整答案。它能帮你解决从数据库字段到前端页面展示中间那一大堆胶水代码把“端到端类型安全”从概念变成真正能运行的工程框架。先说一下 T3 Stack 的设计逻辑再逐层拆 t3code 的实现细节这样就算你之前没接触过 tRPC也能看懂后面每一段代码在干什么。1. t3code 是什么我为什么决定做这样一个全栈项目1.1 T3 技术栈的核心并不只是“三个字母”T3 Stack 这个名字最初来自社区里一个很流行的全栈组合核心成员包括 Next.js、TypeScript、tRPC、Prisma、Tailwind CSS。它并不是一个官方框架而是一套“最符合现代全栈开发习惯”的选型组合。T3 背后的理念我一直很认同与其在前后端之间各写一套类型定义不如用一套代码把类型从数据库一路传到浏览器。我自己在早期项目里吃过不少类型不同步的亏。前端定义User接口后端再定义一份Usermodel数据库里还有一张users表三份定义各改各的某次接口改字段名忘了同步前端编译不报错运行时拿到undefined排查了一下午才找到问题。t3code 想解决的就是这个痛点Prisma 里定义 schematRPC 用类型推导自动生成 API 类型Next.js 组件里直接 import 类型来用三处变成一处字段增删改都有编译器盯着。很多人以为 T3 Stack 就只是“把工具堆一起”其实关键在于类型信息如何流动。不能说因为大家都用 Next.js 就选 Next.js真正让这套组合成立的是 tRPC 和 Prisma 之间的天然配合。Prisma 根据数据库 schema 生成类型tRPC 的 router 定义又基于这些类型推导出完整的输入输出结构。前端调用远程方法时就像调用本地函数一样有提示这种体验在传统 REST API 体系里很难做到。1.2 t3code 的目标与适用场景t3code 不是一个什么都能装的“全家桶框架”它更像是一个有明确边界的起点项目。我给它定的目标有三条第一开箱即用git clone 下来后执行安装命令就能跑起来第二类型安全贯穿全链路不确定类型的代码不应该出现在业务代码里第三代码量要足够少让新人能在一天内看完所有源码。适用场景也很清晰。第一个场景是个人全栈项目的起步模板比如做一个小工具网站、作品集、内部管理系统用 t3code 可以直接把基础架构搭好把注意力留给业务。第二个场景是团队做原型验证产品经理给了一个新需求大家不想从零搭工程t3code 可以在一小时内跑通完整链路包括数据库建表、页面展示、增删改操作。第三个场景是学习交流很多人想学 tRPC 但不知道从哪里开始看最小示例又太简陋看大型项目又太复杂t3code 的代码量处于一个比较适合阅读的中间档位。当然如果你要做的是一个高并发、重缓存、需要复杂消息队列的中大型系统t3code 不适合直接当底座。它不会替你做权限系统、不会帮你拆微服务、不会内置消息推送。这些超出范围的东西一概不碰宁可保持工程的简洁也不要把脚手架变成笨重的框架。1.3 它比 create-t3-app 多做了哪些实际的工作很多朋友看到这里会问直接用create-t3-app不就行了吗为什么还要维护一个叫 t3code 的项目这个问题的答案很实在。create-t3-app生成的是初始骨架解决的是“项目能不能跑起来”的问题t3code 解决的是“项目里有没有一套可以直接复用的业务基础和代码风格”的问题。具体来说我在 t3code 里预设了几个常用模块一个基于 NextAuth 的凭证登录功能支持注册、登录、退出一套统一响应的 tRPC 错误处理中间件一个 Prisma 模型示例包含用户、会话和管理后台核心表页面侧还做了一个带主题切换的布局组件Tailwind 的配置也做了工程化拆分。这些代码并不是网上随意抄来的片段而是我在几个真实项目里反复调整出来的稳定版本。create-t3-app 能让你在几分钟内拥有一个干净工程但接下来你仍然需要自己去接认证、去设计错误处理、去写布局这些工作占用的时间和写业务代码差不太多。t3code 把这一步预置好了相当于从“毛坯房”升级成了“拎包入住”。不过要注意预设的东西越多学习成本也会越高我尽量控制每个模块只保留一个主流实现不搞多种方案并存这样看代码时不会觉得混乱。2. 技术选型取舍与项目骨架2.1 为什么是 Next.js App Router 而不是 Pages Routert3code 使用 Next.js App Router这一点不是跟风而是看完实际收益后做出的选择。App Router 带来的最大改变是目录结构即路由app目录下的page.tsx、layout.tsx、loading.tsx各自承担渲染职责代码组织方式比 Pages Router 的pages/api和pages双目录要清晰很多。从服务端组件和客户端组件的划分来讲App Router 也给了更明确的边界。我可以在服务端组件里直接读取数据库数据并预渲染把需要交互的部分单独隔离成客户端组件。类型安全在这个架构下更自然因为服务端组件的 props 天然就是序列化后的数据不需要再额外写 loading 状态除非真的需要在客户端动态获取数据。还有一个非常实际的好处Next.js 15 以后对 App Router 的支持越来越稳很多第三方库的 SSR 兼容方案都已经默认适配 App Router。如果现在做新项目还用 Pages Router可能短期内看不出问题但接下来新功能迭代和老库更新都会越来越偏向新路由模式。我不建议老项目立刻迁移但是新项目比如 t3code直接用 App Router 是更长远的选择。2.2 Prisma SQLite/Postgres 的权衡数据层我选了 Prisma没有选 Drizzle ORM也没有直接写 SQL。原因很简单Prisma 的 schema 文件足够直观团队里哪怕是刚接触 ORM 的成员也能根据 model 定义看懂表结构同时它自带 migration 工具能生成 SQL 迁移文件方便 review。数据库方面t3code 默认支持 SQLite 和 PostgreSQL 两种配置。SQLite 用于本地开发和个人小项目零配置文件跑起来不用依赖 DockerPostgreSQL 用于生产环境毕竟是实际部署时的主流选择而且和 Prisma 配合得最好。切换数据库的方式只是在.env里改一行DATABASE_URLschema 文件不需要改动除非你用到某些数据库特有类型。这里有个经验值得分享本地开发和线上环境尽量保持同一种数据库。如果本地用 SQLite线上用 PostgreSQL很多 SQL 方言差异会在上线后突然出现比如字段类型、索引行为、事务隔离级别都会有微妙区别。t3code 虽然支持混合开发但我在自己的使用习惯上是能统一就统一实在不行就用 Docker 在本地起一个 PostgreSQL 实例。2.3 目录结构与配置入口解读t3code 的目录结构是我花了不少时间调出来的既要符合 Next.js 的默认约定又要让业务模块边界清晰。核心部分长这样t3code/ ├── app/ │ ├── (auth)/ │ │ ├── login/ │ │ └── register/ │ ├── (dashboard)/ │ │ ├── projects/ │ │ └── settings/ │ ├── api/ │ │ └── trpc/ │ └── layout.tsx ├── components/ │ ├── ui/ │ └── shared/ ├── server/ │ ├── api/ │ │ ├── routers/ │ │ └── trpc.ts │ ├── auth.ts │ └── db.ts ├── prisma/ │ ├── schema.prisma │ └── seed.ts └── trpc/ ├── client.ts └── server.tsapp/(auth)和app/(dashboard)是两组路由组它们不产生真实的 URL 前缀只用于把登录页面和主页面分开。server/api/routers放 tRPC 的各个路由模块trpc/client.ts和trpc/server.ts是类型导出的关键入口。这样的结构让我在加新功能时很明确页面文件去app里加UI 组件去components里加数据接口去routers里加数据库表去prisma里改不会出现文件乱放的问题。很多项目搭建初期不重视目录规范等到文件多了以后开始到处找代码严重的还会出现循环依赖。t3code 里我用了一个简单的依赖规则app层可以引入components和trpccomponents和trpc可以引入server但是server层不能反向引入components。这条规则写进 README 之后团队协作时的沟通成本低了很多。3. 从零搭建 t3code 的关键步骤与实现细节3.1 初始化项目与基础配置开始之前你需要准备 Node.js 20 以上版本和包管理器 pnpmnpm 也能用只是 pnpm 在依赖安装速度和严格模式下更适合这种工程。初始化可以直接用create-t3-app也可以手动搭。我建议初学者先跑一次官方脚手架看看它默认生成的文件结构再用 t3code 的代码对照理解。第一步是创建项目目录和初始化 package.jsonmkdir t3code cd t3code pnpm init然后安装核心依赖pnpm add next react react-dom tanstack/react-query trpc/server trpc/client trpc/react-query trpc/next prisma/client zod superjson pnpm add -D typescript types/node types/react types/react-dom prisma tailwindcss postcss autoprefixer eslint eslint-config-next这里有个很容易犯的错superjson不能漏。tRPC 默认只能序列化 JSON 能表达的数据但Date、BigInt这类对象需要特殊处理。superjson是一个扩展序列化库它让 tRPC 可以传输这些复杂类型少装了这个包即使代码编译通过运行时也会出现序列化错误。安装完成后在.env里配置数据库连接本地开发我用 SQLiteDATABASE_URLfile:./dev.db NEXTAUTH_SECRETdev-secret-please-change NEXTAUTH_URLhttp://localhost:3000NEXTAUTH_SECRET 在本地开发时可以随便写但上线前必须改成足够随机的字符串。我习惯用openssl rand -base64 32生成比手敲键盘可靠得多。3.2 数据库模型设计与 Prisma 迁移t3code 里我设计了三个最常用的模型用户、会话、项目。用户和会话是认证模块需要的基础表项目是用来演示 tRPC CRUD 操作的业务表。Prisma 的 schema 很长我只把最关键的部分拉出来看model User { id String id default(cuid()) email String unique passwordHash String name String? projects Project[] sessions Session[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Project { id String id default(cuid()) title String content String? status Status default(ACTIVE) ownerId String owner User relation(fields: [ownerId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt } enum Status { ACTIVE ARCHIVED }字段类型这里我推荐 String 配 cuid而不是自增 Int。自增主键在单体应用里没什么问题但一旦以后拆表、做数据合并或者暴露 ID自增数字很容易被猜到数量。cuid 虽然长了一点但分布均匀在分布式场景下也能避免冲突。写完 schema 后执行pnpm prisma migrate dev --name init pnpm prisma generatemigrate dev会创建迁移文件并更新本地数据库generate会基于 schema 生成 TypeScript 客户端类型。有个细节每次改 schema 后都要重新generate否则 Prisma 客户端还是旧类型如果你发现代码里访问不到新增字段多半是忘了这一步。3.3 tRPC Router 的编写与 React Query 集成tRPC 的写入方式非常直观一个 router 就是一组方法的集合。t3code 里对 Project 的操作长这样// server/api/routers/project.ts import { z } from zod; import { createTRPCRouter, protectedProcedure } from ../trpc; export const projectRouter createTRPCRouter({ list: protectedProcedure .query(({ ctx }) { return ctx.db.project.findMany({ where: { ownerId: ctx.session.user.id }, orderBy: { createdAt: desc }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().optional() })) .mutation(({ ctx, input }) { return ctx.db.project.create({ data: { title: input.title, content: input.content, ownerId: ctx.session.user.id, }, }); }), });这里有两个概念需要区分query用于读数据mutation用于写数据。React Query 会根据这个区分决定缓存策略和重试策略。query 的结果会被缓存组件重新挂载时不会重复发请求mutation 执行成功后需要让相关 query 失效否则页面上会显示旧数据。在 React 里调用时会自动生成类型安全的 hooksimport { api } from ~/trpc/react; const { data: projects, refetch } api.project.list.useQuery(); const createProject api.project.create.useMutation({ onSuccess: () { refetch(); }, });api.project.list这层链路就是端到端类型安全的体现前端不需要单独写接口路径字符串也不需要在外部再维护一份请求函数。改后端方法的 input 或输出类型前端调用处立即提示编译错误这是 t3code 最值回票价的特性。3.4 Tailwind 主题定制与响应式页面样式方面 t3code 用的是 Tailwind CSS 4相比 v3 最大的变化是配置方式从tailwind.config.js部分转移到了 CSS 变量里。t3code 的全局样式文件会定义一组主题颜色和语义 tokenimport tailwindcss; theme { --color-primary: #6366f1; --color-surface: #f8fafc; --color-text: #0f172a; }定义完theme之后页面里可以直接用bg-primary、text-text这类类名。很多朋友会纠结色值定义我的建议是先定两套模式一套浅色一套深色用 CSS 变量做桥接后续调整皮肤只改变量不用改组件类名。t3code 的布局组件里就做了一个简单主题切换原理是把>// server/db.ts 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; }这段代码几乎是 Next.js Prisma 项目的惯例了目的就是避免开发时创建多个数据库连接。如果你用的是 t3code 自带的server/db.ts这个处理已经内置好了。如果你是自己搭项目一定要加上否则改一行 schema 后热更新数据库连接数会肉眼可见地增长。生产环境还要注意连接池大小。PostgreSQL 默认连接数是 100业务量不大时 Prisma 默认的配置就够了。但如果你部署在 Serverless 环境每个冷启动实例都会建立数据库连接这时建议把连接池调小比如connection_limit5减少数据库压力。4.3 tRPC 类型推断出现 never 或 any 的常见原因tRPC 让人又爱又恨的地方在于类型推断。大多数时候它自动推导得非常好但偶尔你会发现在组件里调用api.project.create.useMutation()时input类型变成any或never这说明类型链路断了。最常见的根源是 router 里没有使用protectedProcedure或publicProcedure这些基础封装而是直接使用某些自定义中间件。tRPC 的类型系统依赖中间件类型能够正确推导如果自己写的中间件返回类型用了any整个 router 的类型就会崩塌。t3code 里我在创建 router 时严格遵守统一封装不直接在文件里写router.procedure的变体。另一个原因是 tsconfig 的 strict 模式没打开或者没有正确配置路径别名。类型推断最怕的就是ts-ignore或as any一旦出现这类代码编译器就无法继续往下推导。我在 t3code 的 tsconfig 里强制开启strict: true并设置了baseUrl和路径别名这样 IDE 和 CI 都能在同一个规则下工作。4.4 一张速查表解决大部分报错为了方便日常开发我把 t3code 里遇到的高频报错整理成了一张表每次出现类似错误先来这里查一遍能省不少排查时间。报错现象可能原因排查步骤推荐解法Prisma 类型里找不到新字段schema 已改但没重新生成客户端执行pnpm prisma generate在 package.json 的 postinstall 里加上prisma generatetRPC 调用显示无此方法router 没有挂载到根 router打开server/api/root.ts检查将新 router 注册到createTRPCRouter({ ... })NEXTAUTH_SECRET报错环境变量缺失检查.env文件本地用开发值线上用随机生成值React 组件提示需要use client使用了useState或事件监听但没标记检查组件顶部按需添加use clientsuperjson序列化 Date 失败服务端和客户端 superjson 版本不一致统一升级版本pnpm add superjsonlatest这张表不是万能药但它能帮你建立条件反射。碰到报错不要急着搜索先看错误信息里的文件和堆栈定位到具体模块后再用表里的思路去查速度比盲目试要快很多。5. 部署到生产环境与后续扩展方向5.1 部署到 Vercel 的配置要点t3code 是 Next.js 项目部署首选的平台自然是 Vercel。流程比较简单把代码推送到 Git 仓库然后在 Vercel 里导入项目它会自动识别 Next.js。需要重点设置的是环境变量包括DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL。如果你用的是 PostgreSQL推荐直接使用 Vercel Postgres 或者 Neon 这类托管数据库。拿到连接字符串后注意DATABASE_URL可能需要加上?sslmoderequire否则某些数据库服务商不接受非 TLS 连接。本地能用不代表线上能连这一步最容易在部署时才发现。Vercel 部署默认是 Serverless 模式每个请求都可能在独立环境里处理所以要注意几个问题文件系统不能作为持久存储临时上传文件要放在对象存储数据库连接要控制并发数依赖安装时需要在postinstall里执行prisma generate不然构建完的产物里没有 Prisma Client。部署完成后可以设置一个 GitHub Action 来做 CIpush 到 main 分支后先跑 lint、typecheck、build再触发 Vercel 部署。这样能避免很多“本地能跑线上崩”的问题。t3code 的仓库里已经附了一个最简版的 CI 配置文件照抄就能用。5.2 还能再往哪个方向扩展t3code 是一个起点之后的扩展方向取决于你实际业务需要。我个人建议优先做这几件事。第一接入 Prisma 的软删除与操作日志。现在的 model 里只有常规字段如果做管理后台需要记录谁在什么时候改了哪条数据可以在 Prisma 中间件或 tRPC 的 middleware 里统一处理。第二增加基于角色的权限控制目前只有登录验证没有区分管理员和普通用户。第三把文件上传接进来比如 S3 兼容存储让 Project 模型可以关联图片和附件。第四补充自动化测试至少给核心 router 写几个集成测试确保数据库操作不会破坏已有数据。不过每次扩展都会增加复杂度。我的原则是先跑通最小闭环再按真实需求加功能不要在项目第一天就把所有东西都规划好。t3code 保持现在这个体积正是为了让后来的人能够清楚地看懂每一步在做什么也可以大胆地按自己的思路去改。最后再聊一点我的真实体会把 t3code 从零搭到可以部署我最大的感受是全栈项目的复杂度并不在于某个单独的技术有多难而在于它们之间的边界需要花心思设计。Next.js 负责做好渲染边界Prisma 负责数据建模tRPC 负责消除前后端类型损耗Tailwind 负责不让样式成为维护负担。每一层单独看都很简单但组合起来真正跑通一轮你对整个现代 Web 应用的运行逻辑会有非常直观的理解。如果你打算拿 t3code 做自己的下一个项目起步模板我建议先别急着改功能花点时间把每个文件从头到尾看一遍尤其是server/api/trpc.ts和server/db.ts这两个文件是整个类型安全链路的起点。搞清楚一次调用从浏览器到数据库再返回的完整路径后面写任何业务代码都会顺手很多。遇到问题时不慌用前面那章速查表逐条找就行。我也还在继续维护这个项目后续大概率会加入多租户和更完整的权限示例但核心的简洁风格短期内不会变。
t3code 这个项目名第一次看到的人可能以为是个代码编辑器或者代码生成器实际上它是我整理的一个全栈项目模板核心技术栈是 The T3 Stack 那一套Next.js、TypeScript、tRPC、Prisma、Tailwind CSS。t3code 这个名字既点明了 T3 技术栈又暗含“代码怎么写才更舒服”的意思所以我把平时做业务项目里重复性最高的认证、数据库建模、API 路由、样式封装全部整合到了一起。这篇东西会围绕 t3code 展开从选型逻辑讲到落地实现再讲到部署和排坑完全按照我自己实操时的状态来写。t3code 适合谁如果你已经会基础的 React 和 Node.js下一步想自己搭一个类型安全的全栈应用又不想每次手动把 Next.js、Prisma、tRPC 黏在一起那这个项目就是一个可以直接照着抄的完整答案。它能帮你解决从数据库字段到前端页面展示中间那一大堆胶水代码把“端到端类型安全”从概念变成真正能运行的工程框架。先说一下 T3 Stack 的设计逻辑再逐层拆 t3code 的实现细节这样就算你之前没接触过 tRPC也能看懂后面每一段代码在干什么。1. t3code 是什么我为什么决定做这样一个全栈项目1.1 T3 技术栈的核心并不只是“三个字母”T3 Stack 这个名字最初来自社区里一个很流行的全栈组合核心成员包括 Next.js、TypeScript、tRPC、Prisma、Tailwind CSS。它并不是一个官方框架而是一套“最符合现代全栈开发习惯”的选型组合。T3 背后的理念我一直很认同与其在前后端之间各写一套类型定义不如用一套代码把类型从数据库一路传到浏览器。我自己在早期项目里吃过不少类型不同步的亏。前端定义User接口后端再定义一份Usermodel数据库里还有一张users表三份定义各改各的某次接口改字段名忘了同步前端编译不报错运行时拿到undefined排查了一下午才找到问题。t3code 想解决的就是这个痛点Prisma 里定义 schematRPC 用类型推导自动生成 API 类型Next.js 组件里直接 import 类型来用三处变成一处字段增删改都有编译器盯着。很多人以为 T3 Stack 就只是“把工具堆一起”其实关键在于类型信息如何流动。不能说因为大家都用 Next.js 就选 Next.js真正让这套组合成立的是 tRPC 和 Prisma 之间的天然配合。Prisma 根据数据库 schema 生成类型tRPC 的 router 定义又基于这些类型推导出完整的输入输出结构。前端调用远程方法时就像调用本地函数一样有提示这种体验在传统 REST API 体系里很难做到。1.2 t3code 的目标与适用场景t3code 不是一个什么都能装的“全家桶框架”它更像是一个有明确边界的起点项目。我给它定的目标有三条第一开箱即用git clone 下来后执行安装命令就能跑起来第二类型安全贯穿全链路不确定类型的代码不应该出现在业务代码里第三代码量要足够少让新人能在一天内看完所有源码。适用场景也很清晰。第一个场景是个人全栈项目的起步模板比如做一个小工具网站、作品集、内部管理系统用 t3code 可以直接把基础架构搭好把注意力留给业务。第二个场景是团队做原型验证产品经理给了一个新需求大家不想从零搭工程t3code 可以在一小时内跑通完整链路包括数据库建表、页面展示、增删改操作。第三个场景是学习交流很多人想学 tRPC 但不知道从哪里开始看最小示例又太简陋看大型项目又太复杂t3code 的代码量处于一个比较适合阅读的中间档位。当然如果你要做的是一个高并发、重缓存、需要复杂消息队列的中大型系统t3code 不适合直接当底座。它不会替你做权限系统、不会帮你拆微服务、不会内置消息推送。这些超出范围的东西一概不碰宁可保持工程的简洁也不要把脚手架变成笨重的框架。1.3 它比 create-t3-app 多做了哪些实际的工作很多朋友看到这里会问直接用create-t3-app不就行了吗为什么还要维护一个叫 t3code 的项目这个问题的答案很实在。create-t3-app生成的是初始骨架解决的是“项目能不能跑起来”的问题t3code 解决的是“项目里有没有一套可以直接复用的业务基础和代码风格”的问题。具体来说我在 t3code 里预设了几个常用模块一个基于 NextAuth 的凭证登录功能支持注册、登录、退出一套统一响应的 tRPC 错误处理中间件一个 Prisma 模型示例包含用户、会话和管理后台核心表页面侧还做了一个带主题切换的布局组件Tailwind 的配置也做了工程化拆分。这些代码并不是网上随意抄来的片段而是我在几个真实项目里反复调整出来的稳定版本。create-t3-app 能让你在几分钟内拥有一个干净工程但接下来你仍然需要自己去接认证、去设计错误处理、去写布局这些工作占用的时间和写业务代码差不太多。t3code 把这一步预置好了相当于从“毛坯房”升级成了“拎包入住”。不过要注意预设的东西越多学习成本也会越高我尽量控制每个模块只保留一个主流实现不搞多种方案并存这样看代码时不会觉得混乱。2. 技术选型取舍与项目骨架2.1 为什么是 Next.js App Router 而不是 Pages Routert3code 使用 Next.js App Router这一点不是跟风而是看完实际收益后做出的选择。App Router 带来的最大改变是目录结构即路由app目录下的page.tsx、layout.tsx、loading.tsx各自承担渲染职责代码组织方式比 Pages Router 的pages/api和pages双目录要清晰很多。从服务端组件和客户端组件的划分来讲App Router 也给了更明确的边界。我可以在服务端组件里直接读取数据库数据并预渲染把需要交互的部分单独隔离成客户端组件。类型安全在这个架构下更自然因为服务端组件的 props 天然就是序列化后的数据不需要再额外写 loading 状态除非真的需要在客户端动态获取数据。还有一个非常实际的好处Next.js 15 以后对 App Router 的支持越来越稳很多第三方库的 SSR 兼容方案都已经默认适配 App Router。如果现在做新项目还用 Pages Router可能短期内看不出问题但接下来新功能迭代和老库更新都会越来越偏向新路由模式。我不建议老项目立刻迁移但是新项目比如 t3code直接用 App Router 是更长远的选择。2.2 Prisma SQLite/Postgres 的权衡数据层我选了 Prisma没有选 Drizzle ORM也没有直接写 SQL。原因很简单Prisma 的 schema 文件足够直观团队里哪怕是刚接触 ORM 的成员也能根据 model 定义看懂表结构同时它自带 migration 工具能生成 SQL 迁移文件方便 review。数据库方面t3code 默认支持 SQLite 和 PostgreSQL 两种配置。SQLite 用于本地开发和个人小项目零配置文件跑起来不用依赖 DockerPostgreSQL 用于生产环境毕竟是实际部署时的主流选择而且和 Prisma 配合得最好。切换数据库的方式只是在.env里改一行DATABASE_URLschema 文件不需要改动除非你用到某些数据库特有类型。这里有个经验值得分享本地开发和线上环境尽量保持同一种数据库。如果本地用 SQLite线上用 PostgreSQL很多 SQL 方言差异会在上线后突然出现比如字段类型、索引行为、事务隔离级别都会有微妙区别。t3code 虽然支持混合开发但我在自己的使用习惯上是能统一就统一实在不行就用 Docker 在本地起一个 PostgreSQL 实例。2.3 目录结构与配置入口解读t3code 的目录结构是我花了不少时间调出来的既要符合 Next.js 的默认约定又要让业务模块边界清晰。核心部分长这样t3code/ ├── app/ │ ├── (auth)/ │ │ ├── login/ │ │ └── register/ │ ├── (dashboard)/ │ │ ├── projects/ │ │ └── settings/ │ ├── api/ │ │ └── trpc/ │ └── layout.tsx ├── components/ │ ├── ui/ │ └── shared/ ├── server/ │ ├── api/ │ │ ├── routers/ │ │ └── trpc.ts │ ├── auth.ts │ └── db.ts ├── prisma/ │ ├── schema.prisma │ └── seed.ts └── trpc/ ├── client.ts └── server.tsapp/(auth)和app/(dashboard)是两组路由组它们不产生真实的 URL 前缀只用于把登录页面和主页面分开。server/api/routers放 tRPC 的各个路由模块trpc/client.ts和trpc/server.ts是类型导出的关键入口。这样的结构让我在加新功能时很明确页面文件去app里加UI 组件去components里加数据接口去routers里加数据库表去prisma里改不会出现文件乱放的问题。很多项目搭建初期不重视目录规范等到文件多了以后开始到处找代码严重的还会出现循环依赖。t3code 里我用了一个简单的依赖规则app层可以引入components和trpccomponents和trpc可以引入server但是server层不能反向引入components。这条规则写进 README 之后团队协作时的沟通成本低了很多。3. 从零搭建 t3code 的关键步骤与实现细节3.1 初始化项目与基础配置开始之前你需要准备 Node.js 20 以上版本和包管理器 pnpmnpm 也能用只是 pnpm 在依赖安装速度和严格模式下更适合这种工程。初始化可以直接用create-t3-app也可以手动搭。我建议初学者先跑一次官方脚手架看看它默认生成的文件结构再用 t3code 的代码对照理解。第一步是创建项目目录和初始化 package.jsonmkdir t3code cd t3code pnpm init然后安装核心依赖pnpm add next react react-dom tanstack/react-query trpc/server trpc/client trpc/react-query trpc/next prisma/client zod superjson pnpm add -D typescript types/node types/react types/react-dom prisma tailwindcss postcss autoprefixer eslint eslint-config-next这里有个很容易犯的错superjson不能漏。tRPC 默认只能序列化 JSON 能表达的数据但Date、BigInt这类对象需要特殊处理。superjson是一个扩展序列化库它让 tRPC 可以传输这些复杂类型少装了这个包即使代码编译通过运行时也会出现序列化错误。安装完成后在.env里配置数据库连接本地开发我用 SQLiteDATABASE_URLfile:./dev.db NEXTAUTH_SECRETdev-secret-please-change NEXTAUTH_URLhttp://localhost:3000NEXTAUTH_SECRET 在本地开发时可以随便写但上线前必须改成足够随机的字符串。我习惯用openssl rand -base64 32生成比手敲键盘可靠得多。3.2 数据库模型设计与 Prisma 迁移t3code 里我设计了三个最常用的模型用户、会话、项目。用户和会话是认证模块需要的基础表项目是用来演示 tRPC CRUD 操作的业务表。Prisma 的 schema 很长我只把最关键的部分拉出来看model User { id String id default(cuid()) email String unique passwordHash String name String? projects Project[] sessions Session[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Project { id String id default(cuid()) title String content String? status Status default(ACTIVE) ownerId String owner User relation(fields: [ownerId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt } enum Status { ACTIVE ARCHIVED }字段类型这里我推荐 String 配 cuid而不是自增 Int。自增主键在单体应用里没什么问题但一旦以后拆表、做数据合并或者暴露 ID自增数字很容易被猜到数量。cuid 虽然长了一点但分布均匀在分布式场景下也能避免冲突。写完 schema 后执行pnpm prisma migrate dev --name init pnpm prisma generatemigrate dev会创建迁移文件并更新本地数据库generate会基于 schema 生成 TypeScript 客户端类型。有个细节每次改 schema 后都要重新generate否则 Prisma 客户端还是旧类型如果你发现代码里访问不到新增字段多半是忘了这一步。3.3 tRPC Router 的编写与 React Query 集成tRPC 的写入方式非常直观一个 router 就是一组方法的集合。t3code 里对 Project 的操作长这样// server/api/routers/project.ts import { z } from zod; import { createTRPCRouter, protectedProcedure } from ../trpc; export const projectRouter createTRPCRouter({ list: protectedProcedure .query(({ ctx }) { return ctx.db.project.findMany({ where: { ownerId: ctx.session.user.id }, orderBy: { createdAt: desc }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().optional() })) .mutation(({ ctx, input }) { return ctx.db.project.create({ data: { title: input.title, content: input.content, ownerId: ctx.session.user.id, }, }); }), });这里有两个概念需要区分query用于读数据mutation用于写数据。React Query 会根据这个区分决定缓存策略和重试策略。query 的结果会被缓存组件重新挂载时不会重复发请求mutation 执行成功后需要让相关 query 失效否则页面上会显示旧数据。在 React 里调用时会自动生成类型安全的 hooksimport { api } from ~/trpc/react; const { data: projects, refetch } api.project.list.useQuery(); const createProject api.project.create.useMutation({ onSuccess: () { refetch(); }, });api.project.list这层链路就是端到端类型安全的体现前端不需要单独写接口路径字符串也不需要在外部再维护一份请求函数。改后端方法的 input 或输出类型前端调用处立即提示编译错误这是 t3code 最值回票价的特性。3.4 Tailwind 主题定制与响应式页面样式方面 t3code 用的是 Tailwind CSS 4相比 v3 最大的变化是配置方式从tailwind.config.js部分转移到了 CSS 变量里。t3code 的全局样式文件会定义一组主题颜色和语义 tokenimport tailwindcss; theme { --color-primary: #6366f1; --color-surface: #f8fafc; --color-text: #0f172a; }定义完theme之后页面里可以直接用bg-primary、text-text这类类名。很多朋友会纠结色值定义我的建议是先定两套模式一套浅色一套深色用 CSS 变量做桥接后续调整皮肤只改变量不用改组件类名。t3code 的布局组件里就做了一个简单主题切换原理是把>// server/db.ts 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; }这段代码几乎是 Next.js Prisma 项目的惯例了目的就是避免开发时创建多个数据库连接。如果你用的是 t3code 自带的server/db.ts这个处理已经内置好了。如果你是自己搭项目一定要加上否则改一行 schema 后热更新数据库连接数会肉眼可见地增长。生产环境还要注意连接池大小。PostgreSQL 默认连接数是 100业务量不大时 Prisma 默认的配置就够了。但如果你部署在 Serverless 环境每个冷启动实例都会建立数据库连接这时建议把连接池调小比如connection_limit5减少数据库压力。4.3 tRPC 类型推断出现 never 或 any 的常见原因tRPC 让人又爱又恨的地方在于类型推断。大多数时候它自动推导得非常好但偶尔你会发现在组件里调用api.project.create.useMutation()时input类型变成any或never这说明类型链路断了。最常见的根源是 router 里没有使用protectedProcedure或publicProcedure这些基础封装而是直接使用某些自定义中间件。tRPC 的类型系统依赖中间件类型能够正确推导如果自己写的中间件返回类型用了any整个 router 的类型就会崩塌。t3code 里我在创建 router 时严格遵守统一封装不直接在文件里写router.procedure的变体。另一个原因是 tsconfig 的 strict 模式没打开或者没有正确配置路径别名。类型推断最怕的就是ts-ignore或as any一旦出现这类代码编译器就无法继续往下推导。我在 t3code 的 tsconfig 里强制开启strict: true并设置了baseUrl和路径别名这样 IDE 和 CI 都能在同一个规则下工作。4.4 一张速查表解决大部分报错为了方便日常开发我把 t3code 里遇到的高频报错整理成了一张表每次出现类似错误先来这里查一遍能省不少排查时间。报错现象可能原因排查步骤推荐解法Prisma 类型里找不到新字段schema 已改但没重新生成客户端执行pnpm prisma generate在 package.json 的 postinstall 里加上prisma generatetRPC 调用显示无此方法router 没有挂载到根 router打开server/api/root.ts检查将新 router 注册到createTRPCRouter({ ... })NEXTAUTH_SECRET报错环境变量缺失检查.env文件本地用开发值线上用随机生成值React 组件提示需要use client使用了useState或事件监听但没标记检查组件顶部按需添加use clientsuperjson序列化 Date 失败服务端和客户端 superjson 版本不一致统一升级版本pnpm add superjsonlatest这张表不是万能药但它能帮你建立条件反射。碰到报错不要急着搜索先看错误信息里的文件和堆栈定位到具体模块后再用表里的思路去查速度比盲目试要快很多。5. 部署到生产环境与后续扩展方向5.1 部署到 Vercel 的配置要点t3code 是 Next.js 项目部署首选的平台自然是 Vercel。流程比较简单把代码推送到 Git 仓库然后在 Vercel 里导入项目它会自动识别 Next.js。需要重点设置的是环境变量包括DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL。如果你用的是 PostgreSQL推荐直接使用 Vercel Postgres 或者 Neon 这类托管数据库。拿到连接字符串后注意DATABASE_URL可能需要加上?sslmoderequire否则某些数据库服务商不接受非 TLS 连接。本地能用不代表线上能连这一步最容易在部署时才发现。Vercel 部署默认是 Serverless 模式每个请求都可能在独立环境里处理所以要注意几个问题文件系统不能作为持久存储临时上传文件要放在对象存储数据库连接要控制并发数依赖安装时需要在postinstall里执行prisma generate不然构建完的产物里没有 Prisma Client。部署完成后可以设置一个 GitHub Action 来做 CIpush 到 main 分支后先跑 lint、typecheck、build再触发 Vercel 部署。这样能避免很多“本地能跑线上崩”的问题。t3code 的仓库里已经附了一个最简版的 CI 配置文件照抄就能用。5.2 还能再往哪个方向扩展t3code 是一个起点之后的扩展方向取决于你实际业务需要。我个人建议优先做这几件事。第一接入 Prisma 的软删除与操作日志。现在的 model 里只有常规字段如果做管理后台需要记录谁在什么时候改了哪条数据可以在 Prisma 中间件或 tRPC 的 middleware 里统一处理。第二增加基于角色的权限控制目前只有登录验证没有区分管理员和普通用户。第三把文件上传接进来比如 S3 兼容存储让 Project 模型可以关联图片和附件。第四补充自动化测试至少给核心 router 写几个集成测试确保数据库操作不会破坏已有数据。不过每次扩展都会增加复杂度。我的原则是先跑通最小闭环再按真实需求加功能不要在项目第一天就把所有东西都规划好。t3code 保持现在这个体积正是为了让后来的人能够清楚地看懂每一步在做什么也可以大胆地按自己的思路去改。最后再聊一点我的真实体会把 t3code 从零搭到可以部署我最大的感受是全栈项目的复杂度并不在于某个单独的技术有多难而在于它们之间的边界需要花心思设计。Next.js 负责做好渲染边界Prisma 负责数据建模tRPC 负责消除前后端类型损耗Tailwind 负责不让样式成为维护负担。每一层单独看都很简单但组合起来真正跑通一轮你对整个现代 Web 应用的运行逻辑会有非常直观的理解。如果你打算拿 t3code 做自己的下一个项目起步模板我建议先别急着改功能花点时间把每个文件从头到尾看一遍尤其是server/api/trpc.ts和server/db.ts这两个文件是整个类型安全链路的起点。搞清楚一次调用从浏览器到数据库再返回的完整路径后面写任何业务代码都会顺手很多。遇到问题时不慌用前面那章速查表逐条找就行。我也还在继续维护这个项目后续大概率会加入多租户和更完整的权限示例但核心的简洁风格短期内不会变。
