两个月前我开始动手做t3code这个项目。它是给团队内部写的一个全栈工具代码片段管理系统附带轻量任务看板让前端、后端、算法同事能把平时沉淀的代码、踩坑记录、常用配置统一放在一个地方。项目代号 t3code 的来历很简单——整套技术栈基于 T3 Stack 的全家桶Next.js、TypeScript、Tailwind CSS、tRPC、Prisma、NextAuth名字里带个 t3叫顺口了。真正触发我做这个项目的是一次具体到不能再具体的痛团队四五个人在群里互相发代码片段过了两周想找某段爬虫配置翻聊天记录翻到接近崩溃。市面上的代码片段管理工具不是没有但要么太重要么权限模型跟团队结构不匹配。我们需要的其实很简单登录、创建片段、打标签、搜索、按成员共享。这种内部工具用现成 SaaS 反而别扭自己写一个小而全的系统是最省心的路。技术选型时我心里其实有过犹豫。手上正好还有一个用 Next.js 的 SSR 项目团队对 React 很熟所以全栈框架方向没争议。真正有争议的是数据访问层走传统 REST 还是上 tRPC。最后让我下决心的是端到端类型安全带来的协作收益。这篇博客把 t3code 从零到上线这段过程完整记录下来包括选型细节、类型系统的落地方式以及这个过程中踩过的所有坑。1. 为什么 t3code 选了 T3 这套组合1.1 小团队协作的最大成本在接口层前后端分离是行业主流但对一个五六人的内部项目来说它带来的沟通成本远大于收益。传统模式下后端写接口文档、前端按文档 mock 数据、联调时两边各改各的字段名差一个字母就要来回沟通。t3code 虽然只是内部工具功能模块依然横跨用户、片段、标签、任务、评论五张核心表接口数量最终超过四十个。如果用 REST OpenAPI 的方式意味着每个接口都要同步文档和类型。类型不同步的问题在开发后期会集中爆发前端已经联调好的页面因为后端改了某个字段的可空性编译直接报错。这个痛点我在之前几个项目里经历过太多次。选 tRPC 的核心理由就一条接口类型直接由服务端代码推导前端引过来就是对的不需要额外维护任何契约文件。1.2 create-t3-app 的三条原则create-t3-app 的维护者提过三条原则我印象很深类型安全第一、只用成熟稳定的方案、样板代码最小化。翻译成大白话就是能在编译期查出来的问题绝不拖到运行时不碰版本号还没稳定、踩坑没人分享的技术脚手架能生成的就别手写这三条对内部工具项目特别合适。我们没有足够的精力去养一套冷门框架也没有预算请专人维护基础设施。T3 组合里的每个组件都是各自领域的默认选项这意味着遇到问题去搜索引擎一搜基本都能找到答案。实际开发中确实如此绝大多数报错都能在社区讨论里找到原因。1.3 被我排除的备选方案选型时我还认真考虑过另外两条路这里记录一下排除理由供参考Next.js Express/NestJS REST接口层要手写文档和类型同步联调成本高不符合小团队的协作模式。纯前端静态站 SupabaseSupabase 的 Row Level Security 确实强大但权限模型的学习成本比写几个 tRPC 接口高得多而且自托管时运维成本不低。排除这两条之后T3 组合几乎是顺理成章的选择。数据库用 Prisma 管理 schema 和迁移认证直接接 NextAuth样式用 Tailwind 保证全程不用写一行 CSS 文件。2. 五个核心组件在 t3code 里的分工2.1 Next.js App Router路由与渲染边界t3code 用的是 Next.js 14 的 App Router。项目里我坚持一个简单的划分原则能放 Server Component 就放 Server Component需要交互的叶子节点才标记 Client Component。比如片段列表页数据在服务端直接从数据库读取经 tRPC 的 server caller 调用后渲染成静态列表整个页面不包含任何 client 端数据请求逻辑。只有搜索框、筛选器、创建弹窗这类需要交互的组件才单独标注use client。这样做的好处是首屏 HTML 里直接有内容搜索引擎能看到用户打开页面也不用先等 JS 加载再渲染。内部工具虽然不太依赖 SEO但加载速度直接影响同事用的意愿——一个打开要转两秒的工具没人愿意天天用。2.2 tRPC把跨进程调用伪装成函数调用tRPC 是 T3 组合里最关键的一块。它的本质是让前端代码直接调用服务端函数类型通过 TypeScript 的泛型推导自动穿越网络边界。我在 t3code 里按照业务域划分 routersnippetRouter、taskRouter、tagRouter、userRouter。每个 router 内部用createTRPCRouter定义若干 procedure每个 procedure 用protectedProcedure或publicProcedure声明访问级别。前端调用时页面里只写一行api.snippet.getAll.useQuery()返回的数据类型就自动对应服务端函数的返回类型。改数据库字段后Prisma 类型重新生成tRPC 类型跟着更新前端如果用了不存在的字段编辑器直接标红。这种改一处、全链报错的体验正是我选这套组合的核心目的。2.3 Prisma数据库迁移与类型生成的自动化t3code 的数据库用 PostgreSQLORM 选了 Prisma。主要原因倒不是 Prisma 本身多强而是它和 TypeScript 的配合度是最顺滑的prisma.schema文件里定义模型后跑一条prisma generate就能得到完整的类型定义并且这些类型会通过 tRPC 一路传到前端。schema 设计上我踩过几次关系模型的坑后面第 4 节会细说。这里先提一个原则多对多关系一定要建显式的中间表不要图省事用 JSON 数组存外键。比如片段和标签的关系我建了SnippetTag中间表带createdAt字段这样后续要排序、去重、统计都有数据可用。2.4 Tailwind CSS原子类的组织方式Tailwind 在 t3code 里负责全部样式。说实话项目初期我对原子化 CSS 是持保留态度的担心长类名影响可读性。实际用下来发现担心是多余的组件拆分足够细的时候每个组件的类名都在可控范围内而且改样式不用全局搜索.css文件直接在对应组件里改类名就行。比较重要的经验是自定义主题色要在一开始就规划好。Tailwind 的默认色板偏向蓝色系而 t3code 的品牌色是青绿色。我在tailwind.config.ts里扩展了brand色系后续所有组件都引用bg-brand-500这类语义化类名而不是直接写色值。这样改主题时只需要动配置文件全站颜色自动生效。2.5 NextAuth登录与授权的接入细节认证方案选了 NextAuth v4配合 GitHub OAuth 和 Credentials 两种登录方式。内部工具用 GitHub 登录非常方便团队成员都有账号免去注册流程。NextAuth 接入 T3 组合时有个固定套路authOptions定义在src/server/auth.tstRPC 的createTRPCContext里读取 session然后protectedProcedure检查session?.user是否存在不存在则抛UNAUTHORIZED错误。3. 类型安全是怎么贯穿全链路的3.1 一条数据从数据库到页面的完整链路拿最核心的片段详情页举例一次请求背后的数据流是这样的Prisma schema 定义Snippet模型prisma generate生成对应 TypeScript 类型tRPC 的getByIdprocedure 调用 prisma 查询返回对象自动携带 Snippet 类型前端调用api.snippet.getById.useQuery()返回的 data 类型与 Snippet 完全一致页面里如果写了data.author.name但 schema 里没有关联该字段编辑器直接报类型错误整条链路没有任何手动声明的 interface所有类型都由一个源头数据库 schema推导而来。这在实际开发中节省的时间是肉眼可见的我几乎再也没有遇到过后端数据结构改了前端忘了更新这类问题。3.2 Router 划分与类型导出的约定t3code 的 tRPC 划分遵循一个约定每个业务域一个文件文件里只暴露 domain 相关的 procedure不跨域调用其他 router 的内部函数。比如snippetRouter里的createSnippet需要同时写入标签关联数据它会直接调用 prisma 操作SnippetTag表而不会去 importtagRouter的函数。这样做的原因是 tRPC 的 router 嵌套虽然方便但跨域调用容易造成类型循环引用排查起来非常痛苦。Procedure 的输入参数统一用 Zod schema 声明。比如创建片段的输入const createSnippetSchema z.object({ title: z.string().min(1).max(100), code: z.string().min(1), language: z.enum([typescript, javascript, python, sql, bash]), tags: z.array(z.string()).max(8), });这个 schema 既能校验运行时输入又能推导出前端调用时的参数类型。在编写页面表单时传给服务端的参数应该长什么样这个问题直接由编辑器提示根本不用查接口文档。3.3 Zod 校验在服务端和客户端的复用Zod 的一大优势是校验逻辑可以跨端复用。t3code 里createSnippetSchema定义在src/server/schemas目录前端表单提交前先做一次本地校验后端 procedure 入口再用同样 schema 校验一次。双端校验不是多此一举。本地校验能做即时反馈——用户没填标题点提交按钮时立刻提示不用等网络往返。服务端校验是最后防线防止有人绕过前端直接请求接口。两者用同一个 schema 意味着不会出现前端校验规则比后端严格的诡异情况。4. 排错实录t3code 开发中值得记录的坑4.1 NextAuth 的 Session 类型扩展我在 t3code 里给 User 模型加了一个nickname字段但页面上通过session.user.nickname访问时TypeScript 一直报错。查了半天才发现 NextAuth 默认的Session类型里user对象只有name、email、image三个字段。解决办法是在src/types/next-auth.d.ts里声明模块扩展declare module next-auth { interface Session { user: { id: string; name?: string | null; nickname?: string | null; email?: string | null; image?: string | null; }; } }这个坑的根源在于 NextAuth 的类型系统故意保持开放让开发者按需扩展。问题是文档里写得不够显眼新手很容易直接改User模型却忘了同步扩展 Session 类型。我建议 T3 项目脚手架生成后第一件事就是把这个类型扩展文件写好避免后续所有页面都在为 session 类型报错。4.2 tRPC 在 Server Component 里的调用方式App Router 全面铺开后tRPC 的调用姿势也跟着变了。在 Client Component 里useQuery是最好的方式但在 Server Component 里不能直接用useQuery需要调用 tRPC 的server caller。t3code 里我封装了一个serverApi实例放在src/server/caller.tsexport const serverApi createCaller({ session: await getServerSession(authOptions), headers: await headers(), });服务端页面里直接await serverApi.snippet.getAll({ search })就能拿到数据并交给组件渲染。这个方案比用 fetch 调自身 API 干净得多因为完全复用了 tRPC 的类型推导而且少了一次 HTTP 往返。让我印象最深的是这个能力在官方文档里埋得有点深。如果直接从网上搜tRPC App Router出来的教程大多还是旧版 Client Component 方案很容易让人在 Server 组件里硬塞use client导致整个页面客户端渲染首屏性能白白浪费。4.3 Prisma 多对多关系的迁移问题t3code 开发到第二周时我想给片段增加收藏功能即用户与片段之间多对多关系。第一次 schema 设计时我图省事直接在Snippet模型里加了一个favoritedBy User[]字段配合隐式关系表。问题出现在后续字段扩展想在收藏关系上记录收藏时间隐式关系表无法自定义字段只能推倒重来改成显式中间表。那次迁移改了三个模型还跑了一次数据回填脚本花了整整一个下午。教训是凡是能预见需要在关系上附加属性的第一次就用显式中间表。收藏、关注、点赞这类关系几乎必然会有什么时间收藏的收藏时的来源页面这类元数据需求不早点建中间表后期迁移成本很高。4.4 React Query 缓存导致的页面假死t3code 的片段列表支持搜索和标签筛选我之前用useQuery的标准写法const { data, refetch } api.snippet.getAll.useQuery({ search, tag });然后搜索框的 onChange 里调用refetch。实测发现用户快速输入时会产生大量并发请求而且输入过程中的请求结果会覆盖最终结果导致页面显示的搜索结果是历史数据。典型的竞态问题。排查后发现根因是 React Query 只管缓存不会自动取消过期请求。旧请求返回慢时它的结果会写入同一个 query key把新结果顶掉。解决方式是不要在 onChange 里自动触发请求改为表单提交或防抖 400ms 后再触发同时给 query key 加上搜索词参数。改成防抖后问题彻底消失还顺带减少了服务器压力。4.5 Tailwind 动态类名不生效这是个老坑但我还是在 t3code 里踩了一次。代码高亮显示的语言标签我写成className{badge-${language}}结果页面上样式时有时无。原因很直接Tailwind 是静态扫描类名的badge-typescript这种字符串没有被完整写在源码里就会被判定为未使用构建时被丢掉。解决办法是把语言标签的完整类名映射表写成一个对象const badgeClasses: Recordstring, string { typescript: bg-blue-100 text-blue-800, python: bg-green-100 text-green-800, };动态字符串拼接在 Tailwind 生态里是要尽量避免的。只要类名是动态拼出来的构建时基本都会出问题。提前用映射表枚举好所有状态比踩完之后再改成本低得多。5. 部署与线上调优5.1 部署环境与连接串配置t3code 部署在 Vercel数据库用了一家托管 Postgres 服务。整体部署过程比预期顺利最需要注意的是环境变量的管理。Prisma 在构建阶段需要扫描 schema、生成 client所以构建机器上必须有数据库连接串执行prisma generate。我第一次部署时没有在 Vercel 后台配环境变量导致构建失败错误信息里 Prisma 找不到 schema 配置排查了二十分钟才反应过来是环境变量没传。此外Vercel 的 serverless 函数对数据库连接数很敏感。每个函数实例都可能建立独立的数据库连接连接数耗尽会导致间歇性超时。解决方式是把 PrismaClient 做成全局单例避免每次调用都实例化const globalForPrisma globalThis as unknown as { prisma: PrismaClient }; export const prisma globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) globalForPrisma.prisma prisma;这段代码 create-t3-app 已经默认生成没必要删掉。我第一次见到觉得多余后来在日志里看到大量连接建立记录才明白这行的价值。5.2 首屏性能实测与优化上线后我用 Lighthouse 测了一遍性能发现最主要问题是 JavaScript 体积偏大。排查发现是 tRPC 把服务端函数引用打包进了前端 bundle加上 Zod 的全量校验逻辑首屏 JS 超过了 300KB。针对这个做了一轮优化Zod 开启z.string().min(1)这类方法时只引入实际使用的校验函数能显著瘦身非核心组件如任务看板的拖拽库用next/dynamic按需加载语言标签的高亮渲染改为服务端完成前端只接收渲染后的 HTML优化后首屏 JS 降到 190KB 左右Lighthouse 性能评分从 68 分提高到 89 分。内部工具虽然对性能容忍度高但数据能说明问题同事打开列表页的白屏时间从 1.8 秒降到 1.1 秒试用意愿明显上一个台阶。5.3 数据库查询的性能瓶颈t3code 上线后最耗时的接口是片段搜索原因是搜索关键词直接在 PostgreSQL 里用了contains操作走了全表扫描。数据量只要到几千条响应时间就会飙到 300ms 以上。我没有引入 Elasticsearch 这类重型方案而是直接给搜索字段加了 trigram 索引CREATE EXTENSION IF NOT EXISTS pg_trgm; CREATE INDEX snippet_code_trgm ON Snippet USING gin (code gin_trgm_ops);配合 ILIKE 查询搜索响应时间从 300ms 降到 40ms 左右。对内部工具的数据规模来说这已经足够。如果后续数据量超过十万条再考虑迁移到专门的全文搜索方案也不迟。6. 复盘T3 组合适合谁、不适合谁6.1 收益最大的场景t3code 这个项目跑完后我对 T3 组合的定位有了更清楚的判断。它最适合几个人到十几个人的小团队做内部工具、MVP 原型、以及业务逻辑中类型安全价值高的中型应用。这类项目的共性是没有庞大的 API 面需要对外暴露没有复杂的微服务拆分需求团队更关注的是快速上线、稳定运行、后续好改。T3 组合端点到端类型安全的特性正好把最大的隐形成本——前后端协作的沟通损耗——压到最低。6.2 不适合的场景同时我也要坦白说有几类场景我会谨慎推荐 T3需要对外开放 API 给第三方调用tRPC 的类型安全只对 TypeScript 客户端有效外部团队用 Java 或 Go 接入时体验反而不如 REST OpenAPI。团队前后端技术栈差异极大如果后端同事是 Java 背景非要整体搬迁到 TypeScript 生态学习成本会抵消类型安全带来的收益。需要高频做数据报表和复杂查询Prisma 的查询 API 对聚合查询支持一般复杂 SQL 场景下用它的体验不如手写 SQL 一个轻量 ORM。6.3 后续打算t3code 的第一版已经上线内测团队反馈基本符合预期。后续我会在三个方向继续迭代把任务看板升级成支持拖拽的看板视图搜索从关键词匹配升级到拼音和全文检索以及把团队内沉淀的代码片段接入 AI 辅助查询——输入一段描述直接联想相关片段。技术上如果要加这些功能t3code 现有的架构不需要大改最多在 tRPC 层新增几个 procedurePrisma 层加两张表。这也从侧面说明当时的选型承受住了业务扩展的压力。最后说点个人体会。做 t3code 之前我对端到端类型安全的认知停留在概念层面觉得无非是少写点 type 定义。真正写完一个完整项目才意识到它带来的最大收益不是编译期报错的前置拦截而是让我在写业务代码时敢大胆改数据结构——数据库字段改了所有受影响的地方会像探照灯一样亮出来不会有一处漏网。这种踏实感是传统接口文档模式给不了的。如果你也在做类似的内部项目不妨给自己一个机会试试这套组合前提是团队基线统一在 TypeScript 上。