t3code 是我最近业余时间打磨的一个全栈小项目，本质是个带标签、带搜索的个人代码片段管理工具。我当时给项目起这个名字，其实是把四个核心单词拼在了一起：TypeScript、Tailwind CSS、tRPC 和 Code，结果发现首字母刚好能凑成一个好记的代号，干脆就叫 t3code。它解决的是一个我长期存在的痛点：浏览器收藏夹里堆着几十个代码片段页面，公司的文档系统越来越难搜，自己写的常用工具函数散落在各个仓库里，真正想复用的时候反而找不到。这篇文章我会把整套项目的设计和实现从头到尾拆一遍，包括为什么选 T3 Stack、数据模型怎么设计、tRPC 路由怎么写、部署时踩了哪些坑，适合正在学习 Next.js 全栈开发、或者准备自己搭一个生产力工具的小伙伴参考。
1. 项目定位与技术栈复盘
1.1 为什么不是文档工具，而是代码片段管理工具
市面上的方案很多，Notion、飞书文档、GitHub Gist、甚至 CSDN 都能存代码，但真正用起来就会发现这几种方案各有各的别扭。文档工具擅长图文排版，但对代码块的高亮、复制、按语言筛选支持很弱；Gist 对个人收藏和分类管理不够灵活，而且在中国网络环境下访问速度不稳定。我更需要的其实是一个非常轻量的自建服务：登录之后 10 秒内完成一次收藏，打上标签，之后能按语言、关键词、标签快速过滤。t3code 的定位就是这样一个"私域代码资产库"，它不追求协作、不追求分享，只解决个人积攒代码的效率问题。
这种定位决定了项目不需要复杂的权限系统，也不需要多人实时编辑的能力，反而能让我把精力集中在技术选型和工程化上。我特意没有加入社交功能，整站就是一个朴素的工具站。对开发者来说，这类轻量工具恰恰是验证全栈技术栈落地效果的最好场景——功能边界清晰、数据模型明确、前后端交互频繁但不复杂，非常适合作为学习 T3 Stack 的载体。
1.2 T3 Stack 到底是什么，值得学吗
T3 Stack 是 Theo 提出的一个全栈 TypeScript 技术组合，核心是 Next.js + Tailwind CSS + tRPC + Prisma，经常还会搭配 NextAuth 做认证。如果用一个生活化比喻来说，这套组合相当于把前后端的所有"通讯语言"统一成了一门方言：后端定义的数据结构和前端调用的函数签名完全同源，改一处，另一处立刻报错。对于习惯了传统 REST API 开发模式的人来说，第一次体验这种端到端类型安全的感觉会非常上瘾。
我之所以选择这套技术栈，没有直接去用 Express + React 或者 Vue + Spring，不是因为其他方案不好，而是因为 t3code 的核心交互恰好是"表单提交 + 列表渲染 + 条件筛选"这种密集型 CRUD 操作。这类场景下，前后端类型断开带来的麻烦会被放大：后端返回的字段名改一个字母，前端不报错，运行时才发现拿不到数据，这种事故我在历史项目里经历过太多次。tRPC 能从根本上消除这一类问题，而且不需要定义 OpenAPI、不需要生成客户端 SDK、不需要维护两份接口文档，代码量和心智负担都小很多。
另一方面，Next.js 的 App Router 配合 Server Component，在对首屏性能要求不高的工具站场景里，开发体验非常友好。我可以用 Server Component 直接查数据库做页面渲染，用 Client Component 处理表单交互，两者混排灵活。Prisma 则帮我省掉了手写 SQL 和迁移脚本的精力，模型改完跑一条命令就能同步数据库结构。这套组合的搭配逻辑是：TypeScript 负责类型，Prisma 负责数据，tRPC 负责把类型无缝串起来，Tailwind 负责样式，每一层都在减少"重复劳动"。
1.3 项目功能范围和最终效果
在动工之前，我先把 t3code 的功能边界写死在了一个清单上：用户注册登录、创建代码片段（标题、描述、代码内容、语言类型、标签）、列表页分页展示、按语言/标签/关键词筛选、详情页查看和高亮复制、编辑与删除。没有设计移动端专属版本，没有做浏览器插件，也没有做团队共享。砍掉这些功能不是因为我偷懒，而是想保证第一款 T3 Stack 项目能在三周内从零到上线，避免陷入无休止的功能膨胀。
做完之后项目形态非常简单：一个部署在 Vercel 的 Next.js 站点，数据库用了 MySQL，整体体积很小。这个项目的价值在于，它完整覆盖了一个真实产品从设计、开发到部署的全流程，同时技术深度刚好探到了全栈开发的甜点区。如果你也有类似的想法，我建议不要先考虑"我应该用什么框架"，而是先列出你要解决的具体问题清单，再去套技术方案。那你会发现 T3 Stack 在这种中小型工具站场景里几乎是最省力的选择。
2. 环境准备与项目初始化
2.1 前置工具和版本选择
项目启动前我花了十几分钟统一环境，不要小看这一步，后面很多莫名其妙的问题都和版本错配有关。我的本机环境是 macOS，Node.js 用了 20 LTS 版本，包管理器选择了 pnpm。Node 18 和 20 在 create-t3-app 里都能跑，但 Next.js 14 对 Node 版本有最低要求，建议直接用 20 LTS，省得后面因为 fetch API 或者原生 Web Stream 特性踩坑。
数据库我一开始用的是 SQLite，理由是开发阶段零配置快速启动。生产环境我切换成了 MySQL，这个切换放在文章后面部署部分细说。如果你预算有限或者想最快看到效果，SQLite 其实撑住一个个人工具站完全没有问题，毕竟单机读写的性能瓶颈远没到数据库这一步。前置工具清单如下：
| 工具 | 版本 | 用途 |
|---|---|---|
| Node.js | 20 LTS 及以上 | 运行 Next.js 开发服务器与构建脚本 |
| pnpm | 8.x | 包管理，磁盘占用和安装速度优于 npm |
| Git | 2.x | 版本管理与 Vercel 自动部署对接 |
| Docker | 可选 | 本地跑 MySQL/Postgres 的替代方案 |
2.2 create-t3-app 初始化过程和交互选项
创建项目我用的是官方脚手架，命令非常简单：
pnpm create t3-app@latest t3code执行之后脚手架会询问你要开启哪些功能，这一步很多人会随手全选，但我建议认真想清楚。我的选择是 Next.js、Tailwind CSS、tRPC、Prisma、NextAuth，没有选了别的。为什么 NextAuth 必须选？因为 tRPC 的 protectedProcedure 依赖 session 判断用户身份，没有认证体系的话，代码片段无法关联到具体用户，整个项目就变成了一个单用户的玩具。而 Tailwind 对个人开发者来说效率极高，写页面不用来回切换 CSS 文件，心智负担直接减半。
初始化完成后，脚手架自动生成了一个可以跑起来的最小应用。我强烈建议这时候先执行pnpm dev看一下默认页面，然后跑pnpm db:push或者pnpm db:migrate让默认的示例模型生效。很多人喜欢先大改代码再启动服务，结果报错了也分不清是脚手架问题还是自己代码问题。先确认基线是绿色的，再开始加功能和改代码，这个习惯能替你省下大量无意义的排查时间。
2.3 项目目录结构解读
脚手架生成的目录结构非常清晰，我先把最核心的几个目录讲透。app/目录是 Next.js App Router 的页面目录，里面的page.tsx对应路由路径，layout.tsx负责全局布局。server/目录下是 tRPC 相关的全部后端逻辑，其中server/api/routers/里按业务域拆分路由文件，server/api/trpc.ts是整个 tRPC 路由器初始化的地方。prisma/目录放 Prisma schema 文件和迁移记录。src/在部分版本里和app/、server/平级，早期脚手架会把代码都放在src/下，不用慌，逻辑是一样的。
刚开始接触 App Router 的人最容易困惑的一点是"这个文件为什么叫 page.tsx 而不是 index.tsx"。Next.js 13 之后约定page.tsx就是某个路由的入口组件，app/snippet/[id]/page.tsx对应/snippet/123这个路径。这个约定需要一点时间适应，但它让路由定义变得非常直观，删掉文件等于删掉路由，不需要维护路由表。t3code 整个项目的所有页面，我都是先在纸上画清楚页面路径，再对文件结构下手，这样头脑里始终有一张清晰的"页面拓扑图"。
3. 数据库模型设计：小项目也别乱来
3.1 Prisma 模型设计的三种关系拆解
代码片段管理工具的核心模型其实只有两个：片段（Snippet）和标签（Tag）。用户（User）则是 NextAuth 体系自带的模型，需要和 Snippet 建立一对多关系。标签和片段之间是典型的多对多关系：一个片段可以打多个标签，一个标签下面可以有多个片段。Prisma 里表达这种关系需要一张中间表，我直接让 Prisma 隐式生成，或者显式定义一张 SnippetTag 表。为了后续查询灵活性，我这里选择显式定义。
model User { id String @id @default(cuid()) name String? snippets Snippet[] accounts Account[] sessions Session[] } model Snippet { id String @id @default(cuid()) title String description String? code String language String @default("text") createdAt DateTime @default(now()) updatedAt DateTime @updatedAt userId String user User @relation(fields: [userId], references: [id], onDelete: Cascade) tags SnippetTag[] } model Tag { id String @id @default(cuid()) name String @unique snippets SnippetTag[] } 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]) }这个模型在设计时有两个细节值得注意。第一，Snippet 里的language字段我没有用枚举类型，而是存普通的字符串。原因是代码语言列表很长且会持续增长，存在 DB 里灵活性更高，前端只需要给一组候选值做下拉选择。第二，所有关系字段都加了onDelete: Cascade，这样删除用户时他的所有片段和标签关系会被自动清理，避免残留脏数据。对个人工具站来说，这个设计足够坚固，不需要过度设计像软删除、审计日志这类复杂能力。
3.2 迁移、种子数据和团队协作规范
模型定义好后，执行迁移命令让数据库结构跟上：
pnpm db:migrate迁移一旦生成，就不应该再手工去改数据库表结构，否则 Prisma 的迁移状态和实际库会对不上。我还写了一个简单的 seed 脚本，用来在开发环境填充一批演示数据：10 条片段、5 个标签。seed 的价值在于，新拉取仓库的同事或换电脑后，跑一次pnpm db:seed就能获得一个和老环境几乎一致的开发起点，不需要手工往库里填数据，也不容易搞出脏数据。
这里我想多说一句团队协作的问题。虽然 t3code 目前是我个人项目，但我仍然按照多人协作的规格来组织代码。在prisma/目录里保留完整的迁移记录，每个模型字段都有清晰命名，seed 脚本幂等可重复执行。这样做最大的好处是：如果你未来决定把项目开源或者交给别人接手，别人不需要你当面解释任何业务细节，光看模型和迁移历史就能还原整个数据演进过程。个人项目按团队规范来做，看起来开销大，其实是在给未来的自己减负。
3.3 开发用 SQLite，生产切 MySQL，这个切换痛不痛
很多教程会让你开发环境和生产环境用同一个数据库，我这次刻意试了先 SQLite 后 MySQL 的路线。说实话切换成本远比我想象的低，主要原因在于 Prisma 的数据库适配层把 SQL 方言差异完全隔离了。声明模型和写查询不需要关心底层是 SQLite 还是 MySQL，只需要在.env里改一行DATABASE_URL，然后跑一次prisma migrate deploy就行。当然实际切换时还是有一个小问题：SQLite 对并发写入的支持比较弱，在本地开发时几乎感觉不到，但如果哪天你在本地同时起了多个脚本和测试进程，偶尔会撞上database is locked的错误。
如果你也想走这条路，我的建议是：开发初期确实可以用 SQLite 快速起步，但一定要在项目部署前的第一周就切换到目标数据库，留下足够的缓冲时间。数据库切换看起来只改一个连接串，真正藏坑的地方在于迁移文件的历史状态、种子数据的兼容性、以及个别类型的隐式转换（比如 SQLite 没有原生真正的布尔类型，MySQL 则是 1/0）。晚切不如早切，特别是当项目有了真实数据之后，迁移会麻烦十倍。
4. 后端逻辑：tRPC 路由设计实战
4.1 从 protectedProcedure 到查询编排
tRPC 里最爽的一个体验是protectedProcedure，它会在进入业务逻辑之前先检查用户是否登录，未登录直接抛出未授权错误。这个逻辑在传统 REST 里通常是中间件实现的，现在直接内建在路由定义里，语义非常清晰：一个路由函数既不需要自己想去查 session，也不需要写if (!user) return null这种多余的防卫代码。t3code 里几乎所有片段相关路由都用 protectedProcedure，毕竟代码片段是私密数据，不该公开晒出来。
// server/api/routers/snippet.ts import { createTRPCRouter, protectedProcedure } from "../trpc"; export const snippetRouter = createTRPCRouter({ getAll: protectedProcedure.query(async ({ ctx }) => { const { user } = ctx.session; return ctx.db.snippet.findMany({ where: { userId: user.id }, orderBy: { createdAt: "desc" }, include: { tags: { include: { tag: true } } }, }); }), });这段代码做了三件事：限制只查当前用户的数据、按创建时间倒序排列、连同标签一起查出避免 N+1 查询。Prisma 的include在底层默认使用 JOIN 查询改造成一个 SQL，一般不需要自己select多个表再手动组装。对于刚接触 tRPC 的开发者来说，最容易犯的错误是把所有逻辑都塞进一个路由函数，导致这个查询函数越长越臃肿。更好的做法是拆成多个精确的查询：getById、getRecent、getByTag，谁用谁取，不搞一个大接口一把梭。
4.2 Zod 校验：为什么前端表单和后端接口都离不开它
创建片段的输入校验我用的是 Zod。t3code 里我定义了一套表单 schema，前端 React Hook Form 用它做实时校验，后端 tRPC 的 input 也用它做运行时校验，一个 schema 两头复用。具体看一下代码：
import { z } from "zod"; export const snippetCreateSchema = z.object({ title: z.string().min(1, "标题不能为空").max(100), description: z.string().max(500).optional(), code: z.string().min(1, "代码内容不能为空"), language: z.string().min(1), tags: z.array(z.string()).min(1, "至少打一个标签").max(5), }); export const snippetRouter = createTRPCRouter({ create: protectedProcedure .input(snippetCreateSchema) .mutation(async ({ ctx, input }) => { return ctx.db.$transaction(async (tx) => { const snippet = await tx.snippet.create({ data: { title: input.title, description: input.description, code: input.code, language: input.language, userId: ctx.session.user.id, }, }); for (const name of input.tags) { const tag = await tx.tag.upsert({ where: { name }, update: {}, create: { name }, }); await tx.snippetTag.create({ data: { snippetId: snippet.id, tagId: tag.id }, }); } return snippet; }); }), });我特别想强调一下$transaction的用法。创建一个片段要同时写 snippet 表和 snippetTag 表，还要对标签做 upsert，这三步操作如果分开执行，中途任何一步出错都会留下半截数据。事务把这三步包装成原子操作，要么全部成功，要么全部回滚。很多个人项目初期图省事忽略事务，等数据量一大就出现"片段有但标签没建上"或者反过来"，排查起来非常崩溃。t3code 从一开始就用了事务，后面没在这种诡异问题上浪费过时间。
4.3 和 REST API 的一次对比实验
我特意在项目中期做了一个对照实验：把其中一个 rpc 改写成 REST API 风格，想看看两种模式在实际开发体验上的差距到底有多大。REST 需要先定义POST /api/snippet，然后在 Next.js 的 route handler 里手动解析 request body、校验参数、处理错误状态码、返回 JSON，最后前端还要写一个 fetch 封装。
对比之下 tRPC 的路由函数就是一个普通 TypeScript 函数，输入输出类型自动推导，错误信息直接抛到前端。表格化对比更直观：
| 维度 | REST API | tRPC |
|---|---|---|
| 接口文档 | 需要 OpenAPI 或手写维护 | 无需单独维护，类型即文档 |
| 类型安全 | 需要手写 d.ts 或生成 client | 端到端自动推导 |
| 错误处理 | 手动映射 HTTP 状态码 | 异常直接传播 |
| 多端复用 | 适合第三方开发者接入 | 适合前后端协作紧密的产品 |
| 调试成本 | 需要 curl 或 Postman | 浏览器 devtools 直接调用 |
说句公道话，REST 的成熟生态和通用性仍然是它不可替代的理由，尤其当你有公开 API 或多端客户端的场景时。但 t3code 是我一个人写的前后端项目，没有任何开放 API 的需求，tRPC 这种"把远程调用伪装成本地函数"的体验无疑是效率最优解。这个实验让我彻底治好了对 REST 的路径依赖。
5. 前端页面与交互实现细节
5.1 页面路由和服务端渲染策略
t3code 的前端页面只有四个核心路由：首页展示列表、新建页面、片段详情页、个人设置页。用 Next.js App Router 实现时，我把列表页做成了服务端渲染，也就是说浏览器拿到的 HTML 里已经包含了片段列表数据。这种方式对个人工具网站响应速度更友好，因为首页不需要等 JS 加载完再向服务端发请求。代码如下：
// app/page.tsx import { api } from "~/server/api"; import { SnippetCard } from "./_components/snippet-card"; export default async function HomePage() { const snippets = await api.snippet.getAll(); return ( <main className="mx-auto max-w-5xl px-4 py-8"> <h1>我的代码片段</h1> <div className="grid gap-4 sm:grid-cols-2"> {snippets.map((snippet) => ( <SnippetCard key={snippet.id} snippet={snippet} /> ))} </div> </main> ); }这里api.snippet.getAll因为在服务端执行，可以直接调用 tRPC 的 server 实例，省掉一层 HTTP 网络往返。App Router 推荐的模式是：优先在服务端取数，实在需要交互和实时更新的时候再用客户端组件。我一开始把所有组件都标成"use client"，页面性能一团糟；后来才理解 Server Component 的价值。
新建片段和编辑片段的表单必须放在客户端组件里，因为它们要维护输入状态、做实时校验、处理复制粘贴事件。详情页我建议做成服务端渲染，只把代码高亮组件单独抽成一个客户端组件。这种"服务端为主、客户端为辅"的混合模式，是 Next.js 14 时代最值得掌握的页面组织方式。
5.2 代码高亮选型：我的对比记录
代码片段管理工具的高亮效果直接关系到使用体验，如果代码灰蒙蒙一片看着难受，这个工具用不了三天就会被我丢进收藏夹吃灰。我对比了三个方案：react-syntax-highlighter、prism-react-renderer和shiki。react-syntax-highlighter 最方便但打包体积大，prism-react-renderer 体积小但主题较老，shiki 最大的优势是使用 TextMate 语法高亮，和 VS Code 的渲染效果几乎一致。
我最终选了 shiki，代价是需要服务端把高亮后的 HTML 传给客户端渲染。这个取舍很值得，因为 shiki 支持的语法列表几百种，而且主题非常好看，和我的暗色风格天然搭。集成方式不复杂：
// app/_components/code-block.tsx import { codeToHtml } from "shiki"; export default async function CodeBlock({ code, language }: { code: string; language: string }) { const html = await codeToHtml(code, { lang: language, theme: "github-dark", }); return <div dangerouslySetInnerHTML={{ __html: html }} />; }需要提醒的是，shiki 在服务端渲染时会先加载语言包，首次调用的耗时可能比较长，建议在应用启动时预先加载常用语言包。我一开始没做预加载，首屏响应慢了差不多 300 毫秒，优化后这个问题就消失了。
5.3 搜索筛选：客户端还是服务端？
t3code 的搜索功能要考虑一个取舍：数据量小的时候客户端过滤体验极好，输入即反馈；数据量大后客户端过滤会遇到首屏全量加载的瓶颈。我的做法是：在数据量小的时候做客户端过滤，所以列表页同时接收全部片段数据，搜索框的 value 变化后直接用filter方法在内存里筛选。代码如下：
import { useState, useDeferredValue } from "react"; function SnippetList({ snippets }: { snippets: Snippet[] }) { const [keyword, setKeyword] = useState(""); const deferredKeyword = useDeferredValue(keyword); const filtered = snippets.filter((snippet) => { const q = deferredKeyword.toLowerCase(); return ( snippet.title.toLowerCase().includes(q) || snippet.description?.toLowerCase().includes(q) || snippet.tags.some((t) => t.tag.name.toLowerCase().includes(q)) ); }); // 渲染 filter 后的列表 }useDeferredValue是 React 18 里的一个小工具，它会让过滤器在输入过程中不阻塞用户界面。对个人工具站来说，如果片段超过一千条，客户端过滤仍然毫秒级完成，完全没有必要上全文搜索引擎。但我预留了切换服务端查询的接口，一旦未来想支持大规模数据，把关键词作为 tRPC 入参传回服务端查数据库即可。这样的设计既保证当前体验，又不堵死后续优化路径。
6. 部署全流程与生产环境经验
6.1 部署平台选型：Vercel 还是传统服务器
我首推 Vercel，理由很简单：Next.js 是 Vercel 的亲儿子，部署链路最顺畅，免费额度对个人项目完全够用。你只需要把项目推到 GitHub，在 Vercel 里导入项目，设置环境变量，然后每次git push都会自动触发构建和部署，全程不需要碰服务器。传统服务器比如云主机，需要自己装 Node.js、配反向代理、处理 SSL 证书，还得考虑进程守护，工作量会多出 2 到 3 天，对个人工具站来说性价比很低。
如果你所在区域访问 Vercel 的体验不稳定，也可以用国内云厂商的 Serverless 应用托管平台，它们大都支持标准 Next.js 应用，部署方式大同小异。关键是 Web 层和数据库层分离，让网页应用保持无状态，这样不管在哪部署都灵活。
6.2 环境变量与数据库连接配置
部署到生产，第一件事是配置环境变量。.env.production里至少要包括下面几项：
DATABASE_URL="mysql://user:password@host:3306/t3code" NEXTAUTH_SECRET="一个足够长的随机字符串" NEXTAUTH_URL="https://t3code.你的域名"NextAuth 的 session 加密依赖NEXTAUTH_SECRET，如果环境变量被遗漏，部署后的认证会报MissingSecret错误。这个字符串可以用openssl rand -base64 32生成，不要把本地开发环境的密钥直接搬上生产。数据库方面，我生产环境用了 MySQL 托管的实例，提前在 Prisma schema 里确认了 mysql 数据源，然后执行pnpm db:migrate deploy同步生产库结构。
生产部署还有一个容易踩的坑是迁移文件的执行顺序。你不能在本地跑完 migrate 就以为万事大吉，Vercel 构建时不会自动执行迁移，必须在部署前手动把迁移跑完，或者写一个构建钩子执行。我最初没跑生产迁移，结果首页一直报"数据表不存在"，排查了半天才想起来是生产库还没初始化。这个错一次就长记性了。
6.3 构建报错实录和解决方案
构建阶段我遇到的最奇葩问题来自 Prisma 的二进制引擎。Vercel 的无服务器环境需要安装 Prisma 引擎，如果项目里把 prisma 放在了 devDependencies，构建时prisma generate可能没有执行，导致运行时 Prisma Client 报错。解决方案是把prisma移入 dependencies，同时在postinstall脚本里加一行prisma generate：
{ "scripts": { "postinstall": "prisma generate" } }另一个常见问题是 Tailwind 样式在生产环境丢失。原因是内容扫描路径配置不对，Tailwind 3 默认扫描模板文件，如果你新增了app/_components/这种目录但没有写进content数组，生产构建会把这些新组件的 class 全部过滤掉。排查了很久才发现不是 Tailwind 升级的问题，纯粹是扫描路径没覆盖。
部署完成后我还会顺手做两件事：在 Vercel 设置一个自定义域名，打开 Vercel Analytics 观察页面流量和性能；同时配置了错误监控，用的 Sentry，免费额度个人项目够用。这些小配置能让项目从"能跑"进阶到"运行得清清楚楚"。
7. 常见问题排查与性能优化实录
7.1 开发期高频问题速查表
我把自己在 t3code 开发过程中遇到过的坑整理成了一张速查表，这些问题你在别的教程里大概率找不到现成答案：
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 部署后登录跳转失败 | NEXTAUTH_URL 配置错误或为空 | 检查环境变量，确保填的是线上域名 |
| tRPC 调用返回 401 | 没有走 protectedProcedure 对应中间件 | 在 createContext 里正确挂载 session |
| Tailwind class 不生效 | content 扫描路径没覆盖新目录 | 更新content数组为./app/**/*.{js,ts,jsx,tsx} |
| Prisma 查询报表不存在 | 生产库还没执行迁移 | 跑prisma migrate deploy |
| shiki 高亮首次加载慢 | 语言包没有预加载 | 应用初始化时调用setDefaultHighlighter预加载 |
| NextAuth session 丢失 | Cookie 域不一致 | 开发用 localhost，生产用NEXTAUTH_URL自动匹配 |
这些坑大多数不是语法问题，而是环境配置问题和工程习惯问题。养成一个习惯：除非你能确定是语言层面的 bug，否则先从环境变量、依赖版本、构建缓存三方面排查，比对着代码反复看效率高得多。
7.2 我很后悔没有早点做性能优化
项目最初跑起来的时候，列表页光服务端渲染耗时就要 800 毫秒。我以为是数据库查询太慢，打开 Prisma 的查询日志才发现，真正的问题是标签关联的 N+1 查询。我用的findMany加include虽然避免了手动 N+1，但有些地方为了图方便还是单独写了查 tag 的循环。后来我把查询重构，统一用include和条件过滤，服务端渲染耗时降到 300 毫秒以内。这个案例告诉我们，性能优化第一步永远是先埋点测量，而不是凭感觉猜。
前端体积方面我也做了几项优化：把 shiki 做了动态加载，按语言包拆分 chunk；tRPC 的客户端调用启用了 React Query 的默认缓存策略，90 秒内重复请求不会重发。实际体验下来，列表页从点击到可交互的时间在 1 秒以内，这个数字对一个内容型工具站来说已经很健康。不要一上来就追求 60fps 动画和 10KB 打包体积，先把瀑布上的明显阻塞点摘掉再说。
7.3 个人体会和可扩展的方向
t3code 走到今天，真正改变我认知的不是某个具体库的用法，而是"类型安全"这四个字的价值。以前写前后端对接，我习惯在脑子里面维护一份字段清单，每次改接口都要反复检查两端；现在改一个 Prisma 模型的字段名，编译器会在前端引用处直接标红，这种约束看似限制，其实是巨大的效率红利。
后续 t3code 如果要继续迭代，我会考虑这几个方向：把标签系统升级成支持层级分类；做一个浏览器插件，看到好的代码片段一键收藏进库里；给代码片段加上 AI 自动生成注释和解释的能力。这些方向都不会推翻现有架构，因为数据模型的核心边界当时已经定明白了。如果你也想做一个类似的工具，我的建议是先把最简单的版本跑起来，再按真实使用下来的痛点逐步加能力，t3code 就是这么长出来的。
