基于T3技术栈构建个人代码片段管理工具：实践与踩坑

1. 项目定位：做“随手存得进、找得到”的代码工具箱

每个开发者电脑里基本都有一堆散落的代码片段：要么是藏在本地备忘录里的正则表达式，要么是随意堆在某个 issues 里的接口示例，又或者是几个月前临时写的配置模板。等项目一多、语言一杂，这些片段就像丢进抽屉的零钱，明明知道有，真要找的时候翻半天也翻不到。我这次做的 t3code，就是想解决这个问题。

t3code 本质上是一个个人代码片段管理工具，核心功能就三件事：存、标、找。你可以把一段 JSON 配置、一条 SQL 语句、一个 React 组件示例快速存进去，给片段打上语言、标签、来源备注，然后通过关键词搜索、标签筛选或者全文检索把它找出来。我把整个项目的技术栈锁死在 T3 全家桶上：Next.js 做前后端一体，TypeScript 保证类型安全，TailwindCSS 负责样式，tRPC 提供端到端的类型化接口，底层数据存储用 SQLite。这个技术组合在个人工具类项目里非常合适，因为它省去了大量接口定义和联调成本。

这个项目适合谁？首先是那些同时维护多个项目、经常切换语言和框架的开发者，其次是对 T3 技术栈感兴趣但缺少一个完整练手场景的人。如果你想搞懂 Next.js App Router 的 Server Component 和 API Route 到底怎么配合、tRPC 的 mutation 和 query 怎么组织、SQLite 的全文索引怎么集成，跟着拆一遍 t3code 的完整实现会很有收获。它不是一个大而全的系统，也不是一个勉强能跑的 demo，而是一个真正被我当成日常工具用了四个多月的小产品，所有设计都经受过真实使用场景的检验。

2. 技术选型：T3 一整套配齐，中间也踩了坑

2.1 为什么选 T3 而不选“自己攒一套”

做这个项目之前，我其实犹豫过要不要自己攒技术栈。比如用 NestJS 做后端再加 React 前端，或者直接用 Vue 配一个轻量服务端。但仔细算了一笔账之后，我打消了这个念头，原因很简单：这是一个单人维护、功能边界清晰的中小型项目，我需要的是“一个人也能维护得动”的技术组合，而不是功能上限最高的组合。

T3 的核心优势是端到端类型安全。从数据库查询到路由到前端调用，类型定义是完整贯穿的。你在 tRPC 的 router 里定义了一个getSnippetById的 query，返回类型是Snippet & { tags: Tag[] }，那么前端调用的时候，TS 会自动推断出这个完整类型。少写几十行 interface 倒是其次，关键是重构的时候不用来回翻文件。有一次我改了数据库里 snippet 表的language字段类型，从string改成enum，tRPC 的返回类型自动同步，前端所有用到language的地方全部标红。这种体验在传统的 REST API 模式下很难做到。

T3 使用 Next.js 作为应用框架还有一个额外好处：Server Component 和 Server Action 可以处理一部分操作，完全不需要暴露额外的路由。比如我实现“从浏览器直接保存当前页面选中的代码”这个功能时，客户端拿到选中文本后，直接调用 server action 创建片段，整个过程没有经过任何 fetch 请求，不仅代码更简洁，而且少了一层 API 攻击面。

2.2 数据存储与部署方案的权衡

数据存储方面我选了 SQLite，具体来说是用了 Turso 提供的 libSQL 服务，基于 SQLite 的分布式封装。原因很实际：这个项目的数据模型非常简单，就是 snippets、tags、snippet_tags 三张表，SQLite 完全够用。而且 SQLite 有一个让我省心的特点——一个文件就是整个数据库，备份只需要复制文件，本地开发时不需要启动任何数据库服务。

不过这里有一个需要权衡的点：如果直接用本地 SQLite 文件存数据，部署到 Vercel 这种 Serverless 平台时会出问题，因为服务器的文件系统不是持久化的。所以我最终采用了 Turso 的远程数据库方案。它兼容 SQLite 协议，支持远程访问，免费额度对一个个人项目来说绰绰有余。你要在国内部署也可以选类似方案，重点是选一个支持 SQL 协议、有免费额度的托管数据库，别自己折腾安装和维护。

2.3 T3 项目初始化的几处细节

初始化项目的时候，我用的是create-t3-app官方脚手架。生成之后有几个地方需要手动确认：tRPC、Next.js、Tailwind 这三个是必选，Prisma 我取消了，因为要用 Drizzle 做 ORM。选择 Drizzle 而不是 Prisma 主要基于两点考虑：Drizzle 的性能更好，没有 Prisma 那么重的引擎层，启动速度更快；类型推断更原生，存储过程中返回的类型可以直接映射到 TypeScript，不用像 Prisma 那样经常需要手动映射。代价是 Drizzle 的 schema 定义和迁移命令需要多熟悉一阵，一旦上手反而觉得更直接。

网上很多教程建议直接保留 Prisma，因为脚手架默认集成比较顺。我个人的建议是：如果项目数据模型比较简单，比如不超过十几张表、没有复杂关联关系，优先选 Drizzle；如果预期模型会很复杂，比如需要大量嵌套查询、复杂的关联更新，Prisma 的 API 会更友好。但对于 t3code 这种小项目，Drizzle 明显是更轻的选择。

3. 核心功能拆解与实现细节

3.1 片段数据模型：结构定对了，后面全是顺的

t3code 最核心的数据结构是片段。片段本身很简单，但我在设计它的字段时花了不少功夫，因为字段结构决定了后续所有功能的上限。最终的表结构是这样的：

这里有两个设计上的小心思。第一，id用 nanoid 而不是自增数字。自增主键在本地创建再同步到远程时会产生冲突，而 nanoid 是完全客户端生成的唯一值，离线也安全。第二，created_at和updated_at用整数时间戳，不用 DATETIME 字符串。SQLite 对时间函数的支持较弱，整数时间戳排序、格式化都更可控，前端用dayjs格式化一下就行。

标签表的设计反而是花心思最多的地方。我把snippet_tags关联表设计成了带权重的：

create table snippet_tags ( snippet_id text not null, tag_id text not null, weight real not null default 1.0, primary key (snippet_id, tag_id) );

weight字段的灵感来自浏览器书签的权重概念。同一个片段可能被多个标签命中，不同标签对这段代码的“代表性”是不同的。比如一段关于Next.js Auth的代码，既有nextjs标签，又有auth标签，但auth更能概括它的核心，那么在搜索时auth标签命中就应该排在nextjs前面。实际操作中，用户给片段加标签时，我提供了“主要标签”和“辅助标签”的区分，主要标签的 weight 是 1.0，辅助是 0.6。排序的时候按标签命中权重加权，这个功能用了一段时间后，搜索准确率提升非常明显。

3.2 标签体系：不要小看这个简单功能

标签是片段管理的核心组织方式。一开始我做的标签体系非常简单：一个标签就是一个字符串，打上就完事。但用了一周后问题来了：标签越来越多，出现了js和javascript并存的情况，一段 TS 代码同时打了ts和typescript，搜索javascript时找不到js标签下的东西。

于是我把标签体系升级成了两层结构：标签本身有规范化的name，还有一个可选的aliases字段，用来存储同义词。存储上，标签表增加了一列：

alter table tags add column aliases text;

使用英文标识作为标签名，中文描述作为别名。比如可以用js作为标签名，把javascript、脚本、J作为别名。搜索时先做别名展开，再统一查所有相关标签。实现上很简单，就是把公式从“匹配标签名”变成“匹配标签名或别名”，查询量并没有增加多少，但整个搜索结果的召回率提升明显。

3.3 搜索功能：从“查得到”进化到“查得准”

搜索功能是我在这个项目上花时间最多的部分，没有之一。第一版我直接用 SQLite 的LIKE查询实现：

select * from snippets where title like '%' || ? || '%' or content like '%' || ? || '%';

这种方式的优点是实现简单，缺点是当片段数量达到几百条时，搜索响应开始明显变慢。每次搜索都要全表扫描，更致命的是它做不了相关性排序，“代码片段管理系统里的数据库优化”这种多关键词搜索，结果完全是混沌的，最后返回的记录和真正要找的那条之间可能隔了十万八千里。

后来我引入了 SQLite 的 FTS5 全文搜索模块。初始化方式是在原表之外建一张虚拟表：

create virtual table snippets_fts using fts5( title, content, content='snippets', content_rowid='id' );

然后把原表的数据同步进去：

insert into snippets_fts(rowid, title, content) select id, title, content from snippets;

查询的时候用match语法：

select snippet_id, bm25(snippets_fts) as rank from snippets_fts where snippets_fts match ? order by rank;

这里最关键的是bm25函数，它返回一个相关性分数，分数越低表示越匹配。BM25 算法是搜索引擎里的经典排序公式，它综合了词频、逆文档频率和文档长度，分词匹配到的越密集、关键词越稀有的权重越高。引入之后搜索质量有了质的提升。

但这里的坑在于：FTS5 虚拟表不会自动同步数据。也就是说你在原表增删改数据后，必须手动同步到 FTS 表，否则搜索到的内容会落后甚至缺失。我一开始没意识到这个问题——测试的时候新增片段搜索得到，过了两天发现之前加的一条记录搜不出来，排查了半天才发现是 FTS 表没有触发同步。最终我采用的做法是，在 Drizzle ORM 的插入、更新、删除方法外层包一个统一的服务层，所有操作走同一个函数，在函数内部执行完insert/update/delete原表后，紧接着执行insert into snippets_fts...同步。这个服务层的方式比 trigger 更容易调试，出现数据不一致时可以直接看到问题出在哪个环节。

3.4 代码高亮与展示：客户端还是服务端

代码展示是片段工具最容易忽略、但实际使用频率极高的部分。第一版我尝试服务端渲染代码高亮，用 highlight.js 在 Server Component 里直接生成 HTML。代码看起来挺好看，但是有一个硬伤：当片段内容包含用户自定义的代码块时，渲染结果会被服务端存储，无法按照当前主题响应式调整颜色。后来我改成了客户端渲染方案，用 react-syntax-highlighter 配合 Prism 主题，在客户端做实时高亮。

这个改动带来一个小问题：代码量大的列表页加载变慢了。因为每个片段组件都需要引入高亮库和语言包。优化方案是动态加载：只有当用户打开某个片段详情时才真正触发高亮渲染，列表页只显示纯文本摘要。

const SyntaxHighlighter = dynamic( () => import("react-syntax-highlighter").then((mod) => mod.Prism), { loading: () => <Skeleton /> } );

这段代码就是典型的按需加载思路，把重组件拆出来做懒加载。实际效果是列表页的首次加载时间从大概 2.1 秒降到了 0.9 秒左右，打开片段详情时会有大约 200ms 的加载框闪一下，但整体感知是流畅的。

4. 开发过程中的真实问题与排查记录

4.1 tRPC 类型地狱：一次写错，全端报错

tRPC 的核心优势是端到端类型安全，但反面就是：一旦类型不匹配，前端的编译错误会相当难看。我遇到最典型的一个问题是：在server/api/routers/snippet.ts里定义了一个 query：

getSnippet: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) => { const snippet = await ctx.db.query.snippets.findFirst({ where: eq(snippets.id, input.id), }); return { ...snippet, tags: await ctx.db.query.snippetTags.findMany({ where: eq(snippetTags.snippetId, input.id), }), }; });

由于findFirst返回的类型里id字段是string | null，虽然数据库层不可能为 null，但 TS 不知道这一点，返回类型的id就变成了string | null。前端调用snippet.id时就会报错，所有用到这个字段的地方全部标红。

解决办法是给返回类型加上一个明确的类型断言：

type SnippetWithTags = Snippet & { tags: Tag[] }; const result: SnippetWithTags = { ...snippet, tags: await getTagsBySnippetId(input.id), }; return result;

或者用zod在输入端先校验一次，保证后续类型收敛。这类问题非常典型，也是很多 T3 新手容易困惑的点：数据库查出来的类型天然是可空的，但业务上又不允许 null。我的建议是：写 tRPC 时尽量定义明确的返回类型别名，不要偷懒让 TS 自动推导。

4.2 SQLite 全文索引查不出来结果

FTS5 有一个很隐蔽的问题：默认的分词器对非英文支持不理想，尤其是中文文本，不加配置的话经常会查不出来。t3code 的片段内容很多是英文代码，但有很多备注描述是中文，搜索这些中文备注时经常出现完全匹配不到的情况。

排查后发现，Sniper 默认的unicode61tokenizer 会把中文字符按整个字符块切割，也就是说“数据同步”会被当做一个整体词索引，搜索“数据”时无法命中。解决办法是给 FTS 表指定trigramtokenizer，从三个字符开始切分：

create virtual table snippets_fts using fts5( title, content, tokenize = "trigram" );

trigram分词器把文本连续切割成三个字符一组，例如“数据同步”会切成“数据同”、“据同步”，搜索“数据”就能命中，因为“数据同”和“据同步”都包含“数据”这两个连续字符。它的代价是索引占用更大、写入稍慢，但对单表几千条记录来说完全不是问题。如果你真要处理大量中文检索，建议单独研究一下分词方案，比如在项目里接一个 jieba 之类的分词组件，这里只是给了一个够用的方案。

4.3 部署到线上后首屏白屏

项目开发完成后部署到 Vercel，第一次访问首页完全白屏，控制台报了一堆 JavaScript 错误。排查后发现是语法错误级别的编译问题，原因是我的某个客户端组件使用了 Node.js 特有的process全局变量，在服务端渲染和客户端打包时产生了冲突。

这个问题其实挺好避免的，只要在代码里少写平台相关的东西，或者用动态导入把依赖抽到浏览器端执行。这里的经验就是： Next.js 项目不是所有代码都能在两端跑，凡是涉及fs、process、path的代码必须要加"use client"或放进useEffect里，否则部署时大概率白屏。

4.4 标签查询的 N+1 问题

列表页展示 50 个片段时，如果每个片段还要单独查询标签，就是 50 次额外查询，性能非常差。我用 Drizzle 的inArray做了一次批量查询：

const ids = snippets.map((s) => s.id); const allTags = await ctx.db.query.snippetTags.findMany({ where: inArray(snippetTags.snippetId, ids), });

然后在内存里按照snippetId分组，再合并到对应的片段对象上。技巧就是在内存里做 join，而不是依赖数据库的关联查询。对于列表页这种高频率操作，这种方式能极大降低查询次数，同时保持代码的可维护性。

5. 上线后的实际使用感受与调整方向

5.1 哪些设计真正在日常用

t3code 上线到现在，我统计了一下真实使用情况。最常用的功能其实是两个：一是“快速保存”，二是“搜索”。每天大概新增 10 到 25 条片段，搜索使用频率大概在 30 到 50 次。我原以为标签管理会很关键，但实际上用得并不多，大多数时候我直接搜关键词就能找到目标片段。标签更像是一种补充的过滤手段，而不是主要入口。

有一个设计是超出预期的：按语言筛选。因为写前端、后端、运维脚本时常用的代码差异很大，按语言分类比按业务标签更好用。这个功能本来只是顺手加的，结果成了最常点击的筛选条件。如果你也想做代码片段管理工具，语言筛选一定是必备。

5.2 如果让我重做，有三点我会改

第一，FTS 搜索最好在项目最开始就引入，而不是先做 LIKE 查询再重构。后面改数据同步成本不高，但改查询逻辑和测试数据花了不少时间。第二，标签同义词其实可以自动化处理，像 js/javascript/typescript 这种常见别名，用一个静态映射表就能解决，不用让用户手填。第三也是最重要的，最好一开始就考虑离线优先。现在 t3code 完全依赖远程数据库，有次网络波动时保存片段直接失败。更好的设计是本地 SQLite 缓存一层，远程库做同步，这个改动是目前规划中最想做的方向。

6. 现在如果从零做 t3code，给你几点实在建议

如果你准备复刻一个类似项目，我的建议是按“最小可用版本”起步，不要一上来就照搬全部功能。

第一版只需要做三张表、四个接口、两个页面：片段增删改查、标签一级级联、简单搜索。先用 Like 查询把流程跑通，等真的有几百条数据了，再考虑替换 FTS5，因为到那时你才会真正理解为什么需要全文索引。第一版部署时可以选择 Vercel 加 Turso 的方案，这样全部零成本，还能直接体验 Serverless 部署的各种细节。

不要在一开始就深挖 UI 和动画。单独用 Tailwind 搭一个黑白灰基础界面就够用，视觉上的打磨放到功能稳定之后。为了减少改代码的精力消耗，从第一天就在 tRPC router 里定义好 TypeScript 返回类型，业务逻辑全部走服务层，不要直接操作 ORM。这个习惯越早养成，项目大了以后你就越省心。

t3code 不算一个创新功能，但它让我从“到处找自己写过的代码”的困境里解脱了。每个开发者都值得有一个自己顺手、用得住、还敢往里面塞各种碎片代码的工具，希望我的这些记录能帮你少踩几个坑。