1. 代码分享这件小事为什么值得专门做个工具做技术这几年我最大的感受是代码写出来不难难的是让代码在团队里流动起来。我们每天在微信群里甩文件、在邮件里贴代码块、在语雀上复制粘贴再手动排版这些办法凑合能用但问题一大堆——代码格式被聊天软件吃掉、没有语法高亮、没有标签归档、想找一个星期前分享过的一段 SQL 翻半天聊天记录也翻不到。我自己手头就有过这样的项目经历。去年团队做数据迁移几个后端同学反复在群里贴数据库脚本贴一次被换行吃掉一次新来的同事问上次那个去重逻辑的伪代码是谁写的没人能答上来。那一刻我就意识到团队缺一个轻量级的代码分享工具。t3code 这个项目最初就是冲着这个问题去的——自己做一个小而美的代码片段托管与协作平台解决随手存、随时查、一键分享这三个核心诉求。如果你也和我一样觉得 GitHub Gist 有点重、私有不方便又不想为了存几个片段去搭建完整的 GitLab那这篇文章应该能给你不少启发。我会从立项思路、技术选型、核心功能实现到实测踩坑的过程一条线讲清楚 t3code 是怎么从零跑起来的。内容偏实战代码和配置都会给到你可以直接照着搭。需要说明一点由于项目的原始资料比较零散文中不少细节比如环境变量配置、目录结构是我按搭建同类项目时的通用做法补齐的属于大多数开发者在这种场景下都会这么做的方案你在落地时按自己团队的习惯调整即可。2. 技术选型t3code 为什么站在 T3 Stack 这条路上2.1 T3 Stack 到底解决了什么问题先解释一下 T3 Stack。它不是一个框架而是一组工具的组合套路Next.js 做前端框架和全栈路由TypeScript 统一类型tRPC 做端到端类型安全的 API 通信Prisma 做数据库操作Tailwind CSS 做样式。这套组合在 React 社区里流行度很高社区还专门总结了那个著名的 T3 宣言——类型安全优先、简单优先、务实优先。t3code 选这套组合核心原因是它完美匹配内部工具型项目的需求。代码片段工具的典型操作是什么创建一条记录、查询列表、分享链接。这些操作全部是服务端和客户端之间的数据流动而 tRPC 厉害的地方在于你在服务端定义好的路由类型前端调用的时候有完整的类型提示。写错函数名、传错参数类型编译期就报错根本轮不到运行时。我第一次用 tRPC 的感觉是它把以前前端定义接口、后端写接口、两边对文档的工作量砍掉了大半。对 t3code 这种小项目来说业务逻辑简单最大的时间消耗其实就花在这类对接上。类型安全帮我省掉的是无穷无尽的联调时间这个收益在小团队里尤其明显。2.2 为什么不用更传统的方案有人可能会说你直接上 Next.js 加 REST API 不就行了Express 写几个路由前端用 axios 调一样能用。这话没错但代价是你得维护双重类型定义。REST API 需要你写接口文档、定义 d.ts 类型文件、处理运行时校验每个接口改动都要同步两三处地方。tRPC 的思路是用 TypeScript 的类型推断代替人工维护函数定义和前端调用直接共用一套类型改一处自动同步。有人也建议过我用 GraphQL但 GraphQL 对这个小项目来说太重了。写 schema、配 resolver、做缓存控制初期学习成本和配置成本都不低。t3code 的接口形态很清晰查询单条、查询列表、创建、更新、删除。这套操作用 tRPC 的 mutation 和 query 就能完全覆盖不需要引入复杂的查询语言层。还有一层考虑是 Next.js 的 App Router 配合 tRPC 的 Server Client 模式。Next.js 负责页面渲染和服务端组件tRPC 只负责数据层两者各干各的事边界非常清楚。Prisma 是另一个让我省心的选择——它生成的类型可以直接提供给前端使用数据库表结构长什么样前端拿到的类型就是什么样中间没有信息损耗。2.3 t3code 的项目结构与数据模型设计我搭 t3code 时采用的是一个比较标准的 T3 App 目录结构这里基于我常用的布局补一份参考t3code/ ├── prisma/ │ └── schema.prisma # 数据库模型定义 ├── src/ │ ├── pages/ # Next.js 页面路由 │ │ ├── index.tsx # 片段列表页 │ │ └── snippets/ │ │ └── [id].tsx # 片段详情页 │ ├── server/ │ │ ├── api/ │ │ │ └── trpc.ts # tRPC 路由入口 │ │ └── db.ts # Prisma 客户端实例 │ ├── styles/ │ └── utils/ ├── .env # 数据库连接等环境变量 ├── package.json └── tailwind.config.tsPrisma schema 是我花时间最多的地方。代码片段的核心字段就那么几个但扩展字段要想清楚否则后面加需求就很痛苦。t3code 的模型长这样model Snippet { id String id default(cuid()) title String content String db.Text language String default(text) tags String[] // 简单用字符串数组存标签 isPublic Boolean default(true) createdAt DateTime default(now()) updatedAt DateTime updatedAt }这里的细节是db.Text类型——如果字段比较大默认的 varchar 很可能存不下长代码块尤其是那种几百行的配置文件。标签用 String 数组而不是单独建一张表是考虑到这个阶段不需要做标签聚合统计、关联推荐这类功能数组够用且省查询。以后如果要做标签云再拆表迁移也不迟。项目的实践经验是初期模型尽量简单能跑通核心流程最重要。3. 从零搭建 t3code 核心功能创建、查询与分享3.1 初始化项目与环境准备创建 T3 应用有官方脚手架create-t3-app一行命令就能把 Next.js、tRPC、Prisma、Tailwind 全部装好npx create-t3-applatest t3code交互式命令行会让你选择需要哪些模块我这边勾选了 Next.js、TypeScript、tRPC、Prisma、Tailwind CSS 五项其余可以不开。装完改一下.env文件里的DATABASE_URL。开发环境我用的是 SQLite连接串长这样DATABASE_URLfile:./dev.dbSQLite 对本地开发非常友好零配置、直接跑。生产环境建议换 PostgreSQL只需把连接串替换成对应的postgresql://格式Prisma schema 里把provider改一下即可。第一次创建完数据表后要执行生成和迁移。我在这里补一个说明这一步是基于所有 Prisma 项目的标准流程t3code 也是按这个方式跑的。npx prisma db push npx prisma generatedb push适合开发阶段快速同步 schema 到数据库generate会生成 Prisma Client 的类型代码。类型代码是后面所有类型提示的根基忘了跑的话前端拿不到任何 Prisma 相关类型编译直接报错。3.2 tRPC Router把代码片段的 CRUD 串起来tRPC 的架构可以简单理解成三层router分组路由procedure定义具体接口input做入参校验。t3code 的核心 Router 在我的项目里大概长这样// src/server/api/routers/snippet.ts import { z } from zod; import { createTRPCRouter, publicProcedure } from ../trpc; export const snippetRouter createTRPCRouter({ // 创建片段 create: publicProcedure .input( z.object({ title: z.string().min(1).max(120), content: z.string().min(1), language: z.string().optional(), tags: z.array(z.string()).default([]), isPublic: z.boolean().default(true), }) ) .mutation(async ({ ctx, input }) { return ctx.db.snippet.create({ data: { title: input.title, content: input.content, language: input.language ?? text, tags: input.tags, isPublic: input.isPublic, }, }); }), // 按 id 查询单条 getById: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) { return ctx.db.snippet.findUnique({ where: { id: input.id } }); }), // 查询公开列表 listPublic: publicProcedure .input( z.object({ limit: z.number().min(1).max(50).default(20), tag: z.string().optional(), }) ) .query(async ({ ctx, input }) { return ctx.db.snippet.findMany({ where: { isPublic: true, ...(input.tag ? { tags: { has: input.tag } } : {}), }, orderBy: { createdAt: desc }, take: input.limit, }); }), });这里有一个很关键的设计入参校验用 zod。zod 不仅能校验类型还能给默认值、限制长度。尤其是content: z.string().min(1)这种约束从根本上避免往数据库里写空内容。我见过太多项目因为入参校验不严格数据库里攒了一堆坏数据。tRPC 和 zod 是天生一对几乎每个 procedure 都应该配一个 zod schema。前端调用方式非常直接// 前端页面调用示例 const utils api.useUtils(); const createSnippet api.snippet.create.useMutation({ onSuccess: () { utils.snippet.listPublic.invalidate(); }, }); createSnippet.mutate({ title: 去重脚本, content: const dedupe arr [...new Set(arr)];, language: typescript, tags: [前端, 工具], });注意useUtils().listPublic.invalidate()这段作用是修改数据后自动重新拉取列表页面不用手动刷新。这个机制是 tRPC 自带的 cache 管理比很多项目里手动调用 refetch 清爽得多。3.3 分享页与代码高亮体验代码片段工具的核心体验之一是高亮。t3code 我采用的是 react-syntax-highlighter 配合 Prism 主题选择它主要是因为集成简单、主题多、体积可控。在[id].tsx页面里核心逻辑如下import { Prism as SyntaxHighlighter } from react-syntax-highlighter; import { oneDark } from react-syntax-highlighter/dist/esm/styles/prism; export default function SnippetDetail({ snippet }) { return ( SyntaxHighlighter language{snippet.language || text} style{oneDark} {snippet.content} /SyntaxHighlighter ); }有个细节容易踩坑language 字段传错会让 Prism 渲染失败比如传了个js实际 Prism 识别的是javascript。我加了一个语言别名映射表把常见的js、ts、py、sh都转成 Prism 认识的标准语言名。这个小处理对用户体验影响很大用户从侧边栏复制代码时万一识别错语言前端会报渲染错误整个页面直接白屏。我的建议是在数据入输入的时候就把 language 规范化而不是在展示层才做兼容。分享链接设计也很简单详情页直接用snippets/${id}作为分享地址。配合 tRPC 的getById查询别人打开这个链接就能看到高亮后的代码再点一下就能一键复制。3.4 列表页和标签筛选列表页我用的是 tRPC 的listPublic查询配合标签筛选功能。实现上在列表页顶部加了一排标签按钮选中某个标签就带上参数重新查询。这里可以展示一个小技巧标签筛选在前端用 query 参数控制链接形如/或/?tag前端方便直接分享带筛选结果的列表页给同事。代码层面用 Next.js 的useSearchParams获取参数再传给 tRPC 的调用输入。这个交互设计成本极低但用户体验提升很明显——找一个片段不再需要从头翻列表。4. 实测中的连环坑从数据库超时到接口类型报错4.1 Prisma 连接 SQLite 时的超时假象开发 t3code 的第一周我遇到一个特别诡异的问题页面加载时有时会卡 5 秒刷新几次又恢复正常。控制台没报错数据库也是本地文件怎么看都不像性能瓶颈。排查过程是这样的我先看 Network 面板发现耗时的并不是静态资源而是 tRPC 的请求时间拉满 5 秒后才返回结果。我一度怀疑是 tRPC 初始化的问题把路由全部注释掉只留一个 hello 方法结果 hello 也要 5 秒。这就排除业务代码的问题了。再往下排查打开 Prisma 的日志输出才发现它在连接数据库时反复重试。原因是我环境变量里写了一个无效的路径前缀Prisma Client 启动时找不到文件重试多次才最终回退到了正确位置。把DATABASE_URL改成file:./dev.db相对路径之后耗时瞬间降到几百毫秒。这个坑提醒我遇到耗时问题不要先怀疑框架先从数据库连接、网络层这类基础设施查起。很多所谓框架性能差的结论最后都只是配置写错了。4.2 tRPC 类型不一致导致的编译失败第二个坑是前端调用报类型错误。现象是某一处createSnippet.mutate无论如何都提示参数缺失红波浪线标在 input 上但代码看起来每一步都对。我后来排查发现原来是后端 router 的 zod 里定义的字段名和前端调用的字段名不一致。后端写的是content前端不知道什么时候改成了codeTypeScript 检查立刻报错。这可能是我在编辑器里重构时只改了前端、没同步后端导致的。这其实是 tRPC 类型安全的一个副作用——一旦前后端字段不一致编译期就会直接拦截。对开发体验来说这反而是好事它把问题暴露在写代码的时候而不是测试的时候。修复方式很简单把两边的字段名统一成同一个规范。我的经验是命名这类基础约定最好在一个共享 constants 文件里定义避免各个文件手写字符串。4.3 TB级幻觉Next.js 打包时把服务端代码打进了客户端第三个坑出在部署前。我把代码片段详情页打包时发现生成的 JS bundle 异常大首屏加载要十来秒。查了一遍发现react-syntax-highlighter被完整打进了浏览器端而且因为我引用的是dist/esm路径没有走 Next.js 的按需加载优化整个 Prism 语言包全部打包了。解法有两个方向一是动态加载只用dynamic将组件按需引入const SyntaxHighlighter dynamic( () import(react-syntax-highlighter).then((mod) mod.Prism), { ssr: false } );二是只引入需要的语言子集。两个都做bundle 体积直接降了一个数量级。这个坑几乎每个用 Prism 类库的项目都会遇到早发现早省心。实际上代码高亮是看起来小、做起来重的典型需求语言包动辄几百 KB做优化是必修课。4.4 权限控制的低配与补课t3code 最初的设计里只有公开片段isPublic字段是后来补的。加私密分享时我犯了一个典型错误在详情页直接通过getById查询数据没有判断当前片段是否公开。这就意味着任何知道片段 id 的人都能访问未公开内容。虽然 tRPC 本身是类型安全的但类型安全不解决业务权限问题。修复方式是加一层业务校验getById: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx, input }) { const snippet await ctx.db.snippet.findUnique({ where: { id: input.id } }); if (!snippet) throw new Error(not found); if (!snippet.isPublic) throw new Error(forbidden); return snippet; });同理后续如果要加用户系统这里就得把所有 procedure 从publicProcedure换成protectedProcedure。t3code 的这个权限边界问题本质上是早期图省事埋下的债。我现在的习惯是不管项目多小访问控制从第一天就做后面补永远比一开始写要痛苦。5. 把 t3code 放进团队工作流之后使用效果与扩展空间5.1 团队内部的使用效果t3code 稳定跑起来之后我在自己带的两个小组里试了一阵子。日常使用场景远超我最初的预期。除了传统意义上的代码片段团队开始用它存复用的 Shell 命令、docker-compose 片段、数据库查询模板。最实用的功能反而是标签筛选和列表页分享。以前同事问有没有现成的初始化脚本现在直接发一个/?tag初始化的链接过去对方点开就有全部相关片段不用再翻聊天记录。这验证了我的一个判断代码片段工具的核心价值不只是存更是找和传。发布一个链接就能把整个类目的代码一次性给对方这个效率提升是微信群不可替代的。5.2 往更深方向扩展的可能性t3code 目前还比较基础但扩展空间是够的。我最近在考虑的方向有三个第一接入语法检查。用 WebAssembly 版本的 linter在片段保存时自动做一次轻量静态检查把常见错误熬在分享之前。这个对团队内部分享的质量提升会很直接。第二做片段转工单的联动。代码分享往往伴随讨论或任务——你这段代码报错了帮我看看——如果把片段直接转成一条带上下文的工单流程会顺很多。第三AI 辅助生成摘要。代码片段多了以后光靠标题和标签检索还是不够。用大模型自动生成片段摘要和关键词配合向量检索找代码的体验会再上一个台阶。如果你也想尝试类似的工具我建议先别急着上用户系统、评论、关注这些功能。把核心链路——存、查、分享、权限——跑通比缺失功能更可怕的是功能太多导致没人愿意用。5.3 我自己的几点使用心得最后说几个实操得出的体会供参考。命名要克制。片段标题存在时间长了会变得杂乱我在 t3code 里没有做强制命名规范但团队约定场景-功能-语言比如数据迁移-去重脚本-python。这样做的索引效果远超靠 tag 硬撑。定期清理私密度。默认isPublic是 true这在一开始让很多同事不放心。我后来在设置面板里加了默认值配置让创建者自己选择默认公开还是默认私有。默认私有对新建用户更友好避免仓库里堆积太多不想公开的片段。高亮库是整个体验的基石。我以前觉得代码片段工具的核心是编辑器后来发现展示端的渲染体验同样重要。一个难看的代码块会让团队失去分享欲望。多花点时间打磨高亮样式、主题切换、窄屏适配收益很大。t3code 做到现在最让我满意的不是技术上的某个亮点而是团队里已经形成了随手存、习惯查的氛围。代码分享这个动作以前是流程里的一个卡点现在变成了一件自然发生的事。工具为人服务这句话在 t3code 身上算是真实落地了。
