我起项目代号很随意，但工具链一点都不随意。t3code这个项目名，来自我去年在团队内部做技术分享时随手起的代号——t3取自T3 Stack，code则因为整个项目从数据层到界面层全部围绕类型安全的代码链路展开。说白了，t3code就是我基于TypeScript、Next.js、tRPC、Prisma、Tailwind这套组合，从零搭起来的一个全栈Web应用示例项目，用来验证“端到端类型安全”到底能在真实业务里省多少事。

如果你正打算选型一套前后端分离但又不愿意维护双端类型定义的项目，或者想看看T3 Stack在实际落地时有哪些坑和细节，这篇就当一次同事间的技术复盘看。我会把项目的设计思路、核心链路、实操步骤以及我踩过的真实问题全部铺开讲，代码片段可以直接拿去改。

1. 项目整体设计与技术选型

1.1 为什么选T3 Stack这套组合

先说结论：T3 Stack不是框架，不是官方发布的东西，它是一套由社区主导的最佳实践组合。核心哲学很直白——能不用JavaScript的地方就不用JavaScript，全部换TypeScript，让类型从数据库一直灌到浏览器里。我在做t3code之前，用过常规的REST API方案，写过GraphQL方案，也试过纯服务端渲染加少量交互的方案，但总会遇到同一个毛病：改了后端字段，前端要手动同步类型定义，漏一次就是线上运行时才发现Bug。

T3 Stack恰好解决了这个痛点。它把Next.js当应用骨架，Prisma做数据库映射，tRPC替代REST和GraphQL，NextAuth做认证，Tailwind负责样式，最后用TypeScript把所有环节粘起来。从Prisma的model定义出发，类型直接推导到tRPC的返回值，再通过React Query的hooks传到组件props，全程你不写一行手动的interface，编辑器都能给你提示字段错误。这对一个以“少写重复代码”为目标的项目来说，几乎是降维打击。

选它还有一个实际原因：社区生态足够成熟。T3相关的关键词在GitHub上能搜出大量模板和讨论，遇到问题有现成的排查思路，不像某些新兴框架连文档都不全。t3code的定位是“生产级示例”，所以我更看重稳定性和可维护性，而不是炫技。

1.2 技术栈逐项拆解与分工

t3code用到的核心依赖如下：

这个分工最舒服的地方在于，每个工具都只管自己最擅长的事：Next.js负责渲染与路由的框架逻辑，Prisma不碰业务逻辑只做数据映射，tRPC不代替业务框架只做类型安全的函数调用，Tailwind不管数据只负责样式。层与层之间的边界非常干净，定位问题的时候能快速缩小范围。

1.3 脚手架初始化与工程规范

t3code初始化用的是Create T3 App的标准命令：

npm create t3-app@latest t3code

交互式选项里我按项目需要勾选了Next.js、Tailwind、tRPC、Prisma、NextAuth，把ESLint也带上。初始化完，目录结构已经有了基础的“三段式”分层：

src/ app/ // Next.js App Router的页面与布局 server/ // api路由、auth配置、db实例、tRPC根路由 trpc/ // tRPC的客户端封装与server返回类型 prisma/ schema.prisma // 数据模型定义

这里有个容易忽略的细节：Create T3 App生成的项目默认使用严格模式的TypeScript配置，noUncheckedIndexedAccess也是开的。这意味着你不能随便用array[0]而不处理undefined。刚开始会有点烦，但适应之后代码质量确实高了不少，很多运行时错误在设计期就被堵住了。

2. 核心链路：类型安全的数据流设计

2.1 Prisma数据建模与迁移策略

t3code的业务模型我设计得比较简单——模拟一个带用户系统的内容管理场景，有User、Post、Comment三个核心实体。先看最关键的Prisma schema：

model User { id String @id @default(cuid()) name String? email String @unique emailVerified DateTime? image String? posts Post[] comments Comment[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Post { id String @id @default(cuid()) title String content String published Boolean @default(false) author User @relation(fields: [authorId], references: [id]) authorId String comments Comment[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Comment { id String @id @default(cuid()) content String post Post @relation(fields: [postId], references: [id], onDelete: Cascade) postId String author User @relation(fields: [authorId], references: [id]) authorId String createdAt DateTime @default(now()) }

我选择cuid()作为主键而不是自增整数，主要是考虑到数据可能在多个环境间迁移、合并，CUID能避免冲突。值得注意的是外键关系一定要明确写onDelete策略。比如评论关联帖子，帖子删除时评论应该一起删，这里就配置了onDelete: Cascade，否则数据库层面会限制删除操作，业务里就要额外写清理逻辑。

迁移我习惯用prisma migrate dev在本地开发，生产环境则用prisma migrate deploy：

npx prisma migrate dev --name init_t3code npx prisma migrate deploy

2.2 tRPC路由划分与类型推导机制

tRPC的核心思想是：后端导出的router类型，前端直接就能推断出来。t3code的tRPC架构是标准的“根路由聚合子路由”模型：

// src/server/api/root.ts export const appRouter = router({ post: postRouter, user: userRouter, comment: commentRouter, }); export type AppRouter = typeof appRouter;

每个子路由内部再拆procedure：

// src/server/api/routers/post.ts import { z } from "zod"; import { createTRPCRouter, protectedProcedure, publicProcedure } from "../trpc"; export const postRouter = createTRPCRouter({ all: publicProcedure.query(async ({ ctx }) => { return ctx.db.post.findMany({ where: { published: true }, orderBy: { createdAt: "desc" }, include: { author: { select: { name: true, image: true } } }, }); }), byId: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx }) => { return ctx.db.post.findUnique({ where: { id: input.id }, include: { comments: { include: { author: true } } }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1) })) .mutation(async ({ ctx, input }) => { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id }, }); }), });

注意这里的publicProcedure和protectedProcedure是区分权限的关键。t3code在createTRPCContext里注入了当前session，若用户未登录，protectedProcedure会直接抛401，前端拿到错误后就能跳转登录页。这样的好处是权限控制不再散落在每个API handler里，而是通过“中间件”统一治理。

2.3 client端React Query的自动生成与缓存

tRPC最爽的使用体验在前端。初始化时通过createTRPCReact创建hooks，类型自动从AppRouter推导：

// src/trpc/react.tsx import { createTRPCReact } from "@trpc/react-query"; export const api = createTRPCReact<AppRouter>();

页面里直接用：

const { data, refetch } = api.post.all.useQuery(); const createPost = api.post.create.useMutation({ onSuccess: () => { utils.post.all.invalidate(); }, });

useMutation的onSuccess里调用invalidate()，删除或创建数据后自动触发相关查询的重新拉取。这是React Query最核心的缓存机制，几乎不用手动管理loading状态，比手工写fetch然后自己setState要省太多。建议新手重点理解失效（invalidate）和缓存命中两个概念，这是和传统fetch方案最大的分水岭。

3. 实操过程与核心环节实现

3.1 认证模块：NextAuth接入与自定义登录

t3code默认集成了NextAuth，但要让它跑起来有几个必填环境变量：

DATABASE_URL="postgresql://..." NEXTAUTH_SECRET="生成一串随机字符串" NEXTAUTH_URL="http://localhost:3000"

我强烈建议用openssl rand -base64 32生成NEXTAUTH_SECRET，不要自己编一个短字符串，否则生产环境会告警。NextAuth的配置集中在src/server/auth.ts：

export const authOptions: NextAuthOptions = { providers: [ GitHubProvider({ clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, }), ], callbacks: { session({ session, user }) { return { ...session, user: { ...session.user, id: user.id } }; }, }, };

理论上到这里GitHub登录就能用了，但实际落地时还有一个坑：NextAuth默认的session类型里没有user.id，需要自己扩展类型声明。我会在src/types/next-auth.d.ts里写：

declare module "next-auth" { interface Session { user: { id: string; name?: string | null; email?: string | null; image?: string | null; }; } }

不补这个类型，ctx.session.user.id在tRPC里会直接报类型错误。这个细节教程里很少提到，但几乎所有基于NextAuth + tRPC的项目都会遇到。

3.2 核心页面与SSR数据加载策略

t3code里我写了三个主要页面：首页帖子列表、单个帖子详情、个人中心。每个页面的数据加载策略不一样，这是Next.js App Router模式下需要仔细权衡的点。

首页用服务端组件直接调tRPC是不行的，因为App Router的服务端组件不能直接使用基于React Query的tRPC hooks。正确做法是调用tRPC的server端函数：

// src/app/page.tsx import { api } from "~/trpc/server"; export default async function HomePage() { const posts = await api.post.all.query(); return <PostList initialPosts={posts} />; }

详情页则可以在Server Component里通过动态路由参数调用api.post.byId.query({ id })，这样首屏HTML直接包含完整数据，SEO友好，不用客户端再等一个loading。

个人中心需要登录后展示自己的帖子，这种情况我选择“混合策略”：外壳用Server Component判断session，内部交互组件用Client Component + tRPC query。这个边界要分清楚：Server Component负责首屏静态数据，Client Component负责需要交互的查询和mutation。

3.3 环境变量管理与多环境部署

t3code用了三个环境文件来管理不同阶段的配置：

.env.example # 模板，提交到仓库 .env.development # 本地开发 .env.production # 线上部署

一个重要的安全习惯：.env.example里只写键名和占位符，真正的密钥永远不要提交到Git仓库。我在项目根目录放了.gitignore，默认会忽略所有.env*，但如果你把.env.example也忽略了，队友拉代码就会一脸懵。建议做两件事：保留.env.example进仓库，手动在.gitignore里加一行!.env.example。

生产部署我用的是Vercel + Postgres托管，Vercel平台对Next.js的支持确实省心，连接数据库只需要在平台环境变量面板里把DATABASE_URL和两个认证密钥填上。如果要部署到自建服务器，则用Dockerfile构建：

FROM node:20-alpine AS base RUN npm i -g pnpm WORKDIR /app FROM base AS deps COPY package.json pnpm-lock.yaml ./ RUN pnpm install --frozen-lockfile FROM base AS build COPY --from=deps /app/node_modules ./node_modules COPY . . RUN pnpm prisma generate && pnpm build FROM node:20-alpine AS runner COPY --from=build /app/.next/standalone ./ COPY --from=build /app/.next/static ./.next/static CMD ["node", "server.js"]

Docker部署时务必注意：Prisma的query engine是平台相关的二进制，在alpine镜像里需要额外安装openssl兼容层，否则跑起来报错Query engine library for current platform "linux-musl" could not be found。如果你不想折腾原生依赖，直接用Vercel这类托管平台能省掉这个烦恼。

4. 常见问题与排查技巧实录

4.1 tRPC调用报500错误，但日志空白

这是我在t3code开发中遇到最多的一类问题。tRPC的错误处理默认会把具体错误信息藏在response里，但如果你开了Next.js的production模式，日志里可能只显示一行Error: Internal Server Error，看不到stack trace，排错效率极低。

排查思路分三步走。先看network响应体的error.data字段，tRPC会把错误堆栈放在data.stack里。如果响应体也是空的，那就去服务端日志里找Prisma的查询报错。还有一个高频原因：在Server Component里直接调api.post.all.query()时忘记给context传入session，导致ctx.session为null。解决方法是给createTRPCContext里做空值兜底：

export const createTRPCContext = (opts: CreateNextContextOptions) => { const session = getServerSession(authOptions); return { db, session: session ?? null }; };

然后protectedProcedure内部通过middleware抛错，而不是在context构建阶段就崩溃。这样至少错误信息能正确分类为UNAUTHORIZED，而不是笼统的500。

4.2 Prisma migrate产生历史分叉

多人协作时，如果你本地的_prisma_migrations历史记录和主线不一致，prisma migrate dev会报“migration history is diverged”。我实操中的快速处理方式是：确认数据库当前状态没问题，保存现有数据后重置迁移记录：

npx prisma migrate reset --force --skip-seed npx prisma migrate dev

但reset会清空数据，所以在非本地环境千万别直接跑这条命令。更稳妥的做法是：删掉本地prisma/migrations目录里多余的历史迁移文件，只保留与生产一致的基线，再重新生成一个合并迁移。另外，生产环境数据库我一般会额外做每日备份，保证出问题时能回滚。

4.3 Tailwind响应式样式不生效

Tailwind的类名在t3code里偶尔会出现“编译了但样式没生效”的情况。最常见的原因是把动态拼接的类名写进了模板字符串，比如className={bg-${color}-500}。Tailwind的扫描器在构建时静态识别类名字符串，动态拼接的类名会被直接跳过，不会生成对应CSS。解决办法是使用完整的类名映射表：

const colorClasses = { red: "bg-red-500 hover:bg-red-600", blue: "bg-blue-500 hover:bg-blue-600", }; <button className={colorClasses[color]} />

另外一个容易踩的坑是App Router里给服务端组件赋值use client组件，或者反过来。如果你在layout.tsx里用了一个Client Component包裹内容，且这个Client Component没有匹配好SSR和客户端渲染条件，会出现首屏FOUC（闪白）。t3code里我把所有“需登录才显示”的导航区块单独隔离成Client Component，避免把整个layout强行标记成客户端渲染。

4.4 生产环境首屏接口过慢与缓存优化

t3code上线内测时，发现帖子列表页的首屏加载在弱网环境下需要2秒以上。排查后定位到两个瓶颈：一是首页query串行请求了作者信息，二是没有做静态缓存。优化方案是Prisma查询里用select按需取字段，避免include整张关联表：

include: { author: { select: { name: true, image: true }, // 只取需要字段 }, }

同时对于“按时间排序的文章列表”这类很少变化的接口，我在Next.js里声明了revalidate = 60，让页面每分钟增量重新生成一次静态结果。tRPC的server调用本身不受影响，但Next.js缓存层就能把大部分请求挡住，200并发压测下响应时间从1.8秒降到了200毫秒左右。注意，如果用cookies()或headers()读取请求上下文，Next.js会自动禁用静态缓存，所以“纯公开数据”的部分才适合加revalidate。

4.5 常见问题速查表

5. 一条龙上线的完整复盘

5.1 开发阶段容易忽略的配置细节

如果你准备完整照着t3code的思路复刻，有四个配置细节我建议从一开始就做对。

第一，tsconfig.json里打开strict和noUncheckedIndexedAccess，虽然前期会多写很多空值判断，但等代码规模上来之后，这个决定能帮你挡住大量边界Bug。

第二，ESLint配置里加上@typescript-eslint的推荐规则，t3code的脚手架默认带了，别手滑删掉。它能在你写异步逻辑时提示未处理Promise，这类错误在运行时往往最难定位。

第三，Prisma的url使用connection pooler还是直连要提前想清楚。我踩过的坑是在Serverless环境用直连Postgres，短连接被数据库拒绝。如果是Vercel + Postgres，一定要把DATABASE_URL配置成连接池地址，否则并发请求一多就会报连接数超限。

第四，所有需要登录的tRPC mutation，入参里都不要信任前端传来的userId，必须从ctx.session.user.id拿。t3code一开始我在一个更新资料的mutation里直接把前端userId作为设置项，测试时发现可以任意改别人数据，后来全部改成了session取值。这个原则要写进团队规范。

5.2 代码组织与团队协作方式

t3code项目规模并不大，但代码组织我刻意按照“可扩展”的方式规划。tRPC路由器的目录命名直接对标业务模块，比如postRouter对应整个帖子模块，页面组件命名和路由保持一致。这样加到第三个业务模块时，只需新开一个router文件，改一下root.ts聚合即可，完全不影响已有功能。

同类型项目协作时，我见过团队纠结“到底用React Query还是SWR”“用zod还是yup”。实际体验下来，tRPC官方绑定的React Query和zod已经是一套非常顺手的组合，不要在中途替换。因为zod不仅仅做入参校验，它的类型推导能力直接被tRPC用来生成procedure的入参类型，换掉yup就等于放弃了这个核心链路的类型安全。

5.3 项目上线后我要干什么

t3code这个项目上线后，我第一件事是注册了日志监控和错误上报服务。tRPC的错误默认会以TRPCClientError结构被前端捕获，但这些只能看到“用户视角的错误”，服务端堆栈对用户没有意义，需要自动上报到后台。我接入了错误捕获服务后，很快就发现了一个“评论创建成功但页面数据不刷新”的问题，用户反馈前就已经通过日志定位到了——又是invalidate调用顺序写错了，把这个操作放在了mutate之后立即执行，但API请求还没完全落地。

按照我的经验，项目上线后的前两周是最容易暴露问题的阶段。那些开发环境重现不了、从用户侧看到的偶发问题，90%都是环境变量缺失、依赖版本不一致、数据库权限不够这类“基础配置”问题，而不是业务逻辑问题。所以t3code的部署脚本里我用GitHub Actions把所有代码质量检查、Prisma migrate deploy、构建产物串到了一起，合并到main分支时自动跑一遍，配置错了会在构建阶段就拦下来。

5.4 后续可以扩展的方向

t3code现在跑得挺稳，但我心里有个扩展清单。短期计划是加上文件上传，图片存在对象存储里，数据库只保存访问路径，Prisma的字段类型改成String，前端用带签名的URL访问。中期计划是加一个基于角色的权限管理，在session里注入role字段，tRPC procedure里加一个requireRole("admin")中间件，对评论审核、内容删除等操作做权限控制。长期计划是把server端抽成独立的BFF服务，和移动端共享同一套tRPC路由，真正做到一套类型定义覆盖Web和App两端。

这些方向都是t3code现在这个架构天然支持的，因为类型安全的底子打好了，加功能不再是“粘贴代码+修类型错误”，而是“写好业务逻辑+让类型检查替你兜底”。这也是我做完这个项目后最大的体会：投资在数据链路的类型安全上，比任何测试补充都更能长期受益。

最后再分享一个小技巧：t3code项目的package.json里，我加了一个db:studio的脚本，本地开发时一键启动Prisma Studio，可以直接浏览和修改数据库数据。调试数据相关问题时，这个工具比写一堆脚本高效得多。如果你是第一次尝试T3 Stack组合，建议先把整个链路跑通一遍——从创建模型、迁移数据库、查询数据到在页面上渲染出来，走完这一步，你对这套组合的信心会翻倍。