t3code：用 tRPC + Prisma 打造团队代码片段管理工具

年初那阵子，团队里最常出现的对话就是“你那个代码片段发我一下”“这个函数上次在哪个项目里写过”。散落在聊天记录、个人笔记、临时文件夹里的代码越来越多，真正要用的时候又找不到。我本来想偷懒写个脚本凑合着用，结果脚本越写越复杂——要搜索、要分类、要多人共享，最后变成了一个完整的小平台。这就是 t3code 的由来：一个面向小团队的代码片段管理与提取工具，技术栈选了 TypeScript + tRPC + Prisma + Tailwind 的组合，项目名里的 t3 就是从这一串名字里长出来的。

这篇文章会把从零搭建 t3code 的过程完整拆开，包括为什么选这套技术栈、数据模型怎么设计、编辑器与渲染管线怎么处理、CLI 终端工具怎么接入、上线前后踩过的坑和补救方案。无论你是想搭一个类似的内部工具，还是单纯想看看 tRPC 和 Prisma 在实际项目里怎么配合，这篇文章应该都能给你一些可直接抄作业的参考。

1. t3code 是怎么冒出来的：从一个终端习惯说起

与其直接说“我们决定做一个代码片段管理平台”，不如先把场景还原一下，因为这决定了后面所有设计。

1.1 场景还原：散落在各处的代码片段

团队大概 8 个人，前端、后端、客户端都混在一起。平时大家分享代码的方式基本是：

• 聊天群里贴一段，之后想找只能往上翻记录；
• 个人笔记里存了一份，但只有自己知道；
• 代码仓库里搜，可是片段往往经过了删改，没法直接拿来用；
• 有些组件模板、配置片段、Shell 脚本，根本没有一个固定的“家”。

赶上要写一个相似功能的时候，往往又是重新 Google、重新写，浪费的时间非常隐性，但算下来很惊人。我们统计过一次，一周里大家互相找代码的时间加起来差不多有 16 个小时，基本等于一个人大半周的工时。

这个数字促使我去找一个解决办法。本来的想法是做一个共享的代码库，大家都往里丢代码，然后用关键字、标签、语言来检索。后来我发现，光是能“存进去、搜出来”还不够，开发者的习惯是待在终端里，最好一个命令就能把代码片段拉取下来，塞进当前项目，而不是打开一个网页去复制粘贴。

1.2 从脚本到项目：边界怎么划

一开始我写了两个脚本：一个负责把片段写进 JSON 文件，另一个负责用rg搜索。跑了两周，问题来了：

• JSON 文件没法多人协作，冲突只能靠 git；
• 没有权限概念，谁都能改；
• 富文本、代码高亮、版本历史这些需求，脚本完全承载不了；
• 团队其他人不会想用命令行去编辑一堆 JSON。

所以我把边界重新划了一下：t3code 不是一个无所不包的知识库，也不是代码托管平台，它只专注做三件事——存片段、按需检索、一键拉进本地项目。

配套能力包括分类标签、语言识别、代码格式化、自定义渲染模板、审计记录。至于文档、 wiki、评论这些功能，一概不做，后续也没有加，因为一旦功能膨胀，这个工具就会从“好用的小东西”变成“难维护的大系统”。

2. 选型决策：为什么是 tRPC + Prisma，而不是 REST + 手写 ORM

技术选型这块，网上争论很多，我不打算说服谁，只讲我们在确定 t3code 技术栈时的实际考虑和当时的取舍。

2.1 三大选型原则

选型不是看哪个技术最新，而是看约束条件。t3code 的约束有三个：

1. 团队大多是 TypeScript 背景，不希望维护两套类型定义；
2. 项目体量不大，不想引入过重的服务端框架；
3. 需要 CLI 和 Web 两端同时访问同样的业务能力。

于是整个技术栈顺理成章地定为：

如果当时选 REST，就意味着要为每个接口维护types.ts，还要处理请求/响应结构差异。以 t3code 这种规模，这纯属浪费。而 tRPC 直接把函数调用变成跨端调用，类型从数据库到前端从来不会出现“手写对齐”的过程。

2.2 monorepo 与包管理方案

t3code 最大的特殊点是有一个 CLI 终端工具。CLI 和 Web 共享的不仅仅是类型，还有部分业务逻辑，比如标签解析、代码格式化、搜索过滤。如果不做 monorepo，就得把这些逻辑复制两份，之后任意一头改规则，另一头就失灵。

所以从第一天就定了 pnpm workspace 的 monorepo：

t3code/ ├── apps/ │ ├── web/ # Next.js 应用 │ └── cli/ # 终端工具，Node.js ├── packages/ │ ├── api/ # tRPC router 定义，供 web 和 cli 复用 │ ├── db/ # Prisma schema 与 client 实例 │ ├── shared/ # 共享类型、常量、zod schema │ └── config/ # 共享的 eslint/tsconfig 配置 └── pnpm-workspace.yaml

这样划分的关键在于：packages/api里不依赖任何 Next.js 代码，只依赖@trpc/server和packages/db。apps/cli同样只依赖packages/api。于是 CLI 可以不带浏览器环境直接调用业务逻辑，web 端也只是多了一个 HTTP 适配层。

2.3 数据库选型的取舍

一开始纠结过 SQLite 还是 PostgreSQL。SQLite 部署简单，适合个人使用；但 t3code 至少有 8 人同时使用，还要考虑并发写入、全文检索、后续可能接 AI embedding，所以直接选了 PostgreSQL。

数据库层面还做了一个决定：全文检索不用 PostgreSQL 内置的全文搜索，而是用pg_trgm扩展加ILIKE查询。原因是 snippet 内容基本是短文本，不需要复杂的词干分析，pg_trgm在 v6/smth 场景下查询速度足够，而且实现简单，不需要引入 Elasticsearch。

表结构设计上用了软删除 + 审计日志，这个后面细说。

3. 核心数据模型与接口层：先把“代码资产”管起来

这个阶段我花了大量时间在 Prisma schema 上。数据模型如果一开始设计歪了，后面改起来很痛苦，尤其是 snippet 和 tag 之间的多对多关系，以及软删除和唯一约束之间的冲突。

3.1 Prisma Schema 设计

t3code 的核心模型有这几个：用户、工作区、代码片段、标签、审计日志。简化后的 Prisma schema 大致长这样：

model User { id String @id @default(cuid()) email String @unique name String? createdAt DateTime @default(now()) memberships WorkspaceMember[] } model Workspace { id String @id @default(cuid()) slug String @unique name String members WorkspaceMember[] snippets Snippet[] createdAt DateTime @default(now()) } model WorkspaceMember { id String @id @default(cuid()) workspaceId String userId String role Role @default(MEMBER) workspace Workspace @relation(fields: [workspaceId], references: [id]) user User @relation(fields: [userId], references: [id]) @@unique([workspaceId, userId]) } model Snippet { id String @id @default(cuid()) workspaceId String title String description String? content String @db.Text language String @default("plaintext") tags SnippetTag[] createdById String createdAt DateTime @default(now()) updatedAt DateTime @updatedAt deletedAt DateTime? workspace Workspace @relation(fields: [workspaceId], references: [id]) // 省略反向关系 @@index([workspaceId, deletedAt]) @@index([language, deletedAt]) } model Tag { id String @id @default(cuid()) workspaceId String name String snippets SnippetTag[] @@unique([workspaceId, name]) } model SnippetTag { snippetId String tagId String snippet Snippet @relation(fields: [snippetId], references: [id], onDelete: Cascade) tag Tag @relation(fields: [tagId], references: [id], onDelete: Cascade) @@id([snippetId, tagId]) } model AuditLog { id String @id @default(cuid()) workspaceId String actorId String action String targetId String? meta Json? createdAt DateTime @default(now()) @@index([workspaceId, createdAt]) }

几个设计上的注意点：

• deletedAt软删除：删除 snippet 只是打标记，防止误删后无法恢复。但软删除带来一个严重问题，就是和唯一约束冲突，这个我放到第 7 章展开。
• @@index([workspaceId, deletedAt])：这个联合索引非常关键，因为主页的 snippet 列表几乎总是先按 workspace 过滤、再排除已删除数据。如果不加联合索引，数据库会先扫所有 snippet 再过滤 workspace，数据量上来之后会很慢。
• Tag 的归属：Tag 直接挂在 workspace 下，而不是全局唯一。因为不同团队可能用同一个名字表达不同语义，比如 “utils” 在前端组和后端组的意思差别很大。

3.2 tRPC 路由的划分

tRPC 的 router 结构尽量按“领域”划分，而不是按 HTTP 动作划分。t3code 里最核心的几个 router：

// packages/api/src/routers/_app.ts import { router } from "../trpc"; import { snippetRouter } from "./snippet"; import { tagRouter } from "./tag"; import { workspaceRouter } from "./workspace"; import { auditRouter } from "./audit"; export const appRouter = router({ snippet: snippetRouter, tag: tagRouter, workspace: workspaceRouter, audit: auditRouter, }); export type AppRouter = typeof appRouter;

packages/api里只导出appRouter和createContext相关类型。这样 web 端在初始化trpcClient时只需要引入AppRouter类型，就能在所有页面拿到完整的类型推导。

snippet router 里的 procedure 大致分这么几类：

每个 procedure 都要用 zod 做输入校验，而不是把校验逻辑写在 controller 里。比如：

import { z } from "zod"; import { protectedProcedure } from "../middleware"; import { prisma } from "@t3code/db"; const snippetCreateSchema = z.object({ workspaceId: z.string().cuid(), title: z.string().min(1).max(100), description: z.string().max(500).optional(), content: z.string().min(1), language: z.string().default("plaintext"), tagNames: z.array(z.string().min(1).max(30)).max(10).optional(), }); export const snippetRouter = router({ create: protectedProcedure .input(snippetCreateSchema) .mutation(async ({ ctx, input }) => { // 校验当前用户是否属于该 workspace const member = await ctx.db.workspaceMember.findFirst({ where: { workspaceId: input.workspaceId, userId: ctx.session.userId }, }); if (!member) throw new TRPCError({ code: "FORBIDDEN" }); // 标签采用 find-or-create const tags = input.tagNames ? await Promise.all( input.tagNames.map((name) => ctx.db.tag.upsert({ where: { workspaceId_name: { workspaceId: input.workspaceId, name } }, update: {}, create: { workspaceId: input.workspaceId, name }, }) ) ) : []; return ctx.db.snippet.create({ data: { ...input, tags: { create: tags.map((tag) => ({ tagId: tag.id })), }, }, include: { tags: { include: { tag: true } } }, }); }), });

这段代码你可能会注意到，标签的find-or-create并不是原子的。如果两个人同时创建一个相同名字的标签，upsert 会因为唯一约束冲突而报错。实际项目中我加了一层重试，捕获 Prisma 的P2002错误后重新查询一次，问题就解决了。

3.3 类型安全带来的实际收益

tRPC 最直观的价值是，所有从前端到后端的调用，类型都来自同一个定义源。我在 t3code 上遇到过一个很典型的例子：后来给 Snippet 增加了一个isPublic字段，我只改了 Prisma schema、zod schema 和两处查询逻辑，前端代码里所有用到 snippet 类型的地方立刻报错，几乎不可能出现“前端少一个字段、后端多一个字段”的隐秘 bug。

这比“写接口文档”更高效的点在于，文档会过期，类型不会。CLI 侧拿到的是同一个AppRouter类型声明，所以 Web 端新增一个查询而 CLI 没实现时，编译期就能给出警告，不会被用户在使用时才暴露问题。

4. 编辑器、标签与渲染：前端最难的不是 UI

t3code 的前端表面看起来就是一个表单加列表，但实际做下来，最大的工作量在三个地方：代码编辑器、Markdown 渲染、代码高亮与预览的一致性。

4.1 代码编辑器组件选型

编辑器的选型上我只比较了两家：Monaco 和 CodeMirror。

Monaco 的功能确实强，智能提示、断点调试、diff 编辑都有，但代价是体积大，一个编辑器就把首屏 bundle 撑到 1MB 以上，对于 t3code 这种以“快速记录和检索”为核心诉求的工具来说不划算。

CodeMirror 6 的模块化做得更好，按需加载语言支持，首屏可以控制得很小。t3code 的场景是编辑短小代码片段，不需要完整 IDE 功能，所以最终选了 CodeMirror 6，搭配@codemirror/lang-*系列做语言高亮。

编辑器还做了一个很关键的交互：Cmd/Ctrl + Enter 直接保存。这个习惯是从 Notion 那边学来的，让“记录代码”这个动作的摩擦降到了最低。

4.2 自定义标签与 Markdown 渲染管线

t3code 里每个 snippet 的正文就是代码，所以不需要专门搞富文本编辑器。但描述字段希望支持 Markdown，同时还要支持一种自定义语法：在描述里用[[snip:xxx]]引用另一个 snippet，渲染时自动嵌入对应片段内容并加上链接。

这个需求如果用 dangerouslySetInnerHTML 去拼字符串就是给自己挖坑。我用了标准 unified 管线：

// packages/web/src/lib/render-markdown.ts import { unified } from "unified"; import remarkParse from "remark-parse"; import remarkGfm from "remark-gfm"; import remarkRehype from "remark-rehype"; import rehypeStringify from "rehype-stringify"; import rehypePrettyCode from "rehype-pretty-code"; import { visit } from "unist-util-visit"; export async function renderMarkdown(markdown: string) { const file = await unified() .use(remarkParse) .use(remarkGfm) .use(() => (tree) => { visit(tree, "text", (node) => { // 识别 [[snip:xxx]] 并替换为自定义节点 node.value = node.value.replace( /\[\[snip:([a-z0-9]+)\]\]/g, (match, id) => `[片段 ${id}](#snippet-${id})` ); }); }) .use(remarkRehype) .use(rehypePrettyCode, { theme: "one-dark-pro", keepBackground: false }) .use(rehypeStringify) .process(markdown); return String(file); }

这里有一个小坑：rehype-pretty-code的keepBackground如果不设为false，会把代码块背景色写成内联 style，导致无法适配用户切换深色/浅色主题。这个问题也连带引发了后面要说的 hydration 问题，在第 7 章详细展开。

4.3 实时预览与性能优化

t3code 详情页采用左右分栏：左侧是原始 Markdown，右侧是渲染结果。刚开始的版本，每次输入都触发整段 Markdown 渲染，几百毫秒的延迟尤其在长文档下非常明显。

优化策略：

1. 防抖：输入间隔超过 300ms 才触发渲染；
2. 缓存渲染结果：按内容 hash 缓存HTML，相同内容直接复用；
3. 大列表分页：列表页不做“一次加载全部”，而是按 20 条一页，配合滚动加载；
4. 代码高亮库使用 Web Worker：shiki 的语法高亮比较耗时，放到 Worker 里避免阻塞 UI。

列表页还有一个细节：语言筛选器用的是一个下拉菜单，而不是一堆 tag 按钮。原因是 snippet 的语言种类可能很多，按钮放不下，而且语言和 tag 的语义不同——语言是代码的“形态”，tag 是代码的“用途”，两者都很重要，但筛选交互应该分开。

5. 从浏览器到终端：CLI 集成的实现思路

t3code 和普通知识库工具最大的区别是，它有一个专门的 CLI。这部分的动机很直接：开发者手在终端里，不希望为了拿一段代码切到浏览器、复制粘贴再切回来。CLI 需要用最少的按键完成“搜索片段 → 写入当前项目”这个流程。

5.1 CLI 的目标形态

我希望 t3code CLI 的使用体验是：

t3code search "prisma unique error" t3code get <snippet-id> t3code push <file> --title "xxx" --tags "utils,db"

初次使用时需要配置服务地址和 API Token：

t3code init --server https://t3code.example.com --token <token>

命令总结如下：

search和get是最常用的两个命令。search输出的内容会自动带上编号和摘要，比如：

#1 [utils] 用 zod 校验环境变量 tags: type-safe, env 更新于 2 天前 #2 [db] PostgreSQL 获取随机行 tags: postgres, query 更新于 5 小时前

5.2 与 tRPC 服务的轻量对接

CLI 不需要跑一个完整 tRPC client，因为 tRPC 的 HTTP 协议本身就是普通的 POST JSON。我看了一下@trpc/client的实现，最重要的是 URL 生成和错误处理，所以直接在 CLI 里用原生 fetch 实现了一个极简 client：

// apps/cli/src/client.ts import { z } from "zod"; const configSchema = z.object({ server: z.string().url(), token: z.string(), }); export async function trpcCall<T>(path: string, input: unknown): Promise<T> { const config = loadConfig(); const res = await fetch(`${config.server}/api/trpc/${path}`, { method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${config.token}`, }, body: JSON.stringify({ json: input ?? {}, }), }); const data = await res.json(); if (!res.ok) { throw new Error(data?.error?.message ?? "t3code 调用失败"); } return data.result.data as T; }

tRPC v10 的 HTTP 请求格式是{ json: input }，响应格式是{ result: { data } }。搞清楚这个协议形式，任何语言都可以调用服务端，不限于 TypeScript。

这里需要解释一下为什么没有直接用官方 client：

1. CLI 需要支持非 Node 环境吗？不需要，所以其实可以用官方 client；
2. 但官方 client 在出错时抛出的 Error 信息不够友好，我想把错误信息直接展示成“可读的提示”，而不是一串堆栈；
3. 除去这些，自定义 client 也让 CLI 的依赖树最小化，安装速度快。

5.3 终端交互与缓存机制

搜索体验有一个隐藏设计：每次search的结果会在本地缓存 1 分钟。这样当你反复用不同关键词过滤时，不会每次都去打服务端，体验上接近本地 grep。

缓存的同时，需要处理数据新鲜度问题。我采用了一种很简单的策略：缓存条目记录fetchedAt，超过 60 秒就重新请求；但用户主动带--refresh参数时，强制刷新并更新缓存。这个策略对 snippet 这种低频变更数据来说完全够用。

get命令在写入文件时也有讲究。如果目标文件已存在，默认不覆盖，除非加--force。写入前会先做一轮模板变量替换，比如：

t3code get abc123 --output ./src/utils/date.ts

如果在 snippet 内容里有{{fileName}}这样的占位符，写入时会自动替换成date.ts。这个功能本来只是我自己需要，后来组里做组件库时发现配套使用非常方便——提前写好组件模板，占位符替换名称，一条命令生成新组件文件。

6. 部署、权限与稳定性：上线前后要补的课

功能开发完只是第一步，真正让人头疼的是部署、鉴权、备份这些东西。不把这些处理干净，工具上线第一天就可能翻车。

6.1 鉴权与会话安全

t3code 的用户体系用的是 Auth.js v5（NextAuth v5），Credentials 登录 + 邮箱验证码。团队内部工具，没必要接一堆社交登录，邮箱验证码最直接。

密码不存数据库，验证码一次性使用，存到 Redis 并设置 5 分钟过期。登录成功后的 session 放在 HTTP-only cookie 里，防止 XSS 窃取。

这里有一个容易被忽略的点：CLI 的 token 不能放在程序目录的配置文件里就算了，权限至少要是 0600。首次init的时候，我会在写入 config 文件前检查权限，如果是 0644 会自动做一次chmod 600，并给出提示。因为这些 token 拥有对工作区全部片段的读写权限，如果一不小心提交到 git，那等于裸奔。

6.2 部署形态与容器化

部署方案是典型的单机 Docker Compose：

version: "3.8" services: web: build: ./apps/web ports: - "3000:3000" env_file: .env depends_on: - db - redis db: image: postgres:16-alpine volumes: - pgdata:/var/lib/postgresql/data environment: POSTGRES_DB: t3code POSTGRES_USER: t3code POSTGRES_PASSWORD: ${DB_PASSWORD} redis: image: redis:7-alpine volumes: pgdata:

Next.js 的 Dockerfile 按官网推荐做了多阶段构建，output: "standalone"模式，最终镜像很小。nginx 放在前面做 TLS 终止和 HTTP 层防护。

反向代理配置里，我专门调大了client_max_body_size，因为有人会贴很大的代码块，比如整个配置文件。默认的 1MB 限制会导致上传片段直接 413，这个坑其实特别常见。

6.3 监控、备份与数据安全

数据库备份用的是pg_dump，每天凌晨 3 点全量备份，保留最近 7 份，备份文件同步到对象存储。业务上，代码片段的丢失不会造成灾难性后果，但审计日志必须长期保留，所以备份周期上两者分开：

• snippet 数据：日备份，7 天循环；
• 审计日志：实时同步到单独的表/归档桶，长期保留。

监控层面没有上重型的 Prometheus + Grafana，只接了一个简单的健康检查接口/api/health，检查数据库连接和 Redis 连接。外部探活每 5 分钟请求一次，连续失败 3 次就告警到企业微信。这个方案对于内部工具足够了，不用为了监控本身去花太多精力。

7. 开发过程中踩过的几个坑

这部分我觉得比功能实现更值得写。每个坑都花了至少一个晚上来解决，写出来希望帮大家省掉这些时间。

7.1 tRPC v10 的 router 合并顺序坑

刚开始建 router 时，我把所有 procedure 都塞进一个文件，到后来加了 tag、workspace、audit 之后，AppRouter类型变得非常大，前端加载类型时明显变慢，甚至偶尔会报 “Type instantiation is excessively deep”。

排查下来，问题出在_app.ts里把各个子 router 一股脑合并，类型递归深度叠加。解决方法是：

1. 每个子 router 独立定义输入输出类型，不要过度依赖typeof推导；
2. procedure 里尽量显式标注input类型而不是只靠 z.infer；
3. 大的 procedure 拆成更小的子 router，减少一次性的类型合并。

另外，在 CLI 端引用AppRouter类型时，尽量用import type，不要直接import，避免类型被拉到运行时。这个点一度导致 CLI bundle 体积从 200KB 涨到 2MB，排查半天才发现是类型导入问题。

7.2 Prisma 多字段唯一约束的坑

这个坑是最隐蔽的。Snippet 的原始需求是允许同一个人在同一个 workspace 里保存多条同名 snippet，因为可能有不同版本。所以我没给 title 加唯一约束。

但是软删除之后出现了一个奇怪场景：删除一条名为utils.ts的 snippet，再创建一条同名 snippet，结果报错说唯一约束冲突。看了 SQL 才知道，我在Tag表上加了@@unique([workspaceId, name])，这个约束对已删除的 tag 也生效。当 tag 被软删除后用同名 upsert，where条件永远找到那条已删除的记录，于是create永远失败。

解决方案是：不在 tag 上做软删除，而是改成硬删除+引用计数。tag 没有历史价值，不需要恢复；如果有 snippet 还引用它，就禁止删除，返回提示“该标签仍被 N 个片段使用”。这个设计后来验证很可靠，也简化了不少查询。

7.3 前端水合与语法高亮的不一致

Next.js App Router 下，详情页使用rehype-pretty-code服务端渲染 HTML，本地开发正常，部署后偶尔会出现 “Hydration failed because the initial UI does not match what was rendered on the server” 的报错。

最终定位到两个问题：

第一个是 shiki 的代码高亮结果包含随机生成的>