如果你正在搜索“t3code”这个词大概率你是被那套“全栈 TypeScript”的理念吸引了。t3code 不是一个官方框架也不是某个大厂出的付费课程它是围绕 T3 技术栈TypeScript Tailwind CSS tRPC展开的一套编码实践集合。我搭建这个项目的初衷很简单在保证类型安全的前提下把前后端开发效率拉满同时避免被 Webpack、Babel、ESLint 那些繁琐配置消耗精力。这篇文章我会把这套方案从设计到落地、从踩坑到优化的完整过程记录下来给想从纯前端转向全栈、或者被配置折腾到怀疑人生的朋友一份可以直接抄作业的参考。1. 项目概述与核心思路1.1 t3code 是什么t3code 是我自己定义的一个全栈编码实践项目本质上是利用 create-t3-app 脚手架快速生成一个 Next.js TypeScript Tailwind CSS tRPC Prisma NextAuth 的应用骨架然后在上面实现真实的业务功能。它不是一个“只有一个登录页”的演示项目而是包含数据建模、服务端渲染、API 暴露、权限校验、部署上线这一整条链路的完整编码练习。为什么选择这一套组合而不是传统的 Express React 分离架构核心原因是类型安全。在传统的 REST API 开发模式下前端拿到后端返回的数据后要手动定义 interface 来匹配响应结构一旦后端字段改名或者结构调整前端往往要等到运行时才能发现问题。t3code 这套方案里tRPC 让前端调用后端函数就像调用本地函数一样输入输出类型全部由 TypeScript 自动推导编译期就能拦截大部分错误。我搭建 t3code 时给自己定了几条原则只使用成熟稳定的核心依赖不盲目追求花哨的 UI 组件库所有数据操作必须经过 Prisma 的 model 定义不手写 SQL认证逻辑基于 NextAuth不重复造轮子样式统一用 Tailwind 原子类不用 CSS Modules这四条原则帮我避免了大量“项目前期选择困难、后期重构痛苦”的问题。1.2 这套方案解决了什么问题传统的前后端分离开发最大的痛点在于接口联调。后端同事写一份接口文档前端同事阅读文档后自己定义类型然后调试时发现字段对不上再回头沟通。一个字段的命名差异可能让整个联调周期延长半天到一天。t3code 把 API 层直接“藏”在 tRPC 的 Router 里前端调用时不需要知道 URL、不需要手动处理 JSON 序列化所有类型从数据库模型一路传到组件 props中间没有任何断点。另外这套组合还解决了一个问题项目初始化成本。作为一个自由开发者或者小团队如果从零搭建 Next.js 项目后面还要自己接 ESLint、Prettier、Prisma、Tailwind、tRPC每一步都可能遇到版本兼容问题。create-t3-app 把这些依赖高度集成官方维护的脚手架保证各版本之间可以协调工作。我实测下来从运行命令到项目启动大概只需要三到五分钟这个成本远低于手动配置。适合参考 t3code 这套思路的人我总结下来有三类想快速做出一个带数据库和用户体系的全栈应用的独立开发者团队前端想往后端延伸但不想立刻学习 Java 或者 Go 的技术人员学校项目或内部工具需要快速迭代、又没有专职后端维护接口的场景如果你属于其中任意一类这篇文章里的实操内容可以直接拿来用。2. 核心技术点拆解2.1 tRPC让前后端类型不再“失联”tRPC 是整个 t3code 技术栈里最核心的一环。它的原理说起来并不复杂在服务端定义一个包含若干 procedure过程的 router每个 procedure 可以看作一个带输入输出类型约束的函数。前端通过 tanstack/react-query 的实例调用这些 procedureTypeScript 会自动把服务端的类型信息“同步”到客户端。这里我举个例子假设我们要做一个用户查询功能// server/api/routers/user.ts import { z } from zod; import { createTRPCRouter, publicProcedure } from ~/server/api/trpc; export const userRouter createTRPCRouter({ getById: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) { return ctx.db.user.findUnique({ where: { id: input.id }, }); }), });在前端组件里我只需要这样调用const { data } api.user.getById.useQuery({ id: userId });这里不需要手写 fetch 函数不需要定义请求类型更不需要在 API 变更后全局搜索“哪个类型需要同步修改”。所有类型都是由服务端自动推导来的。这个体验类比一下就是以前你打电话订餐要念一遍菜单代码现在你直接对厨房说“我要一份宫保鸡丁”厨房知道你说的是哪道菜端上来一定是正确的。tRPC 的 input 校验由 zod 完成output 类型由 Prisma 的返回类型推断整条链路没有“暗箱”。2.2 Tailwind CSS原子化样式的取舍在 t3code 项目里样式方案直接选了 Tailwind CSS。我承认它有自己的学习曲线一开始写div classNameflex items-center justify-between bg-slate-100 p-4会觉得眼花缭乱但一旦熟记常用类名开发效率会明显高于写传统 CSS 文件。为什么不用 CSS Modules 或者 styled-components我的理由是在追求“快速产出功能”的全栈项目里上下文切换成本才是最大的隐形杀手。Tailwind 把样式类名直接写在 JSX 标签上不需要频繁跳转到样式文件去起类名、查属性也不需要担心命名冲突。而且它内置了响应式断点移动端适配直接写md:前缀类名不需要另写媒体查询。我实际使用中的体会Tailwind 最出彩的并不是“快”而是移除。它移除了一整套样式文件的组织成本移除了一个心智负担思考“这个 class 应该叫什么名字”。对于 t3code 这样的全栈编码项目把精力花在业务逻辑和数据模型上远比花在“这个按钮的样式类名”上更有价值。如果你追求的是快速迭代这一点尤其明显。如果你对原子化的类名很反感也可以搭配 headlessui 这类无样式组件库把交互逻辑抽出来样式依然用 Tailwind 控制。这个组合在 t3code 里很容易实现组件库里所有交互状态管理都已经处理好你只需要关心视觉表现。2.3 Prisma 与 NextAuth数据模型和认证的配合一个实际可用的全栈应用必然需要数据库和用户体系。t3code 里数据库访问通过 Prisma认证通过 NextAuth.js现在叫 Auth.js。Prisma 的优势在于它让你用 schema 文件声明数据模型然后自动生成类型安全的数据访问层。我在 t3code 里定义了一个很常见的业务模型User、Project、Session。// 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? accounts Account[] sessions Session[] projects Project[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Project { id String id default(cuid()) name String content String? ownerId String owner User relation(fields: [ownerId], references: [id], onDelete: Cascade) createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Account { id String id default(cuid()) userId String user User relation(fields: [userId], references: [id], onDelete: Cascade) type String provider String providerAccountId String refresh_token String? access_token String? expires_at Int? token_type String? scope String? id_token String? session_state String? }定义好 schema 之后运行npx prisma migrate dev数据库表结构自动生成客户端类型也跟着更新。NextAuth 的作用则是处理登录会话我使用 GitHub Provider 作为 OAuth 登录源避免自己维护密码哈希和会话生命周期。认证和 tRPC 结合时最常遇到的一个问题是如何保护需要登录才能访问的接口t3code 的解法是在 tRPC 里创建一个protectedProcedureexport const protectedProcedure createTRPCProcedure() .use(async ({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: ctx.session } }); });然后在需要保护的路由里直接使用protectedProcedure而不是publicProcedure。这个模式理解成本低代码也足够清晰。你可能以为我一开始就是这么顺利配置好的其实不是这里我也踩过不少坑放到后面单独说。3. 从零搭建 t3code 的完整实操3.1 环境准备与初始化在开始之前我建议先确认本地环境满足这些条件Node.js 18 或以上版本我使用的是 20 LTS包管理器 pnpmcreate-t3-app 对 pnpm 支持最好一个 PostgreSQL 数据库实例本地可以用 Docker 启动GitHub OAuth App 的 Client ID 和 Secret做登录用如果还没有数据库可以用 Docker 快速启动一个 PostgreSQL 容器docker run --name t3code-postgres -e POSTGRES_PASSWORDpostgres -p 5432:5432 -d postgres:16然后创建项目pnpm create t3-applatest t3code初始化过程中交互式命令行会问你要选哪些插件我当时勾选了 NextAuth.js、Prisma、Tailwind、tRPC。其他像 Docker、Stripe 这些建议一开始不要贪多等核心功能跑通了再按需扩展。这个建议是血泪教训我最初一口气勾了很多插件启动项目后报了一堆环境变量缺失的错误心态直接崩了。初始化完成之后目录结构大概是这个样子t3code/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── pages/ │ │ ├── api/ │ │ │ └── auth/ │ │ │ └── [...nextauth].ts │ │ └── index.tsx │ ├── server/ │ │ ├── api/ │ │ │ ├── root.ts │ │ │ └── routers/ │ │ │ ├── post.ts │ │ │ └── user.ts │ │ └── db.ts │ ├── styles/ │ │ └── globals.css │ └── utils/ │ ├── api.ts │ └── auth.ts ├── .env └── package.json看到这个结构我心里其实很踏实。每个目录职责单一没有多余的抽象层。对于包含完整全栈功能的应用这个布局足够支撑到项目规模变大之前。3.2 环境变量配置这是 t3code 初始化后我们遇到的第一个“拦路虎”。create-t3-app 生成的.env文件里需要配置以下变量DATABASE_URLpostgresql://postgres:postgreslocalhost:5432/t3code-postgres NEXTAUTH_SECRET NEXTAUTH_URLhttp://localhost:3000 GITHUB_CLIENT_ID GITHUB_CLIENT_SECRETNEXTAUTH_SECRET 可以直接用 OpenSSL 生成一个随机字符串openssl rand -base64 32GITHUB_CLIENT_ID 和 GITHUB_CLIENT_SECRET 需要去 GitHub 的 Settings - Developer settings - OAuth Apps 里创建回调地址填http://localhost:3000/api/auth/callback/github。这里要注意本地开发时如果用 HTTP 没问题但生产环境一版都是 HTTPS所以回调地址那里要用线上域名如果线上域名还没有确定可以先不启用 GitHub 登录。3.3 跑通第一个数据查询流程环境变量配好之后我们来验证整条链路是否可用。首先执行 Prisma 的迁移命令npx prisma migrate dev --name init这条命令会创建数据表并且生成 Prisma Client。如果执行过程中报错大概率是DATABASE_URL写错了或者是 PostgreSQL 容器没启动。验证 Prisma 是否正常工作可以执行npx prisma studio打开 http://localhost:5555 应该能看到一个可视化面板目前表都是空的。接下来我们把 tRPC 的查询跑起来。在src/server/api/routers/user.ts里添加一个返回所有用户的查询export const userRouter createTRPCRouter({ list: publicProcedure.query(async ({ ctx }) { return ctx.db.user.findMany(); }), });然后修改首页组件通过前端调用这个查询import { api } from ~/utils/api; export default function Home() { const { data: users } api.user.list.useQuery(); return ( main classNameflex min-h-screen flex-col items-center justify-center h1 classNametext-2xl font-boldt3code 用户列表/h1 ul {users?.map((user) ( li key{user.id}{user.name ?? user.email}/li ))} /ul /main ); }启动开发服务器pnpm dev打开 http://localhost:3000页面应该能正常渲染空列表。整个流程到这里从数据库到服务端到前端组件的类型链路就已经完全打通了。这一步看起来很简单但它验证的是最关键的事情数据库 schema - Prisma Client - tRPC Router - React Query - 组件渲染这一整条链路没有断裂。接下来的所有业务功能都可以在这个基础上扩展。3.4 实现带登录和项目创建的完整功能有了基础的查询链路我建议下一步直接实现一个完整的功能闭环。t3code 里我选择的是“用户登录后创建项目”这个极简功能它可以覆盖认证、写操作、关联查询三条重要路径。首先在src/server/api/routers/project.ts里定义创建项目的过程import { z } from zod; import { createTRPCRouter, protectedProcedure } from ~/server/api/trpc; export const projectRouter createTRPCRouter({ create: protectedProcedure .input(z.object({ name: z.string().min(1), content: z.string().optional() })) .mutation(async ({ ctx, input }) { return ctx.db.project.create({ data: { name: input.name, content: input.content, ownerId: ctx.session.user.id, }, }); }), });前端表单组件const utils api.useUtils(); const createProject api.project.create.useMutation({ onSuccess() { utils.project.list.invalidate(); }, }); function handleSubmit(e: FormEvent) { e.preventDefault(); createProject.mutate({ name: nameRef.current?.value ?? }); }借助useUtils().invalidate()创建成功后列表会自动刷新这比手动 setState 更新列表要可靠得多。这个模式在 t3code 里用到很多次它保证了数据的单一数据源——所有 UI 都从服务端查询触发更新不会出现组件状态与数据库状态不一致的问题。登录功能方面NextAuth 的默认配置在初始化时已经生成好了。因为我们在 schema 里定义了 Account 和 Session model只要在前端加上useSession()的调用GitHub 登录的整个流程就能跑起来。受保护页面可以直接在组件的getServerSideProps里用getServerAuthSession做服务端判断也可以直接用protectedProcedure来限制数据操作。我个人的做法是页面是否可见由前端的 session 判断数据能不能写由 tRPC 的 protectedProcedure 判断两层各司其职。3.5 生产环境构建与部署要点开发环境跑通后部署上线时会有几个和本地不一样的地方需要处理。t3code 我最后是部署在 Vercel 上数据库还是用的原来的 PostgreSQL 实例。Vercel 部署时需要注意环境变量要重新填一遍Vercel 后台的 Environment Variables 里配置DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL就可以。NEXTAUTH_URL在 Vercel 上其实就是你的线上域名因为 Vercel 已经自动处理了环境这个变量可以省略不填。但其他变量必须填对否则部署后页面能打开接口却会报错。还有一个比较容易忽略的点如果项目使用了 Prisma 的generate步骤需要在package.json里声明{ scripts: { postinstall: prisma generate } }这个命令的作用是每次依赖安装完成后自动生成 Prisma Client这样部署平台在构建时才不会因为找不到 Prisma Client 而失败。如果你本地跑构建没问题但线上失败大概率就是没加这个 postinstall 钩子。4. 常见问题与排查技巧实录4.1 类型不匹配导致的编译错误t3code 项目里我遇到最多的问题不是运行时错误而是编译时的类型不匹配。比如修改了 Prisma schema 后没有重新生成 Client这时候调用ctx.db.user.findMany()可能报“Property findMany does not exist”之类的错误。这种问题处理起来很简单就是重新执行npx prisma generate。不要怀疑是自己代码写错绝大多数情况都是 Client 没有同步。进阶一点的建议是在package.json里加一个dev脚本同时启动prisma generate和next dev这样每次启动都会强制同步dev: prisma generate next dev这个做法帮我省了很多时间。4.2 NextAuth 登录后 session 拿不到用户 idNextAuth 默认的 session 类型只包含user.id、name、email、image这几个字段如果你需要额外的用户角色或者自定义字段必须扩展 session 类型。我在 t3code 里踩过一个坑protectedProcedure 里访问ctx.session.user.id时TypeScript 报错说id不存在。原因就是 NextAuth 的类型定义里session user 默认没有带 id。解决方法是在src/types/next-auth.d.ts里扩展类型import { DefaultSession } from next-auth; declare module next-auth { interface Session { user: { id: string; } DefaultSession[user]; } }然后在 NextAuth 的配置里把 id 塞进 sessioncallbacks: { session({ session, user }) { if (session.user) { session.user.id user.id; } return session; }, },这个配置要是漏掉了你的 protectedProcedure 即使登录成功也会报 401。它是 NextAuth 和 tRPC 集成时最典型的隐藏问题新手容易被它卡住一整天。4.3 tRPC 请求 404 或 500 的排查思路如果你在调用 tRPC 接口时返回 404先检查两件事一是src/pages/api/trpc/[trpc].ts这个文件是否存在且内容正确二是 tRPC 的路由路径是否和root.ts里注册的 router 匹配。create-t3-app 默认会生成好这些文件但如果你改过目录结构或者删过文件很容易遗漏。返回 500 的时候优先看服务端日志。tRPC 的中间件错误如果没有被 catch会直接抛到 Next.js 的 API 路由。我最常用的排查方式是先把错误输出到日志export const tRPCErrorHandler (error: unknown) { if (error instanceof TRPCError) { console.error({ code: error.code, message: error.message }); } };然后在创建 tRPC 客户端时传入这个 error 处理函数。这样至少能看到具体错误码是哪一种是 UNAUTHORIZED 还是 INTERNAL_SERVER_ERROR方向一下就明确了。还有一个隐藏得很深的坑如果你在 tRPC procedure 的 mutation 里做数据库操作但数据库连接超时或者表不存在可能只会返回一个笼统的 500。碰到这种情况我会直接去数据库控制台看有没有报错而不是盯着 Next.js 的页面看。4.4 Prisma 迁移与数据冲突开发过程中经常改 schemaprisma migrate dev应该是日常操作。但如果你在本地开发中改过一次字段类型而数据库里已有数据迁移时可能会报冲突。例如把一个String?字段改成必填String但数据库里已有几条 NULL 记录迁移就会失败。这时候我不会用prisma migrate dev --force去强行覆盖而是先处理脏数据。常见做法是把这些记录更新为默认值或者先删除测试数据再重新执行迁移。这个顺序原则是先修数据再改结构。它能避免很多“迁移成功了但线上数据混乱”的灾难。4.5 部署后样式丢失t3code 部署到生产环境后有一段时间样式全部丢失页面裸奔。排查下来才发现是因为放在globals.css里的 Tailwind 指令没有被正确构建。解决办法是检查next.config.js是否配置了正确的content路径module.exports { content: [./src/**/*.{js,ts,jsx,tsx}], };这个例子说明了一个普适的排查思路本地开发正常但线上异常的问题大概率出在构建配置上而不是业务代码上。不要上来就在组件里翻来翻去先看构建产物和配置效率会高很多。5. 性能优化与后续扩展思路功能都跑通之后整个项目的性能优化就是下一件重要的事。t3code 里我做了几个关键优化适合你在自己的项目里参考。第一是 tRPC 的请求粒度。不要把一组相关的查询拆成几十个独立 procedure 来回调用那样会产生大量网络往返。t3code 在处理项目详情页的时候如果我既需要项目基本信息又需要项目所属用户的信息我会尽量合并成一个 procedure 来查减少客户端请求数量。更适合的做法是直接定义一个简单的聚合查询虽然会稍微复杂一点但对页面性能和服务器压力都有明显改善。第二是 Prisma 的查询优化。在关联查询时尽量提前压缩字段列表不要一次findMany把所有字段都拉出来。Prisma 支持select参数可以只返回需要的字段。这一点在数据量小的时候不明显数据量上去以后差异巨大。第三是使用 Next.js 的缓存机制。对于读多写少的接口可以用unstable_cache或者 React Server Components 来缓存渲染结果。但这里要和 tRPC 做好配合不要让缓存数据查出来的信息长期过期必要时通过 mutate 使缓存失效保证数据的新鲜度。后续扩展方向上我会建议在 t3code 的基础上逐步引入以下能力增加远程团队协作的实时同步用 WebSocket 或 tRPC 的 subscription 机制增加文件上传与存储Prisma 里加 File model配合对象存储服务增加国际化多语言支持i18n 方案与 Next.js 的集成增加项目管理需要的看板视图前端组件层面扩展增加审计日志功能实现中间件来记录所有 mutation 操作这些扩展都能在保持原有技术栈不变的基础上逐步融入因为 t3code 的核心价值在于它把类型安全、数据建模、认证授权这些基础能力都梳理清楚了后续加功能不会导致技术债爆炸。在做扩展时注意始终保持一条原则核心链路的数据流向保持单向清晰不引入过多复杂性。6. 踩坑总结与个人建议最后分享几条我在搭建 t3code 过程中获得的个人经验这些是文档里不会写的。第一个经验是类型安全并不意味着零调试。tRPC 确实能把大多数类型错误拦截在编译期但运行时的逻辑错误依然要靠日志和观察来排查。不要因为用了 t3code 就放松了对运行时异常的处理。我在开发初期有过一次惨痛教训把一个 zod 校验规则写成了z.string().min(1)结果某个输入是空字符串时前端直接白屏服务端日志却一直空着。后来依靠把错误抛到日志才找到问题过程非常痛苦。第二个经验是不要过度工程化。t3code 在最初的版本里我为每一个查询都单独建了一个文件为每一个 mutation 都写了一层抽象结果代码量翻倍可读性却没有提升。后来我退回到“一个 router 文件对应一个业务域”的模式比如 user、project、team 各自一个文件文件里按功能写 procedure。代码结构清晰也比多余的分层更加实用。第三个经验是数据库 schema 的设计在第一时间要尽量合理。虽然 Prisma 让你可以后续再迁移修改但频繁迁移导致的“技术债”是会累积的。比如索引的缺失、默认值的设计、字段类型的预估这些在项目初期如果没想清楚后期优化代价不小。现在回头看 t3code 的表结构最满意的决定就是把Project和User之间的关联关系设计成了多对一而不是一开始就做成多对多。这让项目记录天然有归属感后续即使要做共享协作也可以单独加中间表。第四个经验也是最重要的一条一定不要在没有理清需求的前提下拿着工具直接开写。create-t3-app 再快也只能帮你省去初期搭建的时间真正决定项目成败的还是业务模型和数据设计。t3code 之所以开发得比较顺利是因为在动手前我先把“谁在用、用来干什么、数据关系是什么”这三个问题回答清楚了。工具是放大器方向错了放大出的复杂度和问题也会加倍。我也必须提醒一下从创建项目到真正能够开发出功能稳定、值得上线的完整应用中间还是有一段不小的距离。不要指望运行完 create-t3-app 就以为万事俱备。数据库迁移、登录回调、部署配置、线上监控这些东西都需要投入精力去打磨。我在 t3code 项目上花的时间真正写业务代码的部分可能只占三成其余时间都在处理“基础设施”问题。这个过程看似琐碎但它是全栈开发能力增长最快的地方。t3code 这个项目对我来说最大的收获不是学会了几个新工具而是真正理解了一条完整链路应该如何处理定义数据模型时多想一步、写接口时不让类型断掉、部署上线后还能有手段监控异常。当这几个环节都顺畅起来项目的复杂度就从“不可控”变回了“可控”。这套思路比任何工具本身都值钱。