个人项目做到一半最难的不是写代码而是反复去翻自己以前写过的片段某个日期格式化函数、某段正则、某个组件的基础用法。项目多了之后本地笔记、聊天记录、旧仓库散落一堆真正要用的时候反而找不到。这就是我做 t3code 的起因——一个基于 T3 Stack 的轻量级代码片段管理工具专门解决自己的代码自己找不到这个问题。如果你正在学全栈、想找一个结构清晰且能直接跑通的参考项目或者跟我一样受不了碎片化笔记这篇文章会把从选型、数据建模到部署踩坑的完整过程都拆给你看。1. 从一个记不住代码的场景到 t3code 的定位这个项目最初的形态根本不是 web 应用。我最开始是在本地用 Markdown 文件按语言分目录整理代码片段配合编辑器全局搜索。用了一阵子就发现问题了本地文件没有标签体系跨语言搜索只能靠文件名想按场景回忆比如带鉴权的 fetch 封装的时候文件名根本不管用。后来临时起意写了个小的命令行工具用 SQLite 存片段、用 fts5 做全文搜索终端里 prompt 一下就能查。命令行工具解决了一部分问题但换电脑、手机上临时要看、想给别人分享某个片段这些场景全都没覆盖。于是我把需求重新梳理了一遍确定 t3code 的核心边界以片段为最小单位每个片段属于一个用户带标题、代码内容、语言、描述和多个标签支持全文搜索和标签筛选这是整个工具的刚需片段即开即用进入页面就能搜、能复制、能保存不搞复杂的工作流零成本部署个人使用为主但架构上预留多用户能力最初的 MVP 我只做了三件事新增片段、列表展示、按语言和标签筛选。搜索做到边输入边过滤就停住了没有一开始就上全文检索引擎。这个克制很重要——很多业余项目死在第一版就想把搜索、多人协、收藏、统计全做出来结果半年了还跑不起来。t3code 最大的教训就是把核心场景存、找、复制做到极致的体验远比功能堆砌有意义。做这个项目之前我也对比过现成的方案GitHub Gist 功能足够强但它是公网可见的私人片段要建 secret gist而且在移动端浏览体验一般Notion 的代码块管理能力不错但每次想插入一个片段都得层层展开页面。t3code 的差异化就一条——它是为了快速存、快速找、快速抄这个单一目的设计的所有交互都围绕这个目标转。2. 技术选型复盘T3 Stack 的每一层都不是白选的T3 Stack 这个名字来自 create-t3-app 这个脚手架核心组合是Next.js TypeScript tRPC Tailwind CSS数据库一般配 Prisma。选这套而不是自研后端 前端分离不是因为流行而是它非常匹配这个项目的实际约束单 repo、全栈 TypeScript、类型安全贯穿前后端、部署简单。2.1 为什么是 Next.js App Router 而不是传统 SPAt3code 的页面分为两类首屏搜索结果页和片段编辑页。用传统 React SPA 方案的话需要单独维护一套路由体系还得考虑 SEO虽然个人工具 SEO 需求很弱更麻烦的是服务端逻辑要额外起 Node 服务部署成本翻倍。Next.js App Router 把页面路由、API 路由、中间件都收在一个框架里部署到 Vercel 的时候一个项目就够了。实际用下来App Router 的 Server Component 对这个项目帮助很大首屏直接用服务端组件读取数据库渲染列表客户端组件只负责搜索框的受控输入和交互状态。这样首屏加载没有任何客户端请求瀑布Lighthouse 的 First Contentful Paint 压到了 0.8 秒以内。2.2 tRPC 为什么比 REST 和 GraphQL 都顺手这是 T3 Stack 里我最想展开讲的一层。先看个对比方案类型安全端到端类型共享学习成本服务端工作量REST OpenAPI中等需要代码生成低高写路由 文档 客户端 SDKGraphQL高需要 codegen较高高写 schema resolvertRPC极高零成本原生共享低低写一个函数导出即可tRPC 的做法颠覆了传统 API 设计思路不需要定义 URL、不需要序列化协议直接在服务端写一个函数procedure客户端 import 类型后就能像调用本地函数一样调用远程函数。类型从数据库查询结果一路“流”到 React 组件的 props中间没有任何断裂点。我举个例子t3code 里获取片段列表的 tRPC procedure 大概是这样的// server/api/routers/snippet.ts import { z } from zod; import { createTRPCRouter, protectedProcedure } from ~/server/api/trpc; export const snippetRouter createTRPCRouter({ list: protectedProcedure .input( z.object({ language: z.string().optional(), tag: z.string().optional(), search: z.string().optional(), }) ) .query(async ({ ctx, input }) { return ctx.db.snippet.findMany({ where: { userId: ctx.session.user.id, ...(input.language ? { language: input.language } : {}), ...(input.tag ? { tags: { some: { name: input.tag } } } : {}), ...(input.search ? { OR: [ { title: { contains: input.search } }, { code: { contains: input.search } }, { description: { contains: input.search } }, ], } : {}), }, orderBy: { updatedAt: desc }, }); }), });客户端调用更是简单到不像话const { data: snippets } api.snippet.list.useQuery({ search: keyword, language: selectedLanguage, });改一个查询条件类型立刻同步编辑器里写错字段名直接红波浪线。这种体验用惯了以后回去写 REST 接口会非常不适应。2.3 Prisma 与数据库选型的实际考量T3 Stack 默认推荐 Prisma我在 t3code 里也确实用了 Prisma。选它的两个决定因素一是 schema 文件足够直观改完模型跑一次prisma migrate就能拿到迁移 SQL对个人项目来说几乎不需要额外学习成本二是它的类型生成机制和 tRPC 是绝配——Prisma 查出来的对象类型可以直接作为 tRPC 的返回类型不需要手动定义 DTO 层。数据库我选的是 PostgreSQLNeon 的 serverless 版本原因也很简单部署到 Vercel 的环境里传统常驻数据库连接不划算serverless Postgres 支持连接池能扛住冷启动后的并发连接压力。Neon 还提供分支数据库功能我本地开发时直接neonctl branch create开一个分支测试完再合并非常干净。2.4 Tailwind 与组件方案的取舍样式层选了 Tailwind CSS shadcn/ui。这里我说下原因t3code 是个人工具没有设计资源shadcn/ui 提供的是可复制到项目里的源码组件不是封装死掉的 UI 库。我可以把 Dialog、DropdownMenu 这些组件直接改造成自己需要的样式而不需要去读一个抽象组件的源码。Tailwind 的实际体验是省掉了很多写类名的心理负担但要注意的是如果项目交互复杂className会变得很长。t3code 的做法是给高频组件提取了一层 wrapper比如SnippetCard把 Tailwind 类收敛在组件内部页面层保持干净。3. 数据模型与权限设计标签多对多、所有权隔离和搜索实现数据层是 t3code 里改动次数最多的地方。第一版我只设计了 Snippet 单表后来加标签、加用户关联、加搜索需求前后重构了三轮。下面把最终的模型和思路完整展开。3.1 Prisma Schema 的最终形态// 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? snippets Snippet[] tags Tag[] accounts Account[] sessions Session[] } model Snippet { id String id default(cuid()) title String code String db.Text description String? db.Text language String default(plaintext) createdAt DateTime default(now()) updatedAt DateTime updatedAt userId String user User relation(fields: [userId], references: [id], onDelete: Cascade) tags Tag[] } model Tag { id String id default(cuid()) name String userId String user User relation(fields: [userId], references: [id], onDelete: Cascade) snippets Snippet[] unique([name, userId]) }几个设计决策Snippet 和 Tag 是多对多中间表 Prisma 会自动生成不需要手写。这么做的好处是搜索某个标签的时候可以反向拿到所有相关片段数据冗余最小。Tag 的 name 不是全局唯一而是[name, userId]联合唯一。也就是说每个用户的标签空间是独立的。这点很容易漏掉如果不加 userId就会出现 A 用户创建的react标签干扰 B 用户的筛选。所有和用户相关的表都带 userId 外键并且删除用户时级联删除。虽然是个人工具但从第一版就把所有权隔离做掉后面真要开放注册的时候不用回头改表结构。3.2 所有权隔离tRPC 中间件的作用前端反馈的时候有人可能漏掉一层权限校验即使页面不展示别人的片段如果 tRPC 路由写得粗心别人拿你的 API 地址直接调用snippet.detail传一个别人的 snippetId就可能会读到别人的数据。t3code 在 tRPC 路由层做了两道防线。第一道是protectedProcedure。它会在执行查询前检查 session没有登录直接抛 UNAUTHORIZED 错误。这个在 create-t3-app 里是默认就有的// server/api/trpc.ts export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user } }, }); });第二道是在每个涉及具体资源的 mutation / query 里强制带上userId过滤条件detail: protectedProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) { const snippet await ctx.db.snippet.findFirst({ where: { id: input.id, userId: ctx.session.user.id, // 关键 }, include: { tags: true }, }); if (!snippet) throw new TRPCError({ code: NOT_FOUND }); return snippet; }),这里用findFirst而不是findUnique就是为了能附加 userId 条件。findUnique只能按唯一键查根本拼不进所有权条件所以这类场景记住用findFirst配where。3.3 搜索方案从怕慢到先跑起来搜索是最纠结的功能。第一想法是上 PostgreSQL 全文检索tsvector GIN 索引确实性能最好但要在 Prisma 里执行原始 SQL对个人项目来说有点重。后来我算了一笔账t3code 单用户的片段量撑死几千条每条 code 可能几百上千字总量不过几 MB在 PostgreSQL 里做LIKE %keyword%虽然不能命中 B-tree 索引但全表扫描几 MB 数据也就几十毫秒。于是 MVP 阶段直接用了最朴素的contains查询search: z.string().optional(), ... ...(input.search ? { OR: [{ title: { contains: input.search, mode: insensitive } }, { code: { contains: input.search, mode: insensitive } }] } : {}),实测下来3000 条片段、平均 5KB 文本的情况下搜索响应稳定在 80 ~ 120ms 之间。这个数据后面可以在数据库加 pg_trgm 索引进一步优化但现阶段完全够用。我的原则很简单先用最简单的方案跑通核心体验当查询时间真的超过 200ms 再考虑引入更复杂的索引结构。很多开发者栽在提前优化上为了一个根本不会发生的并发场景把架构搞复杂了十倍。4. 前端交互的细节打磨从能用到每天想打开t3code 本质是个工具型应用用户打开它的频率取决于找到片段这件事有多顺滑。所以前端我没有把精力花在花哨的动画上而是集中在几个高频交互上反复打磨。4.1 编辑器方案CodeMirror 6 而不是 Monaco代码片段编辑器是核心输入入口。对比过两个方案MonacoCodeMirror 6体积较大~2MB 起步模块化按需加载~300KB语言支持极强VS Code 同款常见语言足够React 集成需要自己封装有官方 React wrapper定制性一般极高一切皆可配置t3code 的场景是编辑 5 行到 100 行的小片段不需要断点调试、不需要多光标、不需要 IntelliSense。Monaco 那种重型 IDE 能力根本用不上还拖慢首屏。CodeMirror 6 按语言加载语法包我只需要导入常见的javascript、typescript、python、go、rust等几个语言包其余 fallback 到纯文本。最后选择 CodeMirror 6首屏体积少了将近 1.5MB。4.2 快捷键与无鼠标流真正的效率工具必须能用键盘完成高频操作。t3code 做了三个快捷键CmdK全局聚焦搜索框输入内容实时过滤列表CmdEnter在编辑器里保存当前片段同时支持CmdS防浏览器默认行为CtrlShiftF快速切换语言筛选比如输入ts直接筛 TypeScript这里有个细节CmdS在浏览器里默认行为是保存页面如果不e.preventDefault()用户每次想保存片段都会弹下载框体验非常差。处理方式是在全局监听了 keydownuseEffect(() { const handler (e: KeyboardEvent) { if ((e.metaKey || e.ctrlKey) e.key s) { e.preventDefault(); if (isEditing) handleSave(); } }; window.addEventListener(keydown, handler); return () window.removeEventListener(keydown, handler); }, [isEditing, handleSave]);4.3 复制按钮的自带反馈代码片段页面最高频操作是复制。我最初只做了一个navigator.clipboard.writeText(code)点击后没有任何反馈经常出现用户点了好几次以为没复制成功的假象。后来改成三步复制成功 - 按钮文案变成已复制 - 2 秒后恢复原状。这是一个极小但体验提升巨大的改动。顺便提醒一句navigator.clipboard在非 HTTPS 环境下不可用本地开发用 localhost 没问题部署到自定义域名时一定记得开 HTTPS否则这个 API 会静默失败。4.4 暗色主题的一点点小坑工具型应用必然要支持暗色模式但代码高亮比较特殊编辑器背景色和语法 token 的颜色需要跟着主题切换否则会出现页面是暗色的代码区域却是白底黑字这种割裂感。t3code 的做法是用 CodeMirror 的 theme 配置重新生成一组高亮颜色并且在 localStorage 里保存主题偏好const editorTheme isDark ? darkTheme : lightTheme; CodeMirror theme{editorTheme} value{code} onChange{setCode} /5. 部署上线实测:Vercel Neon Postgres 的完整闭环部署自带一种项目终于要见光了的忐忑感。t3code 的部署目标很明确成本趋近于零、不需要自己维护服务器、支持自动 HTTPS。最终选了 Vercel 托管 Next.jsNeon 提供 serverless Postgres两家的免费额度对个人工具来说完全够用。5.1 首次部署的全过程按顺序走一遍实际操作在 Neon 控制台创建项目复制连接字符串注意选 connection pooling 的那个地址直接连数据库主机的地址在 serverless 场景容易撞连接数限制在 Vercel 项目设置里配置环境变量DATABASE_URL和NEXTAUTH_SECRET本地跑npx prisma db push把 schema 同步到数据库也可以生成 migration 后在 Vercel 构建时自动跑但个人项目不需要那么复杂推送代码到 GitHubVercel 自动识别 Next.js 项目并构建部署T3 Stack 在这种情况下几乎零配置就能跑起来因为 create-t3-app 已经预设好了构建命令和输出配置。唯一要注意的是环境变量在构建阶段就要存在否则 TypeScript 类型检查会因为拿不到数据库地址而在 CI 报错。5.2 首屏性能实测数据部署完我跑了一次 Lighthouse 和数据统计指标实测结果First Contentful Paint0.8sLargest Contentful Paint1.2sTime to Interactive1.5s首屏 JS 体积约 190KB gzip首屏请求数8含静态资源和接口数据比预期乐观原因有两个一是 App Router 服务端组件把首屏数据直接在 HTML 里渲染出来了没有客户端瀑布请求二是 CodeMirror 只在编辑页面异步加载列表页完全不碰它。这个结果证明了一件事——个人工具完全可以通过架构选择达到很好的性能而不需要专门做性能优化。5.3 成本与运维现实跑了一个月账单如下Vercel 免费档个人项目流量没有超出Neon 免费档Postgres 实例保持休眠白天用的时候被唤醒。整体费用为 0。运维上唯一会遇到的情况是 Neon 实例休眠后第一次访问会有 3 秒左右的冷启动延迟对个人工具来说可以接受。如果实在忍受不了可以加一个定时 ping 的脚本保持实例活跃但免费档不推荐还是让它在不用的时候休眠省资源。6. 踩坑实录四个问题从报错到修复的完整排查链路前后花了很多个晚上,积累下来的这四个坑最有代表性,每一个单独拎出来都够让人查两小时。6.1 Prisma Client 在 Vercel 构建时找不到数据库连接现象第一次部署时日志在prisma generate阶段报错提示Environment variable not found: DATABASE_URL。排查链路先确认环境变量已经在 Vercel 控制台配置随后发现构建阶段的环境变量和运行时还不完全一样——Vercel 构建时会执行prisma generate这个阶段如果拿不到DATABASE_URLPrisma Client 会拒绝生成默认的 cjs 产物。Vercel 的构建环境默认会读取控制台上配置的变量所以按理说不该报错但我的情况是环境变量名写错了——在 Neon 里复制的是DATABASE_URL_POOLED粘贴到 Vercel 时键名却写成了DATABASE_URL_POOL。检查完全部配置后确认是键名不一致导致的问题。修复方案在 Vercel 环境变量里统一使用DATABASE_URL作为键名值为 Neon 提供的 pooling 连接串。6.2 NextAuth 回调地址报错:redirect_uri_mismatch现象本地能登录部署后在 Vercel 点 GitHub 登录跳转回来就报redirect_uri_mismatch。排查链路NextAuth 的 GitHub Provider 需要配置回调地址默认是http://localhost:3000/api/auth/callback/github和https://你的域名/api/auth/callback/github两个都要在 GitHub OAuth App 里配。我只配了 localhost 的线上当然校验失败。修改 GitHub App 配置后还需要确认NEXTAUTH_URL环境变量也指向线上域名否则 NextAuth 在服务端生成的回调地址还会是 localhost。修复方案在 GitHub OAuth App 设置里补上线上回调地址同时 Vercel 环境变量NEXTAUTH_URL设为正式域名。6.3 tRPC 查询总是返回 500,但本地开发完全正常现象线上的snippet.list返回 Internal Server Error本地却一切正常。排查链路先看 Vercel 函数日志报错是PrismaClientInitializationError: PrismaClient failed to initialize。本地正常、线上失败最常见的原因是Prisma Client 产物与当前 Node 环境不匹配或者数据库连接串在运行时拿不到。日志里还能看到一行Invalidprisma.snippet.findMany()invocation的提示指向的是数据库连接无法建立。接下来验证数据库连通性在本地用psql $DATABASE_URL -c select 1能通说明 Neon 的连接串本身没问题。那问题大概率出在 Vercel 的运行时环境变量。检查后发现我在 Vercel 环境变量里配置的是 Neon 的连接串但 Prisma schema 里的连接串名称默认是DATABASE_URL如果环境变量名大小写不一致运行时 Prisma Client 拿到的就是 undefined。为了避免环境变量名大小写混淆统一改为DATABASE_URL全大写并重新部署问题消失。修复方案确认 Vercel 环境变量键名与 Prisma schema / NextAuth 完全一致统一使用DATABASE_URL和NEXTAUTH_SECRET。6.4 自动保存竞态导致片段内容被旧数据覆盖现象编辑片段时切到另一个片段再切回来发现刚才对前一个片段的修改丢了编辑器里显示的是更早的内容。排查链路这不是服务器问题而是前端状态管理的疏漏。t3code 里编辑器组件是被复用的code状态存在组件的 useState 里没有跟当前选中的 snippetId 绑定。切换片段时新的 snippet 数据传入组件useState 的初始值只在组件挂载时生效切回来时组件因为同一个 key 没有重建所以 state 还停留在上一次的旧内容。另一个相关问题是防抖自动保存输入停止 1.5 秒后自动调update接口但如果用户在保存过程中切换了片段旧片段的请求还没完成等它返回后会把新片段的数据覆盖掉。这是一个典型的竞态条件。修复方案两个改动。第一编辑器组件通过key{snippetId}强制在切换片段时重建状态。第二自动保存请求里增加一个当前编辑 id的校验只有请求返回时用户仍然在编辑同一个片段才更新 UI 状态// 伪代码思路 const onAutoSave async (snippetId: string, content: string) { const savedId snippetId; await api.snippet.update.mutate({ id: snippetId, code: content }); if (editingIdRef.current savedId) { setLastSavedAt(new Date()); } else { console.warn(保存返回时用户已切换片段丢弃过期更新); } };7. 后续扩展的想象空间:标签自动生成、全文检索与移动端t3code 作为个人工具核心闭环已经跑通但我脑子里有几个明确的迭代方向。第一个方向是自动打标签。手动维护标签确实是最费精力的一环尤其是片段量过千之后给每个片段想 3 个标签很消耗意志力。基于嵌入模型做一批标题 代码摘要 - 标签的分类是可行的成本也不高。第二版可以先把所有已有片段离线处理一遍打上推荐标签之后新片段入库时再实时推荐。第二个方向是真正的全文检索。当前contains查询在几千条数据时已经能用但到了几万条加上多条件筛选响应时间会明显上行。换 PostgreSQL 的pg_trgm扩展配合 GIN 索引可以把 LIKE 查询加速几个数量级而且不需要改 Prisma 存储层只是在查询时执行SELECT ... WHERE code ILIKE %xxx%就能命中索引。第三个方向是移动端适配。现在手机浏览器打开 t3code列表和编辑器勉强能用但复制操作和多标签筛选的体验很一般。做一个 PWA 版本把核心的浏览、搜索、复制场景搬到手机上是性价比最高的一步不需要单独开发原生 App。代码片段管理这个需求大概率不会消失t3code 这个项目给我的收获已经不只是一个工具了它把全栈开发里那些看起来很简单、做起来全是细节的部分完整暴露了一遍。如果你也想动手做个类似的工具我的建议是从最朴素的方案起步每一步都问自己这个复杂度能不能等需要的时候再加把精力留给真正影响使用体验的环节。毕竟一个好的开发者工具核心从来不是技术炫技而是让使用者顺畅地完成他想做的事。