说实话刚看到t3code这个名字的时候我第一反应是这哥们儿要么在搞 T3 Stack 全家桶要么就是一个跟代码片段管理相关的工具项目。等我把整个项目拉下来过了一遍之后发现确实跟我想的差不多——它就是用 T3 Stack 这一套全栈 TypeScript 技术栈做的代码片段管理工具只不过人家把类型安全这件事做到了骨子里连 API 层的数据流都是通到前端组件里的。这个项目最值得聊的不是它功能有多炫而是它把Next.js tRPC Prisma Tailwind NextAuth这几样东西如何无缝咬合给完整演示了一遍。你要是正在纠结前端怎么调后端接口、要不要为了一个 CRUD 硬上一套 REST 规范那这个项目的思路会很对你的胃口。不管你是刚接触全栈 TypeScript 的新人还是已经在写业务代码但想看看类型安全到底能推到多极致的开发者这篇拆解都值得你花十分钟看完。1. 项目缘起与技术选型思路1.1 为什么非要用 T3 StackT3 Stack 的核心口号是“类型安全至上”。这话听起来有点口号化但 t3code 这个项目把口号变成了一行行能跑的代码。它在技术选型上几乎没有任何多余的东西Next.js 负责页面和 SSRtRPC 负责 APIPrisma 负责数据模型和数据库Tailwind 负责样式NextAuth 负责登录。整套下来你会发现它没有单独再搞一层 REST API也没有手写一堆 interface 去定义请求和响应类型因为 tRPC 会直接从后端路由推导出前端调用时的类型。我在实际体验中最强烈的感受是写 API 和写业务代码可以完全不分开甚至路由文件就放在 pages 目录同级的 server 目录下改动一个类型前端引用处立刻报错。这种开发节奏和以前那种“联调看文档、出错看 postman”的流程完全不是一个体验。你只需要跟着 TypeScript 编译器的错误提示走就能知道哪里参数不对哪里返回值类型对不上。t3code 这个项目本身就是这种开发方式的最佳展示台——它所有增删改查的逻辑都走 tRPC mutation所有数据读取都走 tRPC query全链路类型安全的成果会让人越写越上瘾。1.2 这套组合解决了什么实际痛点做过业务的人应该都有体会前后端接口对接最大的成本其实不在写接口而在沟通和排错。今天后端把字段名改了没通知你明天接口返回的嵌套结构和文档对不上这些都是日常。T3 Stack 的思路是把这些坑堵在编译期连运行都省了。t3code 就是一个典型例子它的数据库里存储用户、代码片段、标签这些实体Prisma 负责生成类型安全的 ClienttRPC 再把这些 Client 的返回类型直接导出到前端组件里。换句话说从数据库表结构到页面显示的数据结构整个类型链是通的。这套组合替代掉的是你过去可能需要的 axios 封装的 interface 定义、swagger 文档的维护、以及为了解决联调问题而引入的一堆中间层。它用一套更简单的方案把这些复杂度消灭了换来的是项目结构更清晰开发心智负担更低。T3 Stack 的“渐进式”原则也体现在这里它不是让你一次就把所有边界情况都处理完而是先用最简洁的类型安全方案把业务串起来后面有更复杂的需求再加东西不至于一上来就被各种配置淹没。1.3 项目定位与功能范围t3code 做的是一个小而完整的代码片段管理工具功能上覆盖了常见的需求登录后可以创建代码片段、给片段打标签、按标签筛选、支持代码高亮显示、还能直接复制内容。听起来功能不多但每一个功能都对应着 T3 Stack 里一条完整的数据流。比如创建片段这件事从前端表单提交到 tRPC mutation再到 Prisma 写入数据库最后刷新列表数据中间没有任何手工维护的类型定义所有步骤都是编译器帮你看管着。这种项目的价值就在于麻雀虽小五脏俱全适合拿来当全栈 TypeScript 的样板工程反复咀嚼。2. 项目结构与目录设计2.1 初始化项目时最容易被忽略的选择题如果你也想自己拉一个 t3code 类似的工程先别急着npm init直接用官方脚手架是最省心的路径。命令很简单pnpm create t3-applatest t3code创建过程中它会让你勾选用哪些模块。我这里建议第一遍先老老实实把四个默认选项都勾上Next.js、tRPC、Prisma、Tailwind再有余力可以把 NextAuth 也选上。因为 t3code 这个项目的核心价值就在于这些模块之间的协作你少一个后续看代码的时候就会少一截理解链条。它默认的src目录已经帮你分好了server和pages两大部分这个结构很符合 T3 的直观原则凡是跟数据库、API 相关的都放 server凡是跟页面渲染相关的都放 pages谁也不跨界。创建完成后它还会自动帮你初始化 Prisma Schema、生成.env配置文件以及把 Tailwind 的三件套globals.css、tailwind.config、postcss.config都摆到该在的位置。你要做的就是打开schema.prisma开始定义自己的模型别在这种可重复的配置上浪费时间。2.2 目录结构背后的设计意图t3code 的 src 目录看起来可能有点让人困惑尤其是第一次接触 T3 的人。我拆开讲一下关键部分src/server/api/routers这是 tRPC 路由的所在地每个文件对应一组业务接口。t3code 里就会有一个snippet.ts里面定义了create、getAll、delete这些 mutation 和 query。src/server/db.tsPrisma Client 的实例化就放在这里。它做了全局缓存避免开发环境下每次热更新都重新 new 一个 PrismaClient导致连接数被打爆。src/pages/api/trpc/[trpc].ts这是 Next.js 与 tRPC 之间的桥梁文件tRPC 的所有请求都通过这个 API 路由入口进来。正常开发时你基本不用改它但得知道它背后的作用它把 Next.js 的 API 能力交给了 tRPC。src/utils/api.ts这是前端调用 tRPC 的唯一入口封装了 React Query 的 hooks 生成逻辑你会在组件里直接import { api } from ~/utils/api然后使用api.snippet.getAll.useQuery()这种形式取数据。这几个目录之间没有多余的绕弯每层都有明确职责。t3code 能保持代码清爽很重要的原因就是它尊重了这套默认结构没有业务代码污染到错误位置。2.3 数据模型设计用 Prisma 建模的取舍数据模型是整个项目的地基t3code 在 Prisma Schema 里定义了 User、Snippet、Tag 三张表。我简化一下核心模型model User { id String id default(cuid()) name String? email String? unique snippets Snippet[] accounts Account[] } model Snippet { id String id default(cuid()) title String description String? code String language String default(plaintext) tags Tag[] author User relation(fields: [authorId], references: [id], onDelete: Cascade) authorId String createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Tag { id String id default(cuid()) name String snippets Snippet[] }这里要特别注意几个细节。第一是default(cuid())而不是自增 id好处是分布式友好而且不容易暴露数据规模。第二是onDelete: Cascade删除用户时顺带把代码片段删掉避免孤儿数据。第三是 uid 和 email 的关系Prisma 里如果两个字段都想唯一你需要用unique标注这里我们把 email 设为可选唯一正好对上 NextAuth 的邮箱登录场景。如果你在 t3code 上继续扩展比如想加收藏功能就直接在 Snippet 上加一个多对多关系表Prisma 会自动帮你处理好连接表。2.4 数据库迁移的正确姿势很多人第一次用 Prisma 都会在迁移上翻车。t3code 这种项目最安全的操作顺序是先把模型改好然后跑npx prisma migrate dev --name init生成迁移文件再跑npx prisma generate重新生成 Client。注意不要在改完模型之后忘了 generate否则 tRPC 路由里拿到的 Prisma Client 还是旧类型编译器就会提示各种字段不存在。这个坑我踩过不止一次每次都是等编辑器飘红一片才反应过来。如果你用的数据库不是本地 Postgres而是 SQLite 想快速跑通那记得在.env里把DATABASE_URL改成 sqlite 的格式。不过我的建议是既然都上 T3 Stack 了直接用 Postgres 更合适SQLite 的并发能力和类型特性都有限后期再切数据库反而麻烦。3. 核心实现tRPC 路由与类型安全链路3.1 先理解 tRPC 的 Context 和 RoutertRPC 的整个设计都建立在 Context 之上。t3code 的createTRPCContext会在每个请求进来的时候把当前登录用户的信息查出来然后塞进上下文里。这个信息在后面的每一个路由处理器里都能拿到非常方便。它的实现大概是export const createTRPCContext async (opts: { headers: Headers }) { const session await getServerSession(authOptions); return { db, userId: session?.user?.id, }; };这个上下文里的userId会成为所有业务路由的鉴权基础。比如在创建片段的 mutation 里你不需要自己再走一遍登录校验只需要从ctx.userId判断是否为 null 就知道该不该拒绝请求。这种设计让业务代码变得非常干净所有跟用户相关的逻辑都从同一个源头取数据。你再看 t3code 的 router 定义就会发现它几乎不用去关心当前用户是谁因为已经由 Context 层统一处理了。Router 在这里的作用就像是业务模块的总线。根路由使用createTRPCProxyRouter组合出来export const appRouter createTRPCRouter({ snippet: snippetRouter, user: userRouter, });前端的api对象就是由这个appRouter的类型推导出来的。你不写自定义的类型定义也不搞单独的 d.ts一切由编译器帮你完成。3.2 代码片段 CRUD 的完整实现来看 t3code 里 snippet router 的实现思路核心代码大约长这样import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const snippetRouter createTRPCRouter({ getAll: publicProcedure.query(async ({ ctx }) { return ctx.db.snippet.findMany({ orderBy: { createdAt: desc }, include: { tags: true }, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1), code: z.string().min(1), language: z.string().optional(), tags: z.array(z.string()).default([]), }) ) .mutation(async ({ ctx, input }) { return ctx.db.snippet.create({ data: { title: input.title, code: input.code, language: input.language ?? plaintext, tags: { connectOrCreate: input.tags.map((name) ({ where: { name }, create: { name }, })), }, authorId: ctx.userId, }, }); }), delete: protectedProcedure .input(z.object({ id: z.string() })) .mutation(async ({ ctx, input }) { await ctx.db.snippet.deleteMany({ where: { id: input.id, authorId: ctx.userId }, }); }), });这里有几个值得展开说的地方。首先是.input()里面的 zod schema它不止做类型校验还直接指导了前端的类型推导。你在前端调用api.snippet.create.useMutation()的时候TS 会知道参数应该是{ title: string; code: string; language?: string; tags: string[] }多一个字段少一个字段都跑不了。其次是deleteMany的用法这里没有用delete而是deleteMany因为要在删除时同时限定id和authorId确保用户不能删别人的片段。如果用delete你还得先查一遍这条数据属不属于自己多一步查询不说还容易漏掉鉴权条件。connectOrCreate也是个很好用的 Prisma 特性给片段打标签时如果标签已经存在就直接关联不存在就先创建再关联。这样避免了先查标签再创建的逻辑一行代码就把事做了。我看到这个用法的时候确实眼前一亮很多人写多对多关联都会在“先查还是先建”上纠结半天。3.3 前端调用链路为什么这么丝滑在 t3code 的组件里你几乎看不到 fetch 或者 axios因为所有数据获取都统一走了api对象。举个例子const { data: snippets, refetch } api.snippet.getAll.useQuery(); const createSnippet api.snippet.create.useMutation({ onSuccess: () refetch(), });这段代码最妙的地方是useQuery和useMutation都是类型推导出来的。snippets的类型直接就是 Prisma 查询返回的类型里面的每个字段都有完整的补全提示不存在“啊这个字段到底叫 createdAt 还是 create_time”这种问题。而且useQuery默认带了 React Query 的缓存策略切换页面或者重新聚焦窗口时数据会自动失效你不需要手动管理 loading 状态和错误状态。React Query 的缓存机制也对 t3code 这类工具很友好。假设你在详情页编辑了一个片段返回列表页时数据会自动更新不会出现手动刷新页面才能看到最新内容的尴尬。T3 选择把 React Query 作为数据请求的状态管理方案我认为是很务实的——它没让你自己封装一套 useSWR也没有让你在组件里到处 try/catch而是把这些异步状态处理统一交给一个久经考验的库开发体验自然就顺了。3.4 关于 protectedProcedure 的鉴权设计T3 Stack 里有两个已经帮你封装好的 procedurepublicProcedure和protectedProceduret3code 里大量使用了后者。它的实现本质上是在调用业务逻辑之前先检查 Context 里有没有用户信息export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.userId) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { userId: ctx.userId } }); });这种方式比起在每个路由里手动判断优势是集中且可复用。以后你想加一个 admin 权限只需要再写一个adminProcedure在里头判断用户角色即可。这种基于中间件的扩展方式让权限模型的演进变得非常简单几乎不用改动已有路由的代码。4. 认证集成与样式方案NextAuth Tailwind 的实战细节4.1 NextAuth 与 tRPC 的结合方式很多用 NextAuth 的人会把登录逻辑完全放在 Next.js 的页面层处理但在 T3 Stack 里tRPC 的 Context 直接依赖 NextAuth 的 Session。这个结合点就在getServerSession(authOptions)的调用上。t3code 的做法是把它放到创建 tRPC Context 的地方这样每个 tRPC 请求都能通过 Session 拿到当前用户信息。authOptions的定义一般放在src/server/auth.ts里里面包含 NextAuth 的 providers 和 callbacks。t3code 用了 GitHub Provider也兼容邮箱登录。在 GitHub 登录场景下你需要去 GitHub 的 OAuth Apps 页面申请一个 Client ID 和 Client Secret然后填进.env文件里。这里要注意的是回调地址要依环境区分本地开发时是http://localhost:3000/api/auth/callback/github线上是https://你的域名/api/auth/callback/github漏一个就得踩半天回调地址不匹配的坑。Session 的 callback 部分我建议不要把整个 User 对象塞进 Session。你在 callback 里返回什么前端就多什么东西。t3code 的做法很克俭只保留了user.id和user.name需要更多信息时再去数据库查。这样 Session 保持轻量也不会因为 Session 内容过大影响性能。4.2 受保护页面的两种常见实现登录后的页面怎么保护t3code 采用的是双保险方案。服务端层面getServerSideProps 里先判断 Session没登录就重定向到登录页客户端层面中间件或者布局组件再判断一次防止未被保护的 API 被直接调用时出现前端展示异常。实际上 T3 Stack 脚手架默认在根路径的middleware.ts里配置了 matcher你可以选择让部分路由必须登录。比如 t3code 里/dashboard、/snippet/new这类页面就应该放进matcher数组否则未登录用户能直接访问页面虽然背后 tRPC 有保护但体验上还是略粗糙。我个人的习惯是页面级的路由用 middleware 保护接口级的路由用 tRPC 的 protectedProcedure 保护两层各司其职基本能杜绝越权访问。4.3 Tailwind 写界面时的响应式心得Tailwind 在 t3code 里扮演的角色很纯粹——负责所有样式。这个项目界面不复杂但麻雀虽小响应式布局的坑却一个不少。比如代码片段卡片在手机上应该单列显示在平板及以上应该两列这时候可以用grid grid-cols-1 md:grid-cols-2一个类搞定不需要写任何媒体查询代码。代码高亮部分t3code 用的是react-syntax-highlighter配合 Prism 主题。这个库的体积不小但胜在开箱即用。如果你对包体积敏感可以考虑用shiki或者highlight.js的轻量模式。我自己的经验是如果只是展示少量示例代码react-syntax-highlighter是效率最高的方案如果代码库大、场景复杂shiki的 Web Worker 高亮体验会更好不过配置复杂度也会上一个台阶。Tailwind 还有一个容易被忽略的配置点自定义主题。你要在tailwind.config.ts里扩展colors才能让项目里出现bg-primary text-secondary这类语义化类名。t3code 用了经典的暗色主题配合代码高亮看起来很舒服。第一次跑起来看到暗色 UI 的时候整体质感确实比默认白底高出不少。5. 部署上线与问题排查实录5.1 从本地到线上部署需要注意的三个细节t3code 部署起来其实不复杂因为它是标准的 Next.js 应用可以直接部署在很多平台上。我自己试过两台不同的服务器流程基本一致先构建项目再启动生产服务。命令只有这几行pnpm install pnpm run build pnpm start但你千万不要以为这就完了有几个坑是绕不过去的。第一是数据库连接串必须改成线上数据库的地址本地 Postgres 的连接串在线上环境里是跑不通的。第二是.env文件一定要在部署环境里重新配置尤其是NEXTAUTH_SECRET、GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET这几个值绝对不能沿用本地的。第三是数据库必须先跑完迁移你需要执行npx prisma migrate deploy而不是migrate dev因为migrate dev只有在开发环境才能正常工作。我曾经在部署时忘记跑迁移启动后所有查数据的接口全部报错日志里全是“table does not exist”。那个排查过程说多了都是泪。现在养成习惯了部署前先看一眼数据库迁移状态再启动服务省心太多。5.2 本地开发中我踩过的几个典型坑头一个坑是 NextAuth 报NEXTAUTH_SECRET缺失。这个错误出现得很频繁尤其是你想给程序加登录功能时。解决办法是随便生成一个长的随机字符串填到.env里比如用 openssl 命令openssl rand -base64 32第二个坑是 GitHub OAuth 回调地址不对导致登录按钮点了之后跳回401。这个真的特别容易出问题。你在 GitHub 后台填回调地址的时候域名部分必须和你访问的地址完全一致包括端口号。本地是http://localhost:3000/api/auth/callback/github你要是配成127.0.0.1:3000或者漏写端口那基本就是秒失败。第三个坑是 Tailwind 的类名没生效。别慌先检查是不是内容文件路径配的不全。在tailwind.config.ts里content要包含所有用到类名的文件目录。如果你建了一个新目录比如components/editor但没加进 content那这个目录里写的类名都会被抛弃页面就会“裸奔”。排查方法也很简单看浏览器开发者工具里体积最大的 CSS 文件是否包含你写的类名。第四个坑在 tRPC 报错上。一旦你出现 “No procedure found on server 这类提示基本是客户端和服务端的 router 不一致导致的。可能的原因有两种一种是前端缓存了旧的类型定义重启开发服务器就好了另一种是你改了 router 文件名比如从snippetRouter改成codeRouter但没同步更新根 router 里的引用。要么重建要么检查 import 路径基本都是这两件事。5.3 遇到问题时的排查工具和思路提到排查问题我强烈推荐你在开发环境打开 tRPC 的日志面板然后用浏览器的 Network 面板追踪请求。T3 Stack 的 tRPC 请求都走/api/trpc/*路径在 Network 面板里能直观看到返回的错误码和错误信息。不要一上来就瞎改代码先看请求到底挂了哪一层是 NextAuth 回调失败还是 tRPC 中间件报错还是 Prisma 查询失败。把问题定位到层再去看对应层的源码效率会高出非常多。如果你用的是 Postgres数据库层面的排查还可以看 Prisma Studio。这个工具内置在 Prisma 里直接运行npx prisma studio你就能在浏览器里直接查看和编辑数据库里的数据。当年我在调试 t3code 的标签关联逻辑时就是通过 Prisma Studio 查看_TagToSnippet这个关系表才发现连接表数据没写进去进而定位到是connectOrCreate的where条件写错了。这种可视化工具和编译器提示配合起来能省去大量控制台打日志的时间。5.4 这些小习惯能让项目长期可维护最后我想补充一点不是所有技术问题而是项目维护层面的经验。t3code 这种项目骨架很适合长期迭代但前提是你要养成一些好习惯。我的习惯是任何时候改数据库模型第一件事就是跑prisma migrate dev然后立刻prisma generate保证本地类型和数据库结构同步。改完 tRPC 路由之后最好直接去写前端的调用代码让 TS 编译器帮你检查类型匹配。长期下来你的开发流程会越来越顺。还有一点尽量保持路由文件的单一职责。t3code 的 snippet router 里只放片段相关接口别把用户相关接口混进去。如果你发现一个 router 文件超过两百行开始出现大段重复逻辑那大概率是你需要拆文件或者抽公共中间件了。T3 Stack 提供了足够灵活的扩展能力但不代表你需要在一开始就把功能都堆上来。渐进式开发才是长期可维护的关键。综合下来t3code 这个项目给我的最大启发是全栈 TypeScript 并不是一种标语式的口号而是可以落地到日常开发流里的实实在在的工作方式。它把从前端到后端到数据库的完整链路都放在同一套类型系统里缩短了联调周期减少了心智负担也让代码结构更透明。如果你也想快速体验这种开发节奏找一个像代码片段管理这样的小工具练手是最合适的路径。等你把 CRUD、认证、样式、部署这些环节都打通一遍再回去写业务系统会有一种“原来全栈也可以这么清爽”的感觉。
说实话刚看到t3code这个名字的时候我第一反应是这哥们儿要么在搞 T3 Stack 全家桶要么就是一个跟代码片段管理相关的工具项目。等我把整个项目拉下来过了一遍之后发现确实跟我想的差不多——它就是用 T3 Stack 这一套全栈 TypeScript 技术栈做的代码片段管理工具只不过人家把类型安全这件事做到了骨子里连 API 层的数据流都是通到前端组件里的。这个项目最值得聊的不是它功能有多炫而是它把Next.js tRPC Prisma Tailwind NextAuth这几样东西如何无缝咬合给完整演示了一遍。你要是正在纠结前端怎么调后端接口、要不要为了一个 CRUD 硬上一套 REST 规范那这个项目的思路会很对你的胃口。不管你是刚接触全栈 TypeScript 的新人还是已经在写业务代码但想看看类型安全到底能推到多极致的开发者这篇拆解都值得你花十分钟看完。1. 项目缘起与技术选型思路1.1 为什么非要用 T3 StackT3 Stack 的核心口号是“类型安全至上”。这话听起来有点口号化但 t3code 这个项目把口号变成了一行行能跑的代码。它在技术选型上几乎没有任何多余的东西Next.js 负责页面和 SSRtRPC 负责 APIPrisma 负责数据模型和数据库Tailwind 负责样式NextAuth 负责登录。整套下来你会发现它没有单独再搞一层 REST API也没有手写一堆 interface 去定义请求和响应类型因为 tRPC 会直接从后端路由推导出前端调用时的类型。我在实际体验中最强烈的感受是写 API 和写业务代码可以完全不分开甚至路由文件就放在 pages 目录同级的 server 目录下改动一个类型前端引用处立刻报错。这种开发节奏和以前那种“联调看文档、出错看 postman”的流程完全不是一个体验。你只需要跟着 TypeScript 编译器的错误提示走就能知道哪里参数不对哪里返回值类型对不上。t3code 这个项目本身就是这种开发方式的最佳展示台——它所有增删改查的逻辑都走 tRPC mutation所有数据读取都走 tRPC query全链路类型安全的成果会让人越写越上瘾。1.2 这套组合解决了什么实际痛点做过业务的人应该都有体会前后端接口对接最大的成本其实不在写接口而在沟通和排错。今天后端把字段名改了没通知你明天接口返回的嵌套结构和文档对不上这些都是日常。T3 Stack 的思路是把这些坑堵在编译期连运行都省了。t3code 就是一个典型例子它的数据库里存储用户、代码片段、标签这些实体Prisma 负责生成类型安全的 ClienttRPC 再把这些 Client 的返回类型直接导出到前端组件里。换句话说从数据库表结构到页面显示的数据结构整个类型链是通的。这套组合替代掉的是你过去可能需要的 axios 封装的 interface 定义、swagger 文档的维护、以及为了解决联调问题而引入的一堆中间层。它用一套更简单的方案把这些复杂度消灭了换来的是项目结构更清晰开发心智负担更低。T3 Stack 的“渐进式”原则也体现在这里它不是让你一次就把所有边界情况都处理完而是先用最简洁的类型安全方案把业务串起来后面有更复杂的需求再加东西不至于一上来就被各种配置淹没。1.3 项目定位与功能范围t3code 做的是一个小而完整的代码片段管理工具功能上覆盖了常见的需求登录后可以创建代码片段、给片段打标签、按标签筛选、支持代码高亮显示、还能直接复制内容。听起来功能不多但每一个功能都对应着 T3 Stack 里一条完整的数据流。比如创建片段这件事从前端表单提交到 tRPC mutation再到 Prisma 写入数据库最后刷新列表数据中间没有任何手工维护的类型定义所有步骤都是编译器帮你看管着。这种项目的价值就在于麻雀虽小五脏俱全适合拿来当全栈 TypeScript 的样板工程反复咀嚼。2. 项目结构与目录设计2.1 初始化项目时最容易被忽略的选择题如果你也想自己拉一个 t3code 类似的工程先别急着npm init直接用官方脚手架是最省心的路径。命令很简单pnpm create t3-applatest t3code创建过程中它会让你勾选用哪些模块。我这里建议第一遍先老老实实把四个默认选项都勾上Next.js、tRPC、Prisma、Tailwind再有余力可以把 NextAuth 也选上。因为 t3code 这个项目的核心价值就在于这些模块之间的协作你少一个后续看代码的时候就会少一截理解链条。它默认的src目录已经帮你分好了server和pages两大部分这个结构很符合 T3 的直观原则凡是跟数据库、API 相关的都放 server凡是跟页面渲染相关的都放 pages谁也不跨界。创建完成后它还会自动帮你初始化 Prisma Schema、生成.env配置文件以及把 Tailwind 的三件套globals.css、tailwind.config、postcss.config都摆到该在的位置。你要做的就是打开schema.prisma开始定义自己的模型别在这种可重复的配置上浪费时间。2.2 目录结构背后的设计意图t3code 的 src 目录看起来可能有点让人困惑尤其是第一次接触 T3 的人。我拆开讲一下关键部分src/server/api/routers这是 tRPC 路由的所在地每个文件对应一组业务接口。t3code 里就会有一个snippet.ts里面定义了create、getAll、delete这些 mutation 和 query。src/server/db.tsPrisma Client 的实例化就放在这里。它做了全局缓存避免开发环境下每次热更新都重新 new 一个 PrismaClient导致连接数被打爆。src/pages/api/trpc/[trpc].ts这是 Next.js 与 tRPC 之间的桥梁文件tRPC 的所有请求都通过这个 API 路由入口进来。正常开发时你基本不用改它但得知道它背后的作用它把 Next.js 的 API 能力交给了 tRPC。src/utils/api.ts这是前端调用 tRPC 的唯一入口封装了 React Query 的 hooks 生成逻辑你会在组件里直接import { api } from ~/utils/api然后使用api.snippet.getAll.useQuery()这种形式取数据。这几个目录之间没有多余的绕弯每层都有明确职责。t3code 能保持代码清爽很重要的原因就是它尊重了这套默认结构没有业务代码污染到错误位置。2.3 数据模型设计用 Prisma 建模的取舍数据模型是整个项目的地基t3code 在 Prisma Schema 里定义了 User、Snippet、Tag 三张表。我简化一下核心模型model User { id String id default(cuid()) name String? email String? unique snippets Snippet[] accounts Account[] } model Snippet { id String id default(cuid()) title String description String? code String language String default(plaintext) tags Tag[] author User relation(fields: [authorId], references: [id], onDelete: Cascade) authorId String createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Tag { id String id default(cuid()) name String snippets Snippet[] }这里要特别注意几个细节。第一是default(cuid())而不是自增 id好处是分布式友好而且不容易暴露数据规模。第二是onDelete: Cascade删除用户时顺带把代码片段删掉避免孤儿数据。第三是 uid 和 email 的关系Prisma 里如果两个字段都想唯一你需要用unique标注这里我们把 email 设为可选唯一正好对上 NextAuth 的邮箱登录场景。如果你在 t3code 上继续扩展比如想加收藏功能就直接在 Snippet 上加一个多对多关系表Prisma 会自动帮你处理好连接表。2.4 数据库迁移的正确姿势很多人第一次用 Prisma 都会在迁移上翻车。t3code 这种项目最安全的操作顺序是先把模型改好然后跑npx prisma migrate dev --name init生成迁移文件再跑npx prisma generate重新生成 Client。注意不要在改完模型之后忘了 generate否则 tRPC 路由里拿到的 Prisma Client 还是旧类型编译器就会提示各种字段不存在。这个坑我踩过不止一次每次都是等编辑器飘红一片才反应过来。如果你用的数据库不是本地 Postgres而是 SQLite 想快速跑通那记得在.env里把DATABASE_URL改成 sqlite 的格式。不过我的建议是既然都上 T3 Stack 了直接用 Postgres 更合适SQLite 的并发能力和类型特性都有限后期再切数据库反而麻烦。3. 核心实现tRPC 路由与类型安全链路3.1 先理解 tRPC 的 Context 和 RoutertRPC 的整个设计都建立在 Context 之上。t3code 的createTRPCContext会在每个请求进来的时候把当前登录用户的信息查出来然后塞进上下文里。这个信息在后面的每一个路由处理器里都能拿到非常方便。它的实现大概是export const createTRPCContext async (opts: { headers: Headers }) { const session await getServerSession(authOptions); return { db, userId: session?.user?.id, }; };这个上下文里的userId会成为所有业务路由的鉴权基础。比如在创建片段的 mutation 里你不需要自己再走一遍登录校验只需要从ctx.userId判断是否为 null 就知道该不该拒绝请求。这种设计让业务代码变得非常干净所有跟用户相关的逻辑都从同一个源头取数据。你再看 t3code 的 router 定义就会发现它几乎不用去关心当前用户是谁因为已经由 Context 层统一处理了。Router 在这里的作用就像是业务模块的总线。根路由使用createTRPCProxyRouter组合出来export const appRouter createTRPCRouter({ snippet: snippetRouter, user: userRouter, });前端的api对象就是由这个appRouter的类型推导出来的。你不写自定义的类型定义也不搞单独的 d.ts一切由编译器帮你完成。3.2 代码片段 CRUD 的完整实现来看 t3code 里 snippet router 的实现思路核心代码大约长这样import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const snippetRouter createTRPCRouter({ getAll: publicProcedure.query(async ({ ctx }) { return ctx.db.snippet.findMany({ orderBy: { createdAt: desc }, include: { tags: true }, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1), code: z.string().min(1), language: z.string().optional(), tags: z.array(z.string()).default([]), }) ) .mutation(async ({ ctx, input }) { return ctx.db.snippet.create({ data: { title: input.title, code: input.code, language: input.language ?? plaintext, tags: { connectOrCreate: input.tags.map((name) ({ where: { name }, create: { name }, })), }, authorId: ctx.userId, }, }); }), delete: protectedProcedure .input(z.object({ id: z.string() })) .mutation(async ({ ctx, input }) { await ctx.db.snippet.deleteMany({ where: { id: input.id, authorId: ctx.userId }, }); }), });这里有几个值得展开说的地方。首先是.input()里面的 zod schema它不止做类型校验还直接指导了前端的类型推导。你在前端调用api.snippet.create.useMutation()的时候TS 会知道参数应该是{ title: string; code: string; language?: string; tags: string[] }多一个字段少一个字段都跑不了。其次是deleteMany的用法这里没有用delete而是deleteMany因为要在删除时同时限定id和authorId确保用户不能删别人的片段。如果用delete你还得先查一遍这条数据属不属于自己多一步查询不说还容易漏掉鉴权条件。connectOrCreate也是个很好用的 Prisma 特性给片段打标签时如果标签已经存在就直接关联不存在就先创建再关联。这样避免了先查标签再创建的逻辑一行代码就把事做了。我看到这个用法的时候确实眼前一亮很多人写多对多关联都会在“先查还是先建”上纠结半天。3.3 前端调用链路为什么这么丝滑在 t3code 的组件里你几乎看不到 fetch 或者 axios因为所有数据获取都统一走了api对象。举个例子const { data: snippets, refetch } api.snippet.getAll.useQuery(); const createSnippet api.snippet.create.useMutation({ onSuccess: () refetch(), });这段代码最妙的地方是useQuery和useMutation都是类型推导出来的。snippets的类型直接就是 Prisma 查询返回的类型里面的每个字段都有完整的补全提示不存在“啊这个字段到底叫 createdAt 还是 create_time”这种问题。而且useQuery默认带了 React Query 的缓存策略切换页面或者重新聚焦窗口时数据会自动失效你不需要手动管理 loading 状态和错误状态。React Query 的缓存机制也对 t3code 这类工具很友好。假设你在详情页编辑了一个片段返回列表页时数据会自动更新不会出现手动刷新页面才能看到最新内容的尴尬。T3 选择把 React Query 作为数据请求的状态管理方案我认为是很务实的——它没让你自己封装一套 useSWR也没有让你在组件里到处 try/catch而是把这些异步状态处理统一交给一个久经考验的库开发体验自然就顺了。3.4 关于 protectedProcedure 的鉴权设计T3 Stack 里有两个已经帮你封装好的 procedurepublicProcedure和protectedProceduret3code 里大量使用了后者。它的实现本质上是在调用业务逻辑之前先检查 Context 里有没有用户信息export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.userId) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { userId: ctx.userId } }); });这种方式比起在每个路由里手动判断优势是集中且可复用。以后你想加一个 admin 权限只需要再写一个adminProcedure在里头判断用户角色即可。这种基于中间件的扩展方式让权限模型的演进变得非常简单几乎不用改动已有路由的代码。4. 认证集成与样式方案NextAuth Tailwind 的实战细节4.1 NextAuth 与 tRPC 的结合方式很多用 NextAuth 的人会把登录逻辑完全放在 Next.js 的页面层处理但在 T3 Stack 里tRPC 的 Context 直接依赖 NextAuth 的 Session。这个结合点就在getServerSession(authOptions)的调用上。t3code 的做法是把它放到创建 tRPC Context 的地方这样每个 tRPC 请求都能通过 Session 拿到当前用户信息。authOptions的定义一般放在src/server/auth.ts里里面包含 NextAuth 的 providers 和 callbacks。t3code 用了 GitHub Provider也兼容邮箱登录。在 GitHub 登录场景下你需要去 GitHub 的 OAuth Apps 页面申请一个 Client ID 和 Client Secret然后填进.env文件里。这里要注意的是回调地址要依环境区分本地开发时是http://localhost:3000/api/auth/callback/github线上是https://你的域名/api/auth/callback/github漏一个就得踩半天回调地址不匹配的坑。Session 的 callback 部分我建议不要把整个 User 对象塞进 Session。你在 callback 里返回什么前端就多什么东西。t3code 的做法很克俭只保留了user.id和user.name需要更多信息时再去数据库查。这样 Session 保持轻量也不会因为 Session 内容过大影响性能。4.2 受保护页面的两种常见实现登录后的页面怎么保护t3code 采用的是双保险方案。服务端层面getServerSideProps 里先判断 Session没登录就重定向到登录页客户端层面中间件或者布局组件再判断一次防止未被保护的 API 被直接调用时出现前端展示异常。实际上 T3 Stack 脚手架默认在根路径的middleware.ts里配置了 matcher你可以选择让部分路由必须登录。比如 t3code 里/dashboard、/snippet/new这类页面就应该放进matcher数组否则未登录用户能直接访问页面虽然背后 tRPC 有保护但体验上还是略粗糙。我个人的习惯是页面级的路由用 middleware 保护接口级的路由用 tRPC 的 protectedProcedure 保护两层各司其职基本能杜绝越权访问。4.3 Tailwind 写界面时的响应式心得Tailwind 在 t3code 里扮演的角色很纯粹——负责所有样式。这个项目界面不复杂但麻雀虽小响应式布局的坑却一个不少。比如代码片段卡片在手机上应该单列显示在平板及以上应该两列这时候可以用grid grid-cols-1 md:grid-cols-2一个类搞定不需要写任何媒体查询代码。代码高亮部分t3code 用的是react-syntax-highlighter配合 Prism 主题。这个库的体积不小但胜在开箱即用。如果你对包体积敏感可以考虑用shiki或者highlight.js的轻量模式。我自己的经验是如果只是展示少量示例代码react-syntax-highlighter是效率最高的方案如果代码库大、场景复杂shiki的 Web Worker 高亮体验会更好不过配置复杂度也会上一个台阶。Tailwind 还有一个容易被忽略的配置点自定义主题。你要在tailwind.config.ts里扩展colors才能让项目里出现bg-primary text-secondary这类语义化类名。t3code 用了经典的暗色主题配合代码高亮看起来很舒服。第一次跑起来看到暗色 UI 的时候整体质感确实比默认白底高出不少。5. 部署上线与问题排查实录5.1 从本地到线上部署需要注意的三个细节t3code 部署起来其实不复杂因为它是标准的 Next.js 应用可以直接部署在很多平台上。我自己试过两台不同的服务器流程基本一致先构建项目再启动生产服务。命令只有这几行pnpm install pnpm run build pnpm start但你千万不要以为这就完了有几个坑是绕不过去的。第一是数据库连接串必须改成线上数据库的地址本地 Postgres 的连接串在线上环境里是跑不通的。第二是.env文件一定要在部署环境里重新配置尤其是NEXTAUTH_SECRET、GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET这几个值绝对不能沿用本地的。第三是数据库必须先跑完迁移你需要执行npx prisma migrate deploy而不是migrate dev因为migrate dev只有在开发环境才能正常工作。我曾经在部署时忘记跑迁移启动后所有查数据的接口全部报错日志里全是“table does not exist”。那个排查过程说多了都是泪。现在养成习惯了部署前先看一眼数据库迁移状态再启动服务省心太多。5.2 本地开发中我踩过的几个典型坑头一个坑是 NextAuth 报NEXTAUTH_SECRET缺失。这个错误出现得很频繁尤其是你想给程序加登录功能时。解决办法是随便生成一个长的随机字符串填到.env里比如用 openssl 命令openssl rand -base64 32第二个坑是 GitHub OAuth 回调地址不对导致登录按钮点了之后跳回401。这个真的特别容易出问题。你在 GitHub 后台填回调地址的时候域名部分必须和你访问的地址完全一致包括端口号。本地是http://localhost:3000/api/auth/callback/github你要是配成127.0.0.1:3000或者漏写端口那基本就是秒失败。第三个坑是 Tailwind 的类名没生效。别慌先检查是不是内容文件路径配的不全。在tailwind.config.ts里content要包含所有用到类名的文件目录。如果你建了一个新目录比如components/editor但没加进 content那这个目录里写的类名都会被抛弃页面就会“裸奔”。排查方法也很简单看浏览器开发者工具里体积最大的 CSS 文件是否包含你写的类名。第四个坑在 tRPC 报错上。一旦你出现 “No procedure found on server 这类提示基本是客户端和服务端的 router 不一致导致的。可能的原因有两种一种是前端缓存了旧的类型定义重启开发服务器就好了另一种是你改了 router 文件名比如从snippetRouter改成codeRouter但没同步更新根 router 里的引用。要么重建要么检查 import 路径基本都是这两件事。5.3 遇到问题时的排查工具和思路提到排查问题我强烈推荐你在开发环境打开 tRPC 的日志面板然后用浏览器的 Network 面板追踪请求。T3 Stack 的 tRPC 请求都走/api/trpc/*路径在 Network 面板里能直观看到返回的错误码和错误信息。不要一上来就瞎改代码先看请求到底挂了哪一层是 NextAuth 回调失败还是 tRPC 中间件报错还是 Prisma 查询失败。把问题定位到层再去看对应层的源码效率会高出非常多。如果你用的是 Postgres数据库层面的排查还可以看 Prisma Studio。这个工具内置在 Prisma 里直接运行npx prisma studio你就能在浏览器里直接查看和编辑数据库里的数据。当年我在调试 t3code 的标签关联逻辑时就是通过 Prisma Studio 查看_TagToSnippet这个关系表才发现连接表数据没写进去进而定位到是connectOrCreate的where条件写错了。这种可视化工具和编译器提示配合起来能省去大量控制台打日志的时间。5.4 这些小习惯能让项目长期可维护最后我想补充一点不是所有技术问题而是项目维护层面的经验。t3code 这种项目骨架很适合长期迭代但前提是你要养成一些好习惯。我的习惯是任何时候改数据库模型第一件事就是跑prisma migrate dev然后立刻prisma generate保证本地类型和数据库结构同步。改完 tRPC 路由之后最好直接去写前端的调用代码让 TS 编译器帮你检查类型匹配。长期下来你的开发流程会越来越顺。还有一点尽量保持路由文件的单一职责。t3code 的 snippet router 里只放片段相关接口别把用户相关接口混进去。如果你发现一个 router 文件超过两百行开始出现大段重复逻辑那大概率是你需要拆文件或者抽公共中间件了。T3 Stack 提供了足够灵活的扩展能力但不代表你需要在一开始就把功能都堆上来。渐进式开发才是长期可维护的关键。综合下来t3code 这个项目给我的最大启发是全栈 TypeScript 并不是一种标语式的口号而是可以落地到日常开发流里的实实在在的工作方式。它把从前端到后端到数据库的完整链路都放在同一套类型系统里缩短了联调周期减少了心智负担也让代码结构更透明。如果你也想快速体验这种开发节奏找一个像代码片段管理这样的小工具练手是最合适的路径。等你把 CRUD、认证、样式、部署这些环节都打通一遍再回去写业务系统会有一种“原来全栈也可以这么清爽”的感觉。
