企业官网建设流程全解析

两个月前我开始动手做t3code这个项目。它是给团队内部写的一个全栈工具：代码片段管理系统，附带轻量任务看板，让前端、后端、算法同事能把平时沉淀的代码、踩坑记录、常用配置统一放在一个地方。项目代号 t3code 的来历很简单——整套技术栈基于 T3 Stack 的全家桶：Next.js、TypeScript、Tailwind CSS、tRPC、Prisma、NextAuth，名字里带个 t3，叫顺口了。

真正触发我做这个项目的是一次具体到不能再具体的痛：团队四五个人在群里互相发代码片段，过了两周想找某段爬虫配置，翻聊天记录翻到接近崩溃。市面上的代码片段管理工具不是没有，但要么太重，要么权限模型跟团队结构不匹配。我们需要的其实很简单：登录、创建片段、打标签、搜索、按成员共享。这种内部工具用现成 SaaS 反而别扭，自己写一个小而全的系统是最省心的路。

技术选型时我心里其实有过犹豫。手上正好还有一个用 Next.js 的 SSR 项目，团队对 React 很熟，所以全栈框架方向没争议。真正有争议的是数据访问层：走传统 REST 还是上 tRPC。最后让我下决心的，是端到端类型安全带来的协作收益。这篇博客把 t3code 从零到上线这段过程完整记录下来，包括选型细节、类型系统的落地方式，以及这个过程中踩过的所有坑。

1. 为什么 t3code 选了 T3 这套组合

1.1 小团队协作的最大成本在接口层

前后端分离是行业主流，但对一个五六人的内部项目来说，它带来的沟通成本远大于收益。传统模式下，后端写接口文档、前端按文档 mock 数据、联调时两边各改各的，字段名差一个字母就要来回沟通。

t3code 虽然只是内部工具，功能模块依然横跨用户、片段、标签、任务、评论五张核心表，接口数量最终超过四十个。如果用 REST + OpenAPI 的方式，意味着每个接口都要同步文档和类型。类型不同步的问题在开发后期会集中爆发：前端已经联调好的页面，因为后端改了某个字段的可空性，编译直接报错。

这个痛点我在之前几个项目里经历过太多次。选 tRPC 的核心理由就一条：接口类型直接由服务端代码推导，前端引过来就是对的，不需要额外维护任何契约文件。

1.2 create-t3-app 的三条原则

create-t3-app 的维护者提过三条原则，我印象很深：类型安全第一、只用成熟稳定的方案、样板代码最小化。翻译成大白话就是：

• 能在编译期查出来的问题绝不拖到运行时
• 不碰版本号还没稳定、踩坑没人分享的技术
• 脚手架能生成的就别手写

这三条对内部工具项目特别合适。我们没有足够的精力去养一套冷门框架，也没有预算请专人维护基础设施。T3 组合里的每个组件都是各自领域的默认选项，这意味着遇到问题去搜索引擎一搜，基本都能找到答案。实际开发中确实如此，绝大多数报错都能在社区讨论里找到原因。

1.3 被我排除的备选方案

选型时我还认真考虑过另外两条路，这里记录一下排除理由，供参考：

• Next.js + Express/NestJS + REST：接口层要手写文档和类型同步，联调成本高，不符合小团队的协作模式。
• 纯前端静态站 + Supabase：Supabase 的 Row Level Security 确实强大，但权限模型的学习成本比写几个 tRPC 接口高得多，而且自托管时运维成本不低。

排除这两条之后，T3 组合几乎是顺理成章的选择。数据库用 Prisma 管理 schema 和迁移，认证直接接 NextAuth，样式用 Tailwind 保证全程不用写一行 CSS 文件。

2. 五个核心组件在 t3code 里的分工

2.1 Next.js App Router：路由与渲染边界

t3code 用的是 Next.js 14 的 App Router。项目里我坚持一个简单的划分原则：能放 Server Component 就放 Server Component，需要交互的叶子节点才标记 Client Component。

比如片段列表页，数据在服务端直接从数据库读取，经 tRPC 的 server caller 调用后渲染成静态列表，整个页面不包含任何 client 端数据请求逻辑。只有搜索框、筛选器、创建弹窗这类需要交互的组件，才单独标注"use client"。

这样做的好处是首屏 HTML 里直接有内容，搜索引擎能看到，用户打开页面也不用先等 JS 加载再渲染。内部工具虽然不太依赖 SEO，但加载速度直接影响同事用的意愿——一个打开要转两秒的工具，没人愿意天天用。

2.2 tRPC：把跨进程调用伪装成函数调用

tRPC 是 T3 组合里最关键的一块。它的本质是让前端代码直接调用服务端函数，类型通过 TypeScript 的泛型推导自动穿越网络边界。

我在 t3code 里按照业务域划分 router：snippetRouter、taskRouter、tagRouter、userRouter。每个 router 内部用createTRPCRouter定义若干 procedure，每个 procedure 用protectedProcedure或publicProcedure声明访问级别。

前端调用时，页面里只写一行api.snippet.getAll.useQuery()，返回的数据类型就自动对应服务端函数的返回类型。改数据库字段后，Prisma 类型重新生成，tRPC 类型跟着更新，前端如果用了不存在的字段，编辑器直接标红。这种"改一处、全链报错"的体验，正是我选这套组合的核心目的。

2.3 Prisma：数据库迁移与类型生成的自动化

t3code 的数据库用 PostgreSQL，ORM 选了 Prisma。主要原因倒不是 Prisma 本身多强，而是它和 TypeScript 的配合度是最顺滑的：prisma.schema文件里定义模型后，跑一条prisma generate就能得到完整的类型定义，并且这些类型会通过 tRPC 一路传到前端。

schema 设计上我踩过几次关系模型的坑，后面第 4 节会细说。这里先提一个原则：多对多关系一定要建显式的中间表，不要图省事用 JSON 数组存外键。比如片段和标签的关系，我建了SnippetTag中间表，带createdAt字段，这样后续要排序、去重、统计都有数据可用。

2.4 Tailwind CSS：原子类的组织方式

Tailwind 在 t3code 里负责全部样式。说实话，项目初期我对原子化 CSS 是持保留态度的，担心长类名影响可读性。实际用下来发现担心是多余的：组件拆分足够细的时候，每个组件的类名都在可控范围内，而且改样式不用全局搜索.css文件，直接在对应组件里改类名就行。

比较重要的经验是自定义主题色要在一开始就规划好。Tailwind 的默认色板偏向蓝色系，而 t3code 的品牌色是青绿色。我在tailwind.config.ts里扩展了brand色系，后续所有组件都引用bg-brand-500这类语义化类名，而不是直接写色值。这样改主题时只需要动配置文件，全站颜色自动生效。

2.5 NextAuth：登录与授权的接入细节

认证方案选了 NextAuth v4，配合 GitHub OAuth 和 Credentials 两种登录方式。内部工具用 GitHub 登录非常方便，团队成员都有账号，免去注册流程。

NextAuth 接入 T3 组合时有个固定套路：authOptions定义在src/server/auth.ts，tRPC 的createTRPCContext里读取 session，然后protectedProcedure检查session?.user是否存在，不存在则抛UNAUTHORIZED错误。

3. 类型安全是怎么贯穿全链路的

3.1 一条数据从数据库到页面的完整链路

拿最核心的"片段详情页"举例，一次请求背后的数据流是这样的：

1. Prisma schema 定义Snippet模型，prisma generate生成对应 TypeScript 类型
2. tRPC 的getByIdprocedure 调用 prisma 查询，返回对象自动携带 Snippet 类型
3. 前端调用api.snippet.getById.useQuery()，返回的 data 类型与 Snippet 完全一致
4. 页面里如果写了data.author.name，但 schema 里没有关联该字段，编辑器直接报类型错误

整条链路没有任何手动声明的 interface，所有类型都由一个源头（数据库 schema）推导而来。这在实际开发中节省的时间是肉眼可见的：我几乎再也没有遇到过"后端数据结构改了，前端忘了更新"这类问题。

3.2 Router 划分与类型导出的约定

t3code 的 tRPC 划分遵循一个约定：每个业务域一个文件，文件里只暴露 domain 相关的 procedure，不跨域调用其他 router 的内部函数。

比如snippetRouter里的createSnippet需要同时写入标签关联数据，它会直接调用 prisma 操作SnippetTag表，而不会去 importtagRouter的函数。这样做的原因是 tRPC 的 router 嵌套虽然方便，但跨域调用容易造成类型循环引用，排查起来非常痛苦。

Procedure 的输入参数统一用 Zod schema 声明。比如创建片段的输入：

const createSnippetSchema = z.object({ title: z.string().min(1).max(100), code: z.string().min(1), language: z.enum(["typescript", "javascript", "python", "sql", "bash"]), tags: z.array(z.string()).max(8), });

这个 schema 既能校验运行时输入，又能推导出前端调用时的参数类型。在编写页面表单时，"传给服务端的参数应该长什么样"这个问题直接由编辑器提示，根本不用查接口文档。

3.3 Zod 校验在服务端和客户端的复用

Zod 的一大优势是校验逻辑可以跨端复用。t3code 里，createSnippetSchema定义在src/server/schemas目录，前端表单提交前先做一次本地校验，后端 procedure 入口再用同样 schema 校验一次。

双端校验不是多此一举。本地校验能做即时反馈——用户没填标题，点提交按钮时立刻提示，不用等网络往返。服务端校验是最后防线，防止有人绕过前端直接请求接口。两者用同一个 schema 意味着不会出现"前端校验规则比后端严格"的诡异情况。

4. 排错实录：t3code 开发中值得记录的坑

4.1 NextAuth 的 Session 类型扩展

我在 t3code 里给 User 模型加了一个nickname字段，但页面上通过session.user.nickname访问时，TypeScript 一直报错。查了半天才发现 NextAuth 默认的Session类型里，user对象只有name、email、image三个字段。

解决办法是在src/types/next-auth.d.ts里声明模块扩展：

declare module "next-auth" { interface Session { user: { id: string; name?: string | null; nickname?: string | null; email?: string | null; image?: string | null; }; } }

这个坑的根源在于 NextAuth 的类型系统故意保持开放，让开发者按需扩展。问题是文档里写得不够显眼，新手很容易直接改User模型却忘了同步扩展 Session 类型。我建议 T3 项目脚手架生成后，第一件事就是把这个类型扩展文件写好，避免后续所有页面都在为 session 类型报错。

4.2 tRPC 在 Server Component 里的调用方式

App Router 全面铺开后，tRPC 的调用姿势也跟着变了。在 Client Component 里，useQuery是最好的方式；但在 Server Component 里，不能直接用useQuery，需要调用 tRPC 的server caller。

t3code 里我封装了一个serverApi实例，放在src/server/caller.ts：

export const serverApi = createCaller({ session: await getServerSession(authOptions), headers: await headers(), });

服务端页面里直接await serverApi.snippet.getAll({ search })，就能拿到数据并交给组件渲染。这个方案比用 fetch 调自身 API 干净得多，因为完全复用了 tRPC 的类型推导，而且少了一次 HTTP 往返。

让我印象最深的是：这个能力在官方文档里埋得有点深。如果直接从网上搜"tRPC + App Router"，出来的教程大多还是旧版 Client Component 方案，很容易让人在 Server 组件里硬塞"use client"，导致整个页面客户端渲染，首屏性能白白浪费。

4.3 Prisma 多对多关系的迁移问题

t3code 开发到第二周时，我想给片段增加"收藏"功能，即用户与片段之间多对多关系。第一次 schema 设计时我图省事，直接在Snippet模型里加了一个favoritedBy User[]字段配合隐式关系表。

问题出现在后续字段扩展：想在收藏关系上记录收藏时间，隐式关系表无法自定义字段，只能推倒重来改成显式中间表。那次迁移改了三个模型，还跑了一次数据回填脚本，花了整整一个下午。

教训是：凡是能预见需要在关系上附加属性的，第一次就用显式中间表。收藏、关注、点赞这类关系几乎必然会有"什么时间收藏的""收藏时的来源页面"这类元数据需求，不早点建中间表，后期迁移成本很高。

4.4 React Query 缓存导致的页面"假死"

t3code 的片段列表支持搜索和标签筛选，我之前用useQuery的标准写法：

const { data, refetch } = api.snippet.getAll.useQuery({ search, tag });

然后搜索框的 onChange 里调用refetch。实测发现：用户快速输入时会产生大量并发请求，而且输入过程中的请求结果会覆盖最终结果，导致页面显示的搜索结果是历史数据。典型的竞态问题。

排查后发现根因是 React Query 只管缓存，不会自动取消过期请求。旧请求返回慢时，它的结果会写入同一个 query key，把新结果顶掉。解决方式是不要在 onChange 里自动触发请求，改为表单提交或防抖 400ms 后再触发，同时给 query key 加上搜索词参数。改成防抖后问题彻底消失，还顺带减少了服务器压力。

4.5 Tailwind 动态类名不生效

这是个老坑，但我还是在 t3code 里踩了一次。代码高亮显示的语言标签，我写成className={badge-${language}}，结果页面上样式时有时无。

原因很直接：Tailwind 是静态扫描类名的，badge-typescript这种字符串没有被完整写在源码里，就会被判定为未使用，构建时被丢掉。解决办法是把语言标签的完整类名映射表写成一个对象：

const badgeClasses: Record<string, string> = { typescript: "bg-blue-100 text-blue-800", python: "bg-green-100 text-green-800", };

动态字符串拼接在 Tailwind 生态里是要尽量避免的。只要类名是动态拼出来的，构建时基本都会出问题。提前用映射表枚举好所有状态，比踩完之后再改成本低得多。

5. 部署与线上调优

5.1 部署环境与连接串配置

t3code 部署在 Vercel，数据库用了一家托管 Postgres 服务。整体部署过程比预期顺利，最需要注意的是环境变量的管理。

Prisma 在构建阶段需要扫描 schema、生成 client，所以构建机器上必须有数据库连接串执行prisma generate。我第一次部署时没有在 Vercel 后台配环境变量，导致构建失败，错误信息里 Prisma 找不到 schema 配置，排查了二十分钟才反应过来是环境变量没传。

此外，Vercel 的 serverless 函数对数据库连接数很敏感。每个函数实例都可能建立独立的数据库连接，连接数耗尽会导致间歇性超时。解决方式是把 PrismaClient 做成全局单例，避免每次调用都实例化：

const globalForPrisma = globalThis as unknown as { prisma: PrismaClient }; export const prisma = globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

这段代码 create-t3-app 已经默认生成，没必要删掉。我第一次见到觉得多余，后来在日志里看到大量连接建立记录，才明白这行的价值。

5.2 首屏性能实测与优化

上线后我用 Lighthouse 测了一遍性能，发现最主要问题是 JavaScript 体积偏大。排查发现是 tRPC 把服务端函数引用打包进了前端 bundle，加上 Zod 的全量校验逻辑，首屏 JS 超过了 300KB。

针对这个做了一轮优化：

• Zod 开启z.string().min(1)这类方法时，只引入实际使用的校验函数，能显著瘦身
• 非核心组件（如任务看板的拖拽库）用next/dynamic按需加载
• 语言标签的高亮渲染改为服务端完成，前端只接收渲染后的 HTML

优化后首屏 JS 降到 190KB 左右，Lighthouse 性能评分从 68 分提高到 89 分。内部工具虽然对性能容忍度高，但数据能说明问题：同事打开列表页的白屏时间从 1.8 秒降到 1.1 秒，试用意愿明显上一个台阶。

5.3 数据库查询的性能瓶颈

t3code 上线后最耗时的接口是"片段搜索"，原因是搜索关键词直接在 PostgreSQL 里用了contains操作，走了全表扫描。数据量只要到几千条，响应时间就会飙到 300ms 以上。

我没有引入 Elasticsearch 这类重型方案，而是直接给搜索字段加了 trigram 索引：

CREATE EXTENSION IF NOT EXISTS pg_trgm; CREATE INDEX snippet_code_trgm ON "Snippet" USING gin (code gin_trgm_ops);

配合 ILIKE 查询，搜索响应时间从 300ms 降到 40ms 左右。对内部工具的数据规模来说，这已经足够。如果后续数据量超过十万条，再考虑迁移到专门的全文搜索方案也不迟。

6. 复盘：T3 组合适合谁、不适合谁

6.1 收益最大的场景

t3code 这个项目跑完后，我对 T3 组合的定位有了更清楚的判断。它最适合几个人到十几个人的小团队做内部工具、MVP 原型、以及业务逻辑中类型安全价值高的中型应用。

这类项目的共性是没有庞大的 API 面需要对外暴露，没有复杂的微服务拆分需求，团队更关注的是"快速上线、稳定运行、后续好改"。T3 组合端点到端类型安全的特性，正好把最大的隐形成本——前后端协作的沟通损耗——压到最低。

6.2 不适合的场景

同时我也要坦白说，有几类场景我会谨慎推荐 T3：

• 需要对外开放 API 给第三方调用：tRPC 的类型安全只对 TypeScript 客户端有效，外部团队用 Java 或 Go 接入时，体验反而不如 REST + OpenAPI。
• 团队前后端技术栈差异极大：如果后端同事是 Java 背景，非要整体搬迁到 TypeScript 生态，学习成本会抵消类型安全带来的收益。
• 需要高频做数据报表和复杂查询：Prisma 的查询 API 对聚合查询支持一般，复杂 SQL 场景下用它的体验不如手写 SQL + 一个轻量 ORM。

6.3 后续打算

t3code 的第一版已经上线内测，团队反馈基本符合预期。后续我会在三个方向继续迭代：把任务看板升级成支持拖拽的看板视图，搜索从关键词匹配升级到拼音和全文检索，以及把团队内沉淀的代码片段接入 AI 辅助查询——输入一段描述直接联想相关片段。

技术上，如果要加这些功能，t3code 现有的架构不需要大改，最多在 tRPC 层新增几个 procedure，Prisma 层加两张表。这也从侧面说明当时的选型承受住了业务扩展的压力。

最后说点个人体会。做 t3code 之前，我对"端到端类型安全"的认知停留在概念层面，觉得无非是少写点 type 定义。真正写完一个完整项目才意识到，它带来的最大收益不是编译期报错的前置拦截，而是让我在写业务代码时敢大胆改数据结构——数据库字段改了，所有受影响的地方会像探照灯一样亮出来，不会有一处漏网。这种踏实感，是传统接口文档模式给不了的。如果你也在做类似的内部项目，不妨给自己一个机会试试这套组合，前提是团队基线统一在 TypeScript 上。