1. t3code 到底是什么T3 Stack 全家桶的一次完整落地做全栈开发这些年我一直有个很深的执念前后端类型割裂这件事真的浪费了太多时间。后端改了个字段前端调接口的时候还在按老结构取数据等联调阶段才被 TypeScript 报错砸一脸这种场景想必不少人都经历过。后来我在 GitHub 上刷到 t3code 这个项目第一反应是终于有人把整套 T3 Stack 的实践整理成可直接复用的样板了。t3code 是一个基于 T3 Stack 构建的全栈应用样板工程。T3 这个名字来自社区里非常流行的组合Next.js TypeScript tRPC Tailwind CSS再加上 Prisma 做数据层、NextAuth.js 做认证整套技术选型的目标只有一个——端到端类型安全。什么意思呢你写的数据库查询、API 路由、前端页面调用所有数据结构的类型从 Postgres 表一路贯穿到 React 组件里任何一层改了字段编译器立刻告诉你哪里跟着坏了不用再靠人工维护一份又一份接口文档。我个人更愿意把 t3code 理解成三件事的集合它是一份项目脚手架克隆下来就能跑它是一套最佳实践展示了类型安全全栈应用的标准写法它更是一个学习地图把 Next.js 服务端组件、tRPC 路由、Prisma 建模、NextAuth 会话这些容易绕晕的概念用一条完整业务链路串了起来。适合谁如果你是这么几类人t3code 应该能帮到你对 Next.js 生态有一定了解、但没系统搭过全栈项目的进阶开发者团队准备统一前后端类型契约、想找个落地范本的技术负责人还有那些和我一样受够了联调三小时排错两小时的实战派。接下来我会从技术选型逻辑、工程骨架、数据链路、认证会话、部署上线这几个维度把这个项目的里里外外拆一遍。1.1 T3 这三个字母背后的技术选型逻辑先说 T3 这个名字是怎么来的。它取自The T3 StackT3 是 Third 的缩写核心思想是第三代 Web 开发方式——不信奉复杂臃肿的微服务架构而是把一套类型安全的工具链直接组合在一起让一个全栈开发者用最少的认知开销完成从数据库到界面的全部工作。社区里也有人开玩笑说它代表 TypeScript 狂魔的福音因为这套技术栈把 TypeScript 的能力用到了极致。每个组件解决什么问题我这里直接给一个对照表。组件职责为什么选它Next.js应用框架渲染层 API 路由服务端组件和客户端组件放在同一套代码里SEO 和交互体验兼顾TypeScript静态类型系统所有类型安全的基石没有它就谈不上端到端安全tRPCAPI 层替代传统 REST 接口前后端共享类型定义不用手写 URL、不用生成 SDK调用远程函数像调用本地函数Tailwind CSS样式方案原子化 CSS 类名不用切换文件写样式开发效率高样式体积可控Prisma数据库 ORMSchema 即类型来源迁移有版本管理查询自动带类型提示NextAuth.js认证方案和 Next.js 深度集成支持 OAuth 和 Credentials 两种主流登录方式这套组合里最吸引人的是 tRPC。传统 REST 架构下前端要拿/api/user/123你得知道 URL 长什么样、参数怎么传、返回结构是什么通常靠手写接口文档或者从 Swagger 复制类型。tRPC 的逻辑完全相反后端定义好 Router前端直接引用同一个类型定义然后像调用本地函数一样发起请求// 后端定义 const userRouter router({ getById: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) { return await ctx.prisma.user.findUnique({ where: { id: input.id }, }); }), }); // 前端调用类型自动推断 const user trpc.user.getById.useQuery({ id: 123 }); // user.data 的类型就是 Prisma 返回的 User | null写错字段立刻报错这就是 tRPC 颠覆认知的地方不再有接口这个概念取而代之的是一个个可被安全调用的服务端函数。你不在前端写fetch(/api/xxx)不用管序列化格式所有校验、错误、类型都在编译期和运行时被兜住。1.2 t3code 在 T3 Stack 之外的补充能力T3 Stack 本身只是工具链但 t3code 这个项目作为样板还额外补齐了很多真实项目里绕不开的东西。我把它拆成四点。第一是可替换的认证方案。T3 默认推荐用 NextAuth 的 GitHub 等 OAuth 方案但 t3code 里我看到它把 Credentials邮箱密码登录也做了完整实现包括密码哈希用的 bcrypt、Session 回调、登录页和注册页。这对国内团队或者内网系统特别重要毕竟不是所有业务场景都有 GitHub 账号让用户去授权。第二是数据库设计已经帮你踩了坑。样板里通常包含一个完整的 Prisma Schema比如用户表、会话表、账号表和某条业务数据表字段设计考的了 upsert、外键关系、索引这些细节。你没有从零设计表结构的压力删掉不用的部分改成自己的业务字段就能开工。第三是响应式界面和组件库选型。t3code 用的是 Tailwind shadcn/ui 这套组合组件以源码形式直接放在项目里想改样式随手改没有组件库版本升级导致 API 变化的焦虑。页面布局、导航栏、表单、表格这些高频组件都给你备好了不用每次开工都从白屏开始。第四是可复用的项目目录约定。比如 Server 端代码放在src/server前端组件放在src/componentsAPI 路由按领域拆分 router公共工具和类型定义集中管理。对于没怎么看过大型 Next.js 项目结构的开发者来说这个目录本身就是一套最佳实践模板跟着它写就能保持清晰的工程边界。一句话总结 t3code 的定位它不是一个产品而是一个带完整业务链路的 TypeScript 全栈应用基座。想快速验证新点子或者给团队树立一个项目结构参照物你都可以直接拿它起跑。2. 从零搭建 t3code工程骨架与核心目录拆解2.1 初始化脚手架直接用 create-t3-app 还是手搭这一步有两条路直接用社区成熟的 create-t3-app 脚手架或者手动把依赖一个个装进来。我的经验和建议是第一遍先用 create-t3-app但一定要在生成后把每一层配置翻一遍搞清楚每个文件是干什么用的再考虑手动搭。用脚手架初始化只需要一条命令npx create-t3-applatest t3code交互式选项那里按下面这个组合选比较省心TypeScript: 选 Yes这是整套技术栈的地基Tailwind CSS: 选 Yes样式方案后续全靠它tRPC: 选 Yes没有 tRPC 就不叫 T3 了Prisma: 选 Yes数据层必须有类型来源NextAuth: 选 Yes认证功能后面会用到App Router: 选 Yes这是 Next.js 当前的主流模式Docker: 如果你是做部署推荐选上本地纯学习可以先不选生成完之后先别急着写业务代码我强烈建议执行一次npm run dev把默认页面在浏览器里过一遍。确认脚手架能跑通后面出了问题你才知道是自己改坏的还是环境本身有问题。那什么时候可以考虑手搭当你已经跑通了脚手架项目并且对 Next.js 的路由规则、Tailwind 的内容配置、tRPC 的 server 端初始化逻辑都很熟悉了再手搭也不迟。手搭的好处是依赖精简、没有脚手架里的样板噪音适合做公司内部定制化骨架。但第一次接触 T3 的开发者不建议走这条路省下的几分钟初始化时间会在后续排查环境问题上加倍还回去。2.2 目录结构与数据流看懂 t3code 的代码组织脚手架生成后核心目录结构大概是这样的t3code/ ├── prisma/ │ ├── schema.prisma │ └── migrations/ ├── src/ │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ │ ├── post.ts │ │ │ │ └── user.ts │ │ │ ├── trpc.ts │ │ │ └── root.ts │ │ └── auth.ts │ ├── trpc/ │ │ ├── server.ts │ │ └── react.tsx │ ├── app/ │ │ ├── layout.tsx │ │ ├── page.tsx │ │ ├── login/page.tsx │ │ ├── register/page.tsx │ │ └── api/ │ │ ├── auth/[...nextauth]/route.ts │ │ └── trpc/[trpc]/route.ts │ ├── components/ │ └── env.js └── next.config.js这个目录最有价值的一点是服务端代码和前端组件的边界非常清晰。src/server下面放 Prisma 实例、tRPC Router、认证配置这部分代码永远不会被打进浏览器端 bundle。src/trpc则负责把服务端的 Router 类型传输给前端让 React 组件能安全调用远程函数。src/app是 Next.js App Router 的页面目录每个文件夹就是一个路由page.tsx是对外可见的页面layout.tsx是共享布局。数据流是我经常拿来跟团队讲的一条龙用户在浏览器点击按钮 - React 组件调用trpc.post.getAll.useQuery()- 请求走到app/api/trpc/[trpc]/route.ts的统一入口 - tRPC 根据请求路径找到对应的 Router 函数 - Prisma 查询数据 - 结果按类型返回 - 前端拿到带完整类型结构的数据渲染到组件里。全程没有手写一行fetch、没有一个未知的any。2.3 环境变量与全局配置提前想清楚才能少踩坑t3code 这种全栈项目尤其吃环境变量因为它同时连着数据库、认证服务、可能还有第三方 API。我用项目里最关键的三组环境变量做个例子。# .env DATABASE_URLpostgresql://postgres:passwordlocalhost:5432/t3code NEXTAUTH_SECRET生成一个足够长的随机字符串 NEXTAUTH_URLhttp://localhost:3000第一组DATABASE_URL很好理解Prisma 连数据库用。我在本地习惯用 Docker 起 PostgreSQL一条命令就够docker run --name t3-postgres -e POSTGRES_PASSWORDpassword -p 5432:5432 -d postgres:16第二组是 NextAuth 的配置。NEXTAUTH_SECRET千万别用123456这类简单值它可以用来加密 Session 和 Cookie如果有心人拿到了这个值就可能伪造登录状态。生成方式很简单终端里执行openssl rand -base64 32复制结果就行。NEXTAUTH_URL在本地是http://localhost:3000上生产环境得改成真实域名。第三组是有没有第三方服务。如果准备支持 GitHub 登录还需要GITHUB_CLIENT_ID和GITHUB_CLIENT_SECRET这得到 GitHub OAuth App 后台申请。申请的时候注意授权回调地址要写成http://localhost:3000/api/auth/callback/github写错了登录几乎百分百会报redirect_uri错误。这里要提醒一下新接触 Next.js 生态的朋友环境变量文件的约定非常严格。.env是所有人共享的默认值库.env.local是本机私有配置.env.production只在生产构建时使用。任何不确定含义的变量先查代码里在哪里被读取再往文件里加别一股脑全堆进去。注意.env文件千万别提交到 Git 仓库生产环境的密钥如果泄漏后果不堪设想。脚手架默认会在.gitignore里把.env*排除掉但如果你是从老项目的基础上改造建议检查一下忽略规则是否生效。3. 数据层与 API 层Prisma 建模和 tRPC 类型安全的完整配合3.1 Prisma Schema 设计与迁移流程在 t3code 里Prisma Schema 是数据类型的唯一来源字段长什么样前端最终拿到的类型就是什么样所以建模阶段一定要想清楚。我以博客场景为例给出一个设计相对完整的 User 和 Post 模型。// prisma/schema.prisma generator client { provider prisma-client-js } datasource db { provider postgresql url env(DATABASE_URL) } model User { id String id default(cuid()) name String? email String? unique emailVerified DateTime? image String? passwordHash String? posts Post[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Post { id String id default(cuid()) title String content String published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt index([authorId]) }几个容易被忽略的点。id字段用cuid()而不是autoincrement()因为 CUID 不需要数据库自增分布式环境下生成 ID 不会撞车也更安全、不易被遍历猜测。User.email字段标了unique但保留name、image、emailVerified这些字段是为后面对接 OAuth 预留的。NextAuth v5 的 Prisma Adapter 对 User 表和 Account 表有固定的字段约定如果缺字段登录功能会报字段找不到的错误。posts和author是一对多的关系字段。这个关系定义很关键它让 Prisma 查询时可以像访问对象属性一样连表const postsWithAuthor await prisma.post.findMany({ include: { author: true }, });写完 Schema 后执行两条命令生成表结构和 Client 类型npx prisma migrate dev --name init npx prisma generatemigrate dev会在prisma/migrations目录下生成带版本号的 SQL 文件以后数据库长什么样全看这套迁移记录。prisma generate则根据 Schema 生成 TypeScript 类型前端拿到的Post类型就是从这段 Schema 来的。实战提示migrate dev只适合开发环境。生产环境做结构变更时应该先把 migration SQL 文件提交到代码仓库然后在服务器上执行prisma migrate deploy避免直接改线上数据库导致迁移历史错乱。3.2 tRPC Router 的拆分与复用从 hello 到业务模块tRPC 的 Router 可以理解成一份后端函数的注册表。t3code 默认把 Router 拆成了多个模块文件然后在根 Router 里合并这个习惯在项目变大以后收益非常明显。src/server/api/trpc.ts是 tRPC 实例的初始化文件里面做了几件重要的事创建 tRPC 上下文、定义中间件、声明受保护路由。// src/server/api/trpc.ts import { initTRPC, TRPCError } from trpc/server; import superjson from superjson; import { ZodError } from zod; import { getServerAuthSession } from /server/auth; export const createTRPCContext async (opts) { const session await getServerAuthSession(); return { session, prisma, }; }; const t initTRPC.contexttypeof createTRPCContext().create({ transformer: superjson, errorFormatter({ shape, error }) { return { ...shape, data: { ...shape.data, zodError: error.cause instanceof ZodError ? error.cause.flatten() : null, }, }; }, }); export const publicProcedure t.procedure; export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { ...ctx, user: ctx.session.user } }); });这段代码里有个非常核心的设计protectedProcedure。凡是需要登录才能访问的接口直接把publicProcedure换成protectedProcedureRPC 内部就会检查 Session没登录直接抛UNAUTHORIZED。因为类型是共享的前端调用时也能感知到这个接口是不是需要认证不会出现前端拿不到数据还不知道为什么的情况。从 t3code 的实践来看Router 模块按业务域拆比按用户/订单/商品这类资源拆更合理。比如文件上传和文件列表虽然都跟文件相关但上传属于写入域列表属于读取域它们的鉴权要求、输入校验完全不同拆成两个独立的 router 反而好维护。3.3 Zod 校验与类型推断一条数据从浏览器到数据库的完整链路Zod 在 T3 技术栈里扮演两个角色运行时校验器 类型推断器。很多时候新手容易忽略 Zod觉得反正 TypeScript 已经约束了类型还要桂运行时干嘛这个想法在真正的生产环境是要吃亏的。类型系统只在编译期有效而程序跑起来以后的输入——比如用户提交的表单——编译期根本看不见。REST 架构下你在后端每个接口里手写参数校验逻辑写多了还容易漏。Zod 把校验规则和类型定义合并到一次声明里代码天然是自文档化的。我拿典型的注册新用户场景演示完整链路。// 后端 Router 的定义 import { z } from zod; const registerSchema z.object({ email: z.string().email(), password: z.string().min(8).max(32), name: z.string().min(2).max(20), }); export const authRouter router({ register: publicProcedure .input(registerSchema) .mutation(async ({ ctx, input }) { const exists await ctx.prisma.user.findUnique({ where: { email: input.email }, }); if (exists) throw new TRPCError({ code: CONFLICT }); const hashed await bcrypt.hash(input.password, 10); return ctx.prisma.user.create({ data: { email: input.email, name: input.name, passwordHash: hashed }, }); }), });这是后端完整的一次处理Zod 先校验参数格式非法格式返回详细错误列表然后查重、给密码加盐哈希、落库。到了前端调用代码不需要任何额外类型标注。const registerMutation trpc.auth.register.useMutation(); // 提交时 registerMutation.mutate({ email, password, name }, { onError: (err) { // err.data?.zodError 里带着每个字段的具体错误信息 }, });这里useMutation返回的mutate函数参数类型正是后端的registerSchema。由于类型是引用关系你改后端 Schema 的长度限制前端表单校验的提示类型会同步更新这就是端到端类型安全最直观的体验。我曾经花过一晚上排查前端明明传了值后端却说字段为空的问题最后发现是两边校验规则不一致造成的用了 Zod 共享校验之后这类问题直接绝迹。4. 认证与前端渲染NextAuth 会话管理 Tailwind 页面搭建4.1 NextAuth 接入Credentials 与 OAuth 两种方案的取舍认证是全栈项目绕不过去的一块硬骨头t3code 的两套方案我都实际跑过说说我选型的判断逻辑。OAuth 方案比如 GitHub、Google 登录用户体验好、不用自建密码找回体系、安全由平台方兜底。它适合面向公众用户的网站。首次集成要申请的流程略复杂需要注册 OAuth App、配置回调地址、处理state参数防 CSRF但 NextAuth 已经把大部分工作封装好了用在 t3code 上属于开箱即用。Credentials 方案邮箱密码实现完全自主适合企业内部系统、后台管理这类用户群体可控的场景。难点在密码存储、登录限流、防爆破这些安全细节都要自己把关。t3code 默认实现里用了 bcrypt 对密码做哈希但没有内置限流逻辑生产环境建议在外面套一层 Redis 或者在应用层做失败次数统计。两种方式在代码里的形态不同。OAuth 只需要在 NextAuth 配置里声明 Provider然后前端跳转到/api/auth/signin即可// src/server/auth.ts import NextAuth from next-auth; import GitHub from next-auth/providers/github; export const { handlers, auth, signIn, signOut } NextAuth({ providers: [ GitHub({ clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, }), ], });Credentials 则需要自定义校验函数import Credentials from next-auth/providers/credentials; providers: [ Credentials({ credentials: { email: {}, password: {} }, authorize: async (credentials) { const user await prisma.user.findUnique({ where: { email: credentials.email as string }, }); if (!user) return null; const ok await bcrypt.compare(credentials.password as string, user.passwordHash ?? ); if (!ok) return null; return { id: user.id, name: user.name, email: user.email, image: user.image }; }, }), ],4.2 服务端组件与 tRPC 的配合避免页面白屏与状态丢失Next.js 的 App Router 默认所有组件都是服务端组件Server Component这意味着你可以直接在服务端读取 Session、查询数据库再把处理过的数据传给子组件。这个特性让 t3code 的页面写起来非常清爽。比如受保护的仪表盘页面// src/app/dashboard/page.tsx import { auth } from /server/auth; import { redirect } from next/navigation; import PostList from /components/PostList; export default async function DashboardPage() { const session await auth(); if (!session?.user) { redirect(/login); } return PostList userId{session.user.id} /; }这段代码没有多余的认证状态判断请求直接由服务端决定「能不能进」进不了就重定向。相比传统客户端渲染的 SPA服务端组件的优势是首次加载时 HTML 就已经就位用户不会看到白屏闪烁对 SEO 也更友好。但要特别提醒一个 tRPC 在 App Router 下的使用差异服务端组件里不要直接调用trpc.post.getAll.useQuery()。因为useQuery是 React Hooks 体系的一部分本质上是给客户端组件用的。服务端组件想取数据直接调 Prisma 或 tRPC Router 的内部函数就可以没必要再绕一层 HTTP。t3code 推荐的做法是路由页面Server Component负责拿数据列表、表单这些组件Client Component负责交互逻辑两边的数据通过 Props 传递。4.3 Tailwind shadcn/ui快速搭建无设计稿的可维护界面前端界面我试过好几条路线——从纯手写 CSS 到引入 antd 组件库再到 Tailwind shadcn/ui现在的结论是后者最适合 T3 全家桶。Tailwind 的原则是原子类名直接堆写样式不打文件切换bg-blue-500、px-4、rounded-lg这些类名当场就能看见效果。一开始会觉得类名很长、HTML 变丑但配合编辑器插件和组件抽象以后实际写下来比其他方案都要快。shadcn/ui 就更特别了它不是一个传统意义上的组件库而是一堆可以直接复制进你项目的源码组件。放在 t3code 里使用时先把基础配置跑一遍npx shadcnlatest init npx shadcnlatest add button input card form table初始化后会在src/components/ui生成组件目录每个组件的源码就在项目里想改样式直接改。比如默认按钮是圆角灰色你改成圆角更大、带渐变的风格不会受组件库版本更新的影响。这点对于做公司内部系统特别友好——你可以基于它定制出自己团队的设计规范而不是被第三方 UI 库的设计语言绑死。我用 shadcn/ui 给 t3code 搭过一个带登录页、列表页、详情页的管理后台加一个表格筛选功能大概半天就完成了因为表单校验、错误提示、加载状态这些组件都帮我处理好了只需要把 Zod 校验规则传进去。5. 上线部署与真实环境排查t3code 从开发到 Docker 的最后一公里5.1 Docker 多阶段构建与镜像体积优化本地跑通只是第一步把 t3code 放到服务器上才算真上线。t3code 的部署方案我强烈建议用 Docker 多阶段构建可以大幅减小镜像体积也能避免开发环境和生产环境的依赖不一致问题。标准的 Dockerfile 大概是下面这个思路。# 第一阶段安装依赖并构建 FROM node:20-alpine AS builder WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npx prisma generate RUN npm run build # 第二阶段生产环境镜像 FROM node:20-alpine AS runner WORKDIR /app ENV NODE_ENVproduction COPY --frombuilder /app/node_modules ./node_modules COPY --frombuilder /app/.next ./.next COPY --frombuilder /app/package.json ./package.json COPY --frombuilder /app/prisma ./prisma COPY --frombuilder /app/public ./public EXPOSE 3000 CMD [npm, run, start]有几个细节值得展开。npm ci和npm install的区别是前者完全按package-lock.json安装保证生产环境和 CI 的依赖版本一致构建失败的概率更低。npx prisma generate必须在npm run build之前执行因为 Next.js 编译时会把 Prisma Client 的类型一起打包如果不生成构建会报找不到PrismaClient 之类的错误。这个顺序错误我在早期部署时踩过第二次就长记性了。多阶段构建真正受益的地方是最终镜像里只有生产依赖和构建产物开发时的源码、临时文件都被丢弃了。如果你是直接把整个node_modules复制过去镜像体积轻轻松松超过 1GB而多阶段构建的 t3code 镜像能控制在 300MB 左右。5.2 环境变量、Prisma Client 生成与迁移的部署顺序Docker 部署最头疼的是环境变量和数据库迁移的顺序问题。我给一套已经验证过的执行顺序拉取代码到服务器创建.env.production文件填好DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL执行npx prisma migrate deploy这一步只应用代码仓库里的迁移文件执行新的表结构变更构建 Docker 镜像并启动容器。有一个容易忽略的坑如果DATABASE_URL指向的是远程数据库要确认数据库的 IP 白名单或者安全组是否允许服务器的出口 IP 访问。很多人在本地连数据库没问题上了服务器反而connect ECONNREFUSED十有八九就是网络访问限制的问题。另外Next.js 属于 Node.js 服务环境变量在构建时会被编译进客户端代码。这意味着如果你在 Docker 构建时设置了AUTH_SECRET是构建时读进去的运行时再改环境变量对已经编译好的客户端代码是不生效的。所以部署时尽量减少同一变量、不同环境、不同值这种情况或者干脆用统一的变量名避免起混淆。5.3 常见问题速查表与排错思路最后把我在实际使用 t3code 过程中频繁遇到的问题整理成一张排查表。这些问题都是真实踩过的按频率从高到低排。现象可能原因排查步骤页面报PrismaClientInitializationErrorPrisma Client 未生成执行npx prisma generate后重启开发服务器登录报redirect_uri错误OAuth 回调地址不匹配比对 NextAuth 配置里的NEXTAUTH_URL与 OAuth 后台的回调地址数据库连接connect ECONNREFUSEDPostgreSQL 未启动或网络不通先docker ps确认容器状态再检查 DATABASE_URL 的端口和主机名类型报错Property xxx does not exist修改了 Prisma 模型但还没同步类型重新执行npx prisma generate让 TypeScript 类型感知最新 Schema客户端请求一直401 Unauthorized没登录就访问了受保护接口检查前端是否遗漏了登录态或者 Session 过期尝试重新登录NEXTAUTH_SECRET提示缺失未配置或值不规范用openssl rand -base64 32生成强随机值补上Docker 构建内存不足OOMKilledNext.js 构建阶段内存占用高在 Docker 配置里调大内存限制或构建时加NODE_OPTIONS--max-old-space-size2048页面白屏控制台报 Hydration 错误服务端渲染和客户端渲染不一致检查组件里是否有依赖window的渲染逻辑条件渲染时确保两边结果一致排查这类问题的通用思路是先看服务端日志docker logs -f 容器名再去看 tRPC 返回的具体错误结构最后用 Prisma Studio 直接确认数据库里有没有这条数据。多数数据不对的问题其实在数据库这一层就能看到真相。6. 从 t3code 出发后续扩展与我的实际体会6.1 从 Demo 到业务系统t3code 可以怎么长t3code 作为样板工程只是起步它真正的价值在于能支撑你往上长出完整的业务系统。我给几个已经实践过的扩展方向。多模块 router 扩展目前默认只有一个auth和post类 router。业务一复杂应该在src/server/api/routers下面按业务域继续加文件比如order.ts、product.ts、payment.ts然后在根 router 里用mergeRouters组合。tRPC 对 router 树没有层级上限命名空间清晰代码规模翻几倍也不会乱。文件上传能力默认 t3code 没有接入对象存储但现实中头像、附件这些需求很常见。我建议引入一个独立的 upload router前端直传对象存储比如 S3或走后端中转统一在 router 层做文件大小、文件类型的校验。上传链接和业务数据的关联就靠 Prisma 表里的 URL 字段维护。后台管理权限如果要做管理后台在protectedProcedure的基础上再加一个adminProcedure就行中间件里检查当前用户的角色字段。T3 技术栈下做 RBAC 权限体系非常顺手类型安全让角色定义和接口访问控制天然绑定在一起。性能监控与日志开发阶段控制台随便看生产环境不行。t3code 可以在 server 端加一层日志中间件记录每个 RPC 调用的耗时、错误率再把日志推送到日志平台。这一步不会影响业务代码但上线之后排查线上问题全靠它。6.2 我在实际使用中的几个体会最后说点我个人最真实的感受。第一次跑通 t3code 的时候我最大的震撼不是功能很全而是前后端联调变得没有存在感了。以前写完前端接口文档、后端再对着文档实现中间来回核对字段名是不是拼错、负责人是谁、联调谁改谁等着这些摩擦全部消失。你改一行 Schema全链路类型立刻跟着变这种编译器帮你盯着全局的踏实感用习惯了是真回不去的。第二个体会是框架的组合拳比单点工具重要。单独用 Next.js、单独用 Prisma 你都能干成事但把它们按 tRPC 串起来产生的是乘法级的效率提升不是加法。t3code 其实就是这套组合拳的示范它用一条真实业务链路把所有环节打通了而不是给你一堆互不相干的技术片段。最后再分享一个小技巧每次改完数据库模型随手执行npx prisma generate然后顺手看一眼 Prisma Studio 里的实际数据。很多前端类型报错、运行时字段缺失源头其实在数据模型和真实数据不一致上。养成这个习惯以后你花在排查字段明明存在为什么取不到上的时间会少很多。想快速上手 T3 系列我的建议很简单把 t3code 克隆到本地跟着把每一层代码读一遍然后删掉默认的业务数据改成你自己的业务模型。一遍跑通以后你会发现全栈开发原来可以这么清爽。