戰(zhàn)：用 TypeScript、Next.js、tRPC、Prisma 構(gòu)建全棧內(nèi)部工具)
去年年底我接了一個(gè)內(nèi)部工具的重構(gòu)需求項(xiàng)目代號(hào)就叫t3code。最初的需求很樸素把團(tuán)隊(duì)散落在各個(gè)文檔里的流程、命令和模板整理成一套可交互的網(wǎng)頁(yè)工具讓新同學(xué)能照著操作老同學(xué)能快速查參數(shù)。但做著做著我發(fā)現(xiàn)這個(gè)項(xiàng)目的技術(shù)選型比業(yè)務(wù)本身更值得聊——它最終落到了 TypeScript Next.js tRPC Prisma Tailwind 這一整套全棧組合上也就是社區(qū)里常說(shuō)的 T3 Stack。這篇文章我會(huì)把t3code從立項(xiàng)到部署全過(guò)程的思路、配置、代碼和踩過(guò)的坑完整寫(xiě)出來(lái)如果你正在糾結(jié)要不要用這套技術(shù)?；蛘咭呀?jīng)入坑想看看別人的實(shí)踐這篇應(yīng)該對(duì)你有用。先說(shuō)明一下t3code不是什么開(kāi)源框架也不是某個(gè)現(xiàn)成產(chǎn)品的倉(cāng)庫(kù)名它只是我給這個(gè)內(nèi)部項(xiàng)目起的代號(hào)。但這個(gè)代號(hào)背后選型的過(guò)程以及每一層技術(shù)承擔(dān)的角色完全可以作為一個(gè)全棧項(xiàng)目的參考樣本。接下來(lái)我會(huì)按照項(xiàng)目推進(jìn)的時(shí)間線來(lái)講先講整體設(shè)計(jì)和技術(shù)選型再講腳手架搭建和數(shù)據(jù)庫(kù)建模然后是 tRPC 的完整鏈路實(shí)現(xiàn)最后是部署和那些你上網(wǎng)搜都不一定搜得到的坑。1. 項(xiàng)目背景與整體設(shè)計(jì)思路1.1 項(xiàng)目要解決的痛點(diǎn)與拆解方式t3code這個(gè)項(xiàng)目的原始需求本質(zhì)上是把團(tuán)隊(duì)里的“隱形知識(shí)”變成“顯性工具”。我之前統(tǒng)計(jì)過(guò)團(tuán)隊(duì)內(nèi)部常用的命令、腳本、配置片段大概有六十多條分散在 Confluence、群公告、個(gè)人筆記里版本還對(duì)不上。比如同一個(gè)部署命令有人寫(xiě)成 Docker 形式有人寫(xiě)成裸進(jìn)程形式新同學(xué)照著舊文檔跑必然報(bào)錯(cuò)。所以第一版設(shè)計(jì)就定了三個(gè)原則所有內(nèi)容必須有唯一數(shù)據(jù)源、所有操作盡量能在線執(zhí)行而非復(fù)制粘貼、所有代碼示例必須與實(shí)際代碼倉(cāng)庫(kù)保持同步。為了做到這三點(diǎn)技術(shù)選型一開(kāi)始就沒(méi)什么懸念。前端需要一套成熟的 React 生態(tài)后端需要一個(gè)能直接復(fù)用前端類型定義的服務(wù)端方案數(shù)據(jù)庫(kù)需要一個(gè)支持快速迭代且類型安全的 ORM。結(jié)果就是 TypeScript 打底Next.js 做頁(yè)面和接口宿主tRPC 做端到端類型安全的通信Prisma 管理 PostgreSQL最后用 Tailwind 快速搭界面。這五個(gè)組件正好就是 T3 Stack 的完整陣容。這里我多說(shuō)一句為什么不用傳統(tǒng)的 REST 方案。如果按 REST 來(lái)寫(xiě)前端需要維護(hù)一套 API 路徑常量后端需要寫(xiě)路由和中間層校驗(yàn)兩邊各維護(hù)一份類型定義聯(lián)調(diào)時(shí)總會(huì)有一方先改。tRPC 的思路是讓你直接“調(diào)用函數(shù)”而且函數(shù)簽名里的類型是自動(dòng)從前端推斷到后端的改一處另一處馬上報(bào)錯(cuò)。對(duì)于t3code這種需要頻繁增刪字段的配置管理工具這個(gè)特性省下的是實(shí)實(shí)在在的開(kāi)發(fā)時(shí)間。1.2 為什么用 T3 Stack 而不是其他組合其實(shí)我在立項(xiàng)前也對(duì)比過(guò)幾套方案。第一套是 Next.js GraphQL TypeScriptGraphQL 的 schema 定義和安全校驗(yàn)都很強(qiáng)但對(duì)一個(gè)幾十個(gè)接口的內(nèi)部工具來(lái)說(shuō)寫(xiě) schema、配 resolver、維護(hù) fragment 的復(fù)雜度偏高收益不明顯。第二套是 NestJS React 前后端分離工程上是標(biāo)準(zhǔn)做法但兩個(gè)倉(cāng)庫(kù)之間的聯(lián)調(diào)和類型同步成本在兩個(gè)人開(kāi)發(fā)的小項(xiàng)目里會(huì)被放大。最終定下 T3 組合的核心原因可以歸納成三條單一代碼倉(cāng)庫(kù)、單一語(yǔ)言、單一類型系統(tǒng)前后端不存在“跨語(yǔ)言邊界”。初始化體驗(yàn)極好create-t3-app會(huì)把 Next.js、tRPC、Prisma、Tailwind 的工程模板一次性裝好省去手工拼裝的時(shí)間。社區(qū)維護(hù)積極Next.js 和 Prisma 的版本迭代都會(huì)被模板及時(shí)跟進(jìn)。另外要提一個(gè)反向觀點(diǎn)T3 Stack 不是銀彈。如果你的項(xiàng)目需要對(duì)外提供開(kāi)放 API或者有其他語(yǔ)言的服務(wù)端要對(duì)接tRPC 的“函數(shù)調(diào)用”模式就不太合適REST 或 GraphQL 才是兼容性更好的選擇。所以這個(gè)選型適合“前后端都由同一撥人維護(hù)的內(nèi)部工具類項(xiàng)目”t3code恰好屬于這一類。2. 從零搭建 t3code腳手架與核心配置2.1 初始化項(xiàng)目與選項(xiàng)選擇t3code的初始化我用的是官方腳手架一條命令就能拉起整套工程npx create-t3-applatest t3code過(guò)程會(huì)問(wèn)你幾個(gè)問(wèn)題這里把當(dāng)時(shí)的選擇列出來(lái)并解釋原因TypeScript必選整個(gè) T3 棧的基石不選就沒(méi)有類型安全可言。Next.js選 App Router 模式新項(xiàng)目沒(méi)必要再用 Pages Router。tRPC選這是前后端聯(lián)通的核心。Prisma選配合 PostgreSQL 使用。Tailwind CSS選界面開(kāi)發(fā)效率和一致性都靠它。初始化 Git選方便隨時(shí)回滾。導(dǎo)入路徑別名選/別名能讓代碼結(jié)構(gòu)更清晰。跑完之后目錄結(jié)構(gòu)是這樣的核心部分t3code/ ├── prisma/ │ ├── schema.prisma │ └── seed.ts ├── src/ │ ├── app/ │ │ ├── api/trpc/[trpc]/route.ts │ │ ├── layout.tsx │ │ └── page.tsx │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ ├── root.ts │ │ │ └── trpc.ts │ │ └── db.ts │ ├── trpc/ │ │ ├── server.ts │ │ └── client.ts │ └── styles/ │ └── globals.css └── .env這個(gè)結(jié)構(gòu)最有價(jià)值的地方在于src/server/api里寫(xiě)路由src/trpc里提供前后端共享的類型工具前端頁(yè)面完全可以直接引用server層的類型不需要額外的 d.ts 文件。2.2 環(huán)境變量與數(shù)據(jù)庫(kù)配置接下來(lái)是數(shù)據(jù)庫(kù)部分。t3code用的是 PostgreSQL我在本地用 Docker 起了個(gè)實(shí)例.env 配置如下DATABASE_URLpostgresql://postgres:passwordlocalhost:5432/t3code?schemapublic NEXT_PUBLIC_APP_URLhttp://localhost:3000注意一個(gè)細(xì)節(jié)create-t3-app生成的模板默認(rèn)會(huì)在src/server/db.ts里用globalThis做 Prisma 客戶端的全局緩存防止開(kāi)發(fā)模式下熱更新導(dǎo)致連接數(shù)暴增。這個(gè)是模板自動(dòng)處理的但如果你手動(dòng)搭建 Prisma一定要記得自己加這段。然后執(zhí)行遷移npx prisma migrate dev --name init這一步會(huì)根據(jù) schema 生成遷移 SQL 并同步數(shù)據(jù)庫(kù)同時(shí)生成最新的 Prisma Client整個(gè)鏈路到這里就通了。2.3 Tailwind 主題定制界面方面我沒(méi)有用現(xiàn)成的 UI 組件庫(kù)而是直接用 Tailwind 寫(xiě)了基礎(chǔ)樣式。t3code是一個(gè)內(nèi)部工具不需要花哨的視覺(jué)要的是信息密度和一致性。我在globals.css里定義了幾個(gè)關(guān)鍵的設(shè)計(jì)變量tailwind base; tailwind components; tailwind utilities; layer base { :root { --background: 210 40% 98%; --foreground: 222 47% 11%; --primary: 221 83% 53%; --muted: 214 32% 91%; } }這樣做的原因有兩點(diǎn)第一CSS 變量驅(qū)動(dòng)的主題方便后續(xù)加暗色模式不需要改組件代碼第二Tailwind 的hsl(var(--...))寫(xiě)法比硬編碼顏色更可維護(hù)。寫(xiě)組件時(shí)直接bg-background text-foreground就能跟隨主題變化非常順手。3. 核心鏈路用 tRPC 打通全棧類型安全3.1 tRPC 的三個(gè)核心概念tRPC 上手前先記住三個(gè)詞procedure、router、caller。procedure 是對(duì)后端函數(shù)的一個(gè)抽象分 query查詢和 mutation寫(xiě)操作兩類router 是多個(gè) procedure 的集合可以嵌套caller 是服務(wù)端內(nèi)部調(diào)用路由的方式用于在 Next.js 的 Server Component 里直接拿數(shù)據(jù)。t3code里我設(shè)計(jì)了一個(gè)基礎(chǔ)路由結(jié)構(gòu)// src/server/api/routers/entry.ts import { z } from zod; import { createTRPCRouter, publicProcedure } from ../trpc; export const entryRouter createTRPCRouter({ list: publicProcedure.query(async ({ ctx }) { return ctx.db.entry.findMany({ orderBy: { updatedAt: desc }, }); }), byId: publicProcedure.input(z.string()).query(async ({ ctx, input }) { return ctx.db.entry.findUnique({ where: { id: input } }); }), create: publicProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1), tags: z.array(z.string()).default([]), })) .mutation(async ({ ctx, input }) { return ctx.db.entry.create({ data: input }); }), });這里的zod校驗(yàn)是 tRPC 框架強(qiáng)推的因?yàn)檩斎腩愋秃桶踩ｒ?yàn)可以一次定義。比如create這個(gè) mutation如果前端傳了空字符串程序會(huì)在進(jìn)數(shù)據(jù)庫(kù)之前直接拒絕不需要在業(yè)務(wù)代碼里再寫(xiě)一遍 if 判斷。3.2 一個(gè)完整的 CRUD 實(shí)現(xiàn)鏈路上面這段只是服務(wù)端的路由前端是怎么調(diào)用的呢t3code的頁(yè)面組件里調(diào)用方式是這樣的use client; import { api } from ~/trpc/client; export function EntryList() { const { data, refetch } api.entry.list.useQuery(); const createEntry api.entry.create.useMutation({ onSuccess: () refetch(), }); return ( div {data?.map((entry) ( div key{entry.id} h3{entry.title}/h3 p{entry.content}/p /div ))} button onClick{() createEntry.mutate({ title: test, content: hello })} 添加 /button /div ); }這段代碼里有兩個(gè)容易被忽略但很關(guān)鍵的點(diǎn)。第一api.entry.list.useQuery()返回的data類型是直接從服務(wù)端entry.list這個(gè) procedure 的返回值推斷出來(lái)的。也就是說(shuō)如果后端改了返回結(jié)構(gòu)前端這里會(huì)立刻出現(xiàn)類型報(bào)錯(cuò)不用等接口聯(lián)調(diào)發(fā)現(xiàn)問(wèn)題。第二createEntry.mutate的入?yún)㈩愋鸵彩菑姆?wù)端輸入校驗(yàn)的 zod schema 自動(dòng)推斷的。服務(wù)端要求title必須是字符串且至少 1 個(gè)字符那么前端傳數(shù)字或空字符串在編輯階段就會(huì)報(bào)錯(cuò)。這里的時(shí)間收益是很直觀的內(nèi)部工具的需求變化特別頻繁昨天可能還要tags字段今天就要改成category在 REST 體系下要改后端 schema、前端 interface、接口文檔三處在 tRPC 下只需要改一處剩下兩處類型會(huì)自動(dòng)傳播。3.3 tRPC 和 Next.js Server Component 的結(jié)合除了客戶端調(diào)用t3code的很多頁(yè)面其實(shí)不需要交互只需要在服務(wù)端渲染時(shí)把數(shù)據(jù)取好。這種情況下不需要走 HTTP而是直接用createCaller// src/app/entries/page.tsx import { api } from ~/trpc/server; export default async function EntriesPage() { const entries await api.entry.list(); return ( main {entries.map((entry) ( div key{entry.id}{entry.title}/div ))} /main ); }注意這里的api是~/trpc/server導(dǎo)出的不是客戶端那個(gè)api。它會(huì)在服務(wù)端直接調(diào)用 router 里的函數(shù)數(shù)據(jù)不經(jīng)過(guò)網(wǎng)絡(luò)棧性能上比傳統(tǒng) SSR 還要好。這種寫(xiě)法非常適合內(nèi)容展示類的內(nèi)部頁(yè)面。不過(guò)要注意Server Component 里不能直接調(diào)用需要登錄態(tài)的 mutation因?yàn)?mutation 本身需要返回給前端觸發(fā)。t3code的做法是只讀數(shù)據(jù)用 Server Component需要交互的表單、編輯操作都用 Client Component 調(diào) mutation。4. 數(shù)據(jù)建模與遷移實(shí)戰(zhàn)Prisma 的細(xì)節(jié)與坑4.1 t3code 的數(shù)據(jù)模型設(shè)計(jì)t3code里最核心的數(shù)據(jù)是“條目”也就是那條命令或配置片段。它的模型定義如下model Entry { id String id default(cuid()) title String content String category String? tags String[] status Status default(ACTIVE) authorId String? createdAt DateTime default(now()) updatedAt DateTime updatedAt } enum Status { ACTIVE ARCHIVED } model Tag { id String id default(cuid()) name String unique entries Entry[] }這里我特意選了cuid()而不是自增 id原因很簡(jiǎn)單內(nèi)部工具的數(shù)據(jù)會(huì)頻繁導(dǎo)入導(dǎo)出cuid 不會(huì)因?yàn)閿?shù)據(jù)合并而沖突。tags直接用 PostgreSQL 的 string[] 類型省一張關(guān)聯(lián)表查詢hasTag的場(chǎng)景用tags [docker]就能完成夠用且簡(jiǎn)單。關(guān)于category一開(kāi)始我用了必填字段后來(lái)發(fā)現(xiàn)實(shí)際錄入時(shí)很多條目其實(shí)不好歸類改成了可選。這個(gè)調(diào)整是在實(shí)踐過(guò)程中發(fā)現(xiàn)的也印證了數(shù)據(jù)建模初期別把約束設(shè)得太死盡量給可選等數(shù)據(jù)量上來(lái)了再收緊更穩(wěn)妥。4.2 遷移與重置的坑Prisma 的migrate dev在開(kāi)發(fā)環(huán)境很好用但我踩過(guò)一個(gè)具體的坑當(dāng)我把一個(gè)字段從必填改成可選時(shí)prisma migrate dev生成了一個(gè)帶ALTER COLUMN的 SQL但本地?cái)?shù)據(jù)庫(kù)已經(jīng)有數(shù)據(jù)老數(shù)據(jù)里這個(gè)字段是 null導(dǎo)致在線遷移失敗。這個(gè)問(wèn)題的實(shí)際處理方案是用prisma db push來(lái)繞過(guò)遷移歷史直接同步 schema 到數(shù)據(jù)庫(kù)。但注意這會(huì)改變數(shù)據(jù)庫(kù)結(jié)構(gòu)而不產(chǎn)生遷移文件所以只在純開(kāi)發(fā)環(huán)境用。如果是多環(huán)境部署還是老老實(shí)實(shí)改遷移 SQL或者在 schema 改動(dòng)前先寫(xiě)一個(gè)默認(rèn)值填充腳本。另外還有一個(gè)高頻坑改了schema.prisma之后Prisma Client 的代碼是自動(dòng)生成的但在 Next.js 開(kāi)發(fā)模式下偶爾不會(huì)自動(dòng)刷新導(dǎo)致新字段報(bào)“Unknown argument”。處理方法是強(qiáng)制重新生成npx prisma generate然后重啟 dev server基本都能解決。4.3 種子數(shù)據(jù)與測(cè)試數(shù)據(jù)準(zhǔn)備t3code需要一個(gè)穩(wěn)定的種子數(shù)據(jù)來(lái)驗(yàn)證界面和接口。我在prisma/seed.ts里面放了十幾條真實(shí)常用的命令模板然后用 tsx 運(yùn)行npx tsx prisma/seed.ts種子腳本用 upsert 而不是 create這樣重復(fù)執(zhí)行不會(huì)報(bào)唯一鍵沖突import { PrismaClient } from prisma/client; const prisma new PrismaClient(); async function main() { const dockerEntry await prisma.entry.upsert({ where: { id: seed-docker }, update: {}, create: { id: seed-docker, title: Docker 容器啟動(dòng)模板, content: docker run -d --name demo -p 8080:80 nginx, tags: [docker, nginx], }, }); console.log(Seeded: ${dockerEntry.title}); } main().finally(() prisma.$disconnect());這里用固定 id 是一個(gè)經(jīng)驗(yàn)之談開(kāi)發(fā)時(shí)反復(fù) seed 不會(huì)生成重復(fù)數(shù)據(jù)而且可以放心地在代碼里硬編碼這個(gè) id 作為界面演示數(shù)據(jù)。5. 部署鏈路與性能優(yōu)化要點(diǎn)5.1 部署到 Vercel 的完整配置t3code最終部署在 Vercel 上因?yàn)?Next.js 應(yīng)用用它部署最省心而且支持自動(dòng)預(yù)覽部署分支推送就能生成獨(dú)立預(yù)覽環(huán)境對(duì)團(tuán)隊(duì)協(xié)作很友好。主要配置如下環(huán)境變量DATABASE_URL 用生產(chǎn) PostgreSQL 的地址。構(gòu)建命令prisma migrate deploy next build注意這里是migrate deploy而不是migrate dev前者只會(huì)執(zhí)行已生成的遷移文件不會(huì)在 CI 里創(chuàng)建新遷移?？蚣茴A(yù)設(shè)Vercel 會(huì)自動(dòng)識(shí)別 Next.js不需要額外配置。數(shù)據(jù)庫(kù)用的是 Neon 的 PostgreSQL 免費(fèi)版本身支持連接池。不過(guò)在 Vercel Serverless 環(huán)境下數(shù)據(jù)庫(kù)連接數(shù)很容易被并發(fā)請(qǐng)求打滿我的建議是檢查.env里的DATABASE_URL是否包含連接池參數(shù)例如?pgbouncertrueconnection_limit1。這一點(diǎn)很多人會(huì)忽略但實(shí)際部署后遇到連接數(shù)報(bào)錯(cuò)九成是這個(gè)原因。5.2 構(gòu)建體積與圖片優(yōu)化t3code這個(gè)項(xiàng)目本身不依賴重型可視化庫(kù)但 Next.js 默認(rèn)會(huì)把所有頁(yè)面打包到構(gòu)建產(chǎn)物里時(shí)間久了 bundle 會(huì)膨脹。我做了兩個(gè)優(yōu)化第一動(dòng)態(tài)導(dǎo)入只在需要時(shí)加載的重組件例如代碼高亮器const CodeBlock dynamic(() import(~/components/code-block), { loading: () p加載中.../p, });第二所有靜態(tài)圖片走 Next.js Image 組件自動(dòng)處理尺寸和 webp 格式。對(duì)于內(nèi)部工具圖片不多但每次訪問(wèn)都要拉原始大圖也沒(méi)有必要。Image 組件的sizes屬性一定要寫(xiě)否則會(huì)浪費(fèi)不少帶寬Image src{thumbnail} altcover width{400} height{225} sizes(max-width: 768px) 100vw, 400px /5.3 性能數(shù)據(jù)與復(fù)盤(pán)上線后我觀察了 Vercel 分析面板t3code的首頁(yè) LCP 穩(wěn)定在 1.2 秒以內(nèi)交互頁(yè)面 INP 在 200ms 以內(nèi)。對(duì)于一個(gè)內(nèi)部工具來(lái)說(shuō)這個(gè)數(shù)據(jù)已經(jīng)足夠好。需要注意如果未來(lái)?xiàng)l目數(shù)量增長(zhǎng)到上萬(wàn)條entry.list的裸查可能會(huì)成為瓶頸那時(shí)需要在 Prisma 查詢里加take分頁(yè)參數(shù)或者引入搜索。目前t3code的數(shù)據(jù)量在幾百條量級(jí)索引都命中沒(méi)必要過(guò)度設(shè)計(jì)。6. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄6.1 類型不更新的典型問(wèn)題tRPC 類型傳播是它的賣(mài)點(diǎn)但開(kāi)發(fā)中有一個(gè)很煩的現(xiàn)象后端路由改了前端報(bào)錯(cuò)卻還是舊類型。這個(gè)通常不是 tRPC 的問(wèn)題而是 TypeScript 的編譯器沒(méi)有重新生成聲明。在我遇到的情況里重啟 Next.js dev server 能解決九成問(wèn)題剩下的一成是tsconfig.json的include沒(méi)有覆蓋src/trpc目錄。排查步驟整理如下# 1. 強(qiáng)制重新生成 Prisma Client npx prisma generate # 2. 檢查 tRPC 類型看是否有顯式 any # 在代碼里搜索 : any如果有替換為具體類型 # 3. 重啟開(kāi)發(fā)服務(wù)器 # 如果還不行刪除 .next 目錄再啟動(dòng) rm -rf .next npm run dev這個(gè)三板斧在幾十個(gè)項(xiàng)目里都驗(yàn)證夠了不要一上來(lái)就懷疑框架有問(wèn)題。6.2 Prisma 連接數(shù)超限的排查前文提到了連接池這里展開(kāi)講一下真實(shí)的情況。部署初期t3code在 Vercel 上經(jīng)常報(bào)Too many clients錯(cuò)誤。排查步驟是先看日志確認(rèn)是數(shù)據(jù)庫(kù)連接數(shù)超過(guò) Neon 的限制再看DATABASE_URL有沒(méi)有配置連接池參數(shù)最后檢查代碼里有沒(méi)有重復(fù)創(chuàng)建 PrismaClient。create-t3-app模板自帶globalThis緩存不會(huì)重復(fù)創(chuàng)建最終問(wèn)題就落在連接池參數(shù)上。加上之后服務(wù)穩(wěn)定了沒(méi)有再次出現(xiàn)連接數(shù)告警。6.3 常見(jiàn)問(wèn)題速查表我整理了一張表記錄了t3code開(kāi)發(fā)中實(shí)際遇到的高頻問(wèn)題查閱或排查起來(lái)很省事?，F(xiàn)象原因解決方案本地接口返回 500Prisma Client 版本與數(shù)據(jù)庫(kù) Schema 不匹配執(zhí)行npx prisma generate后重啟 dev server部署構(gòu)建失敗遷移文件未執(zhí)行構(gòu)建命令加npx prisma migrate deploy生產(chǎn)環(huán)境連接數(shù)報(bào)錯(cuò)缺少連接池參數(shù)DATABASE_URL 加?pgbouncertrueconnection_limit1前端類型與后端不一致dev server 緩存舊類型rm -rf .next后重啟種子腳本重復(fù)執(zhí)行報(bào)錯(cuò)未使用 upsert改用upsert并設(shè)置固定 id字段改名后遷移失敗數(shù)據(jù)庫(kù)已有數(shù)據(jù)手動(dòng)編寫(xiě)遷移 SQL 或先補(bǔ)默認(rèn)值6.4 兩個(gè)值得分享的排查經(jīng)驗(yàn)除了上面這些常規(guī)問(wèn)題再講兩個(gè)t3code特有的經(jīng)驗(yàn)都是網(wǎng)上教程很少提到的。第一個(gè)是 Server Component 里調(diào)用 tRPC 時(shí)如果不小心把query寫(xiě)成了mutation瀏覽器端不會(huì)直接報(bào)錯(cuò)而是會(huì)在服務(wù)端渲染過(guò)程中拋出一個(gè)非常不直觀的錯(cuò)誤。排查的時(shí)候要看完整堆棧別只盯瀏覽器 console。正確的做法是只讀數(shù)據(jù)用api.someRouter.query寫(xiě)操作才用mutation兩者不要混用。第二個(gè)是 Tailwind 的自定義顏色變量在服務(wù)端渲染時(shí)可能會(huì)閃爍因?yàn)?CSS 變量在服務(wù)端首屏渲染時(shí)還沒(méi)掛載到:root。解決辦法是確保變量定義在layer base里且沒(méi)有在組件里覆蓋同名變量。這個(gè)問(wèn)題在新項(xiàng)目初始階段不明顯但一旦有人往全局樣式文件里多寫(xiě)了幾個(gè)--primary就會(huì)開(kāi)始亂。講一個(gè)更實(shí)際的經(jīng)驗(yàn)。t3code第二次迭代時(shí)我需要批量更新幾十條 seed 數(shù)據(jù)當(dāng)時(shí)偷懶沒(méi)有寫(xiě)腳本直接在 Prisma Studio 里手動(dòng)改。改到一半發(fā)現(xiàn)某個(gè)字段要全局替換才意識(shí)到這個(gè)操作應(yīng)該在腳本里做。后來(lái)我整理了一遍規(guī)范所有數(shù)據(jù)的導(dǎo)入導(dǎo)出、批量更新、字段遷移都必須通過(guò)prisma/scripts目錄下的腳本執(zhí)行禁止直接在數(shù)據(jù)庫(kù)管理工具里手改。這個(gè)規(guī)范看起來(lái)是自找麻煩但它保證了所有變更都有記錄、可回放對(duì)于內(nèi)部工具來(lái)說(shuō)這比花哨的功能更重要。我自己的體會(huì)是T3 Stack 給的真正優(yōu)勢(shì)不是某一個(gè)框架多強(qiáng)而是它們組合起來(lái)把“定義一次、到處使用”變成了現(xiàn)實(shí)前后端共享類型帶來(lái)的省心感只有當(dāng)你改完后端字段前端整條鏈路自動(dòng)同步時(shí)才有直觀感受。如果你手上也有類似t3code這種前后端同團(tuán)隊(duì)維護(hù)的內(nèi)部項(xiàng)目不妨按這套思路試一次從某種意義上說(shuō)它會(huì)改變你對(duì)全棧開(kāi)發(fā)的某些習(xí)慣。最后留個(gè)擴(kuò)展建議下一步可以給t3code加上簡(jiǎn)單的基于會(huì)話的登錄鑒權(quán)接入 tRPC 的 middleware這樣每一條 procedure 都能統(tǒng)一控制訪問(wèn)權(quán)限項(xiàng)目的完整度會(huì)再上一個(gè)臺(tái)階。 T3 Stack 實(shí)戰(zhàn)：用 TypeScript、Next.js、tRPC、Prisma 構(gòu)建全棧內(nèi)部工具
去年年底我接了一個(gè)內(nèi)部工具的重構(gòu)需求項(xiàng)目代號(hào)就叫t3code。最初的需求很樸素把團(tuán)隊(duì)散落在各個(gè)文檔里的流程、命令和模板整理成一套可交互的網(wǎng)頁(yè)工具讓新同學(xué)能照著操作老同學(xué)能快速查參數(shù)。但做著做著我發(fā)現(xiàn)這個(gè)項(xiàng)目的技術(shù)選型比業(yè)務(wù)本身更值得聊——它最終落到了 TypeScript Next.js tRPC Prisma Tailwind 這一整套全棧組合上也就是社區(qū)里常說(shuō)的 T3 Stack。這篇文章我會(huì)把t3code從立項(xiàng)到部署全過(guò)程的思路、配置、代碼和踩過(guò)的坑完整寫(xiě)出來(lái)如果你正在糾結(jié)要不要用這套技術(shù)?；蛘咭呀?jīng)入坑想看看別人的實(shí)踐這篇應(yīng)該對(duì)你有用。先說(shuō)明一下t3code不是什么開(kāi)源框架也不是某個(gè)現(xiàn)成產(chǎn)品的倉(cāng)庫(kù)名它只是我給這個(gè)內(nèi)部項(xiàng)目起的代號(hào)。但這個(gè)代號(hào)背后選型的過(guò)程以及每一層技術(shù)承擔(dān)的角色完全可以作為一個(gè)全棧項(xiàng)目的參考樣本。接下來(lái)我會(huì)按照項(xiàng)目推進(jìn)的時(shí)間線來(lái)講先講整體設(shè)計(jì)和技術(shù)選型再講腳手架搭建和數(shù)據(jù)庫(kù)建模然后是 tRPC 的完整鏈路實(shí)現(xiàn)最后是部署和那些你上網(wǎng)搜都不一定搜得到的坑。1. 項(xiàng)目背景與整體設(shè)計(jì)思路1.1 項(xiàng)目要解決的痛點(diǎn)與拆解方式t3code這個(gè)項(xiàng)目的原始需求本質(zhì)上是把團(tuán)隊(duì)里的“隱形知識(shí)”變成“顯性工具”。我之前統(tǒng)計(jì)過(guò)團(tuán)隊(duì)內(nèi)部常用的命令、腳本、配置片段大概有六十多條分散在 Confluence、群公告、個(gè)人筆記里版本還對(duì)不上。比如同一個(gè)部署命令有人寫(xiě)成 Docker 形式有人寫(xiě)成裸進(jìn)程形式新同學(xué)照著舊文檔跑必然報(bào)錯(cuò)。所以第一版設(shè)計(jì)就定了三個(gè)原則所有內(nèi)容必須有唯一數(shù)據(jù)源、所有操作盡量能在線執(zhí)行而非復(fù)制粘貼、所有代碼示例必須與實(shí)際代碼倉(cāng)庫(kù)保持同步。為了做到這三點(diǎn)技術(shù)選型一開(kāi)始就沒(méi)什么懸念。前端需要一套成熟的 React 生態(tài)后端需要一個(gè)能直接復(fù)用前端類型定義的服務(wù)端方案數(shù)據(jù)庫(kù)需要一個(gè)支持快速迭代且類型安全的 ORM。結(jié)果就是 TypeScript 打底Next.js 做頁(yè)面和接口宿主tRPC 做端到端類型安全的通信Prisma 管理 PostgreSQL最后用 Tailwind 快速搭界面。這五個(gè)組件正好就是 T3 Stack 的完整陣容。這里我多說(shuō)一句為什么不用傳統(tǒng)的 REST 方案。如果按 REST 來(lái)寫(xiě)前端需要維護(hù)一套 API 路徑常量后端需要寫(xiě)路由和中間層校驗(yàn)兩邊各維護(hù)一份類型定義聯(lián)調(diào)時(shí)總會(huì)有一方先改。tRPC 的思路是讓你直接“調(diào)用函數(shù)”而且函數(shù)簽名里的類型是自動(dòng)從前端推斷到后端的改一處另一處馬上報(bào)錯(cuò)。對(duì)于t3code這種需要頻繁增刪字段的配置管理工具這個(gè)特性省下的是實(shí)實(shí)在在的開(kāi)發(fā)時(shí)間。1.2 為什么用 T3 Stack 而不是其他組合其實(shí)我在立項(xiàng)前也對(duì)比過(guò)幾套方案。第一套是 Next.js GraphQL TypeScriptGraphQL 的 schema 定義和安全校驗(yàn)都很強(qiáng)但對(duì)一個(gè)幾十個(gè)接口的內(nèi)部工具來(lái)說(shuō)寫(xiě) schema、配 resolver、維護(hù) fragment 的復(fù)雜度偏高收益不明顯。第二套是 NestJS React 前后端分離工程上是標(biāo)準(zhǔn)做法但兩個(gè)倉(cāng)庫(kù)之間的聯(lián)調(diào)和類型同步成本在兩個(gè)人開(kāi)發(fā)的小項(xiàng)目里會(huì)被放大。最終定下 T3 組合的核心原因可以歸納成三條單一代碼倉(cāng)庫(kù)、單一語(yǔ)言、單一類型系統(tǒng)前后端不存在“跨語(yǔ)言邊界”。初始化體驗(yàn)極好create-t3-app會(huì)把 Next.js、tRPC、Prisma、Tailwind 的工程模板一次性裝好省去手工拼裝的時(shí)間。社區(qū)維護(hù)積極Next.js 和 Prisma 的版本迭代都會(huì)被模板及時(shí)跟進(jìn)。另外要提一個(gè)反向觀點(diǎn)T3 Stack 不是銀彈。如果你的項(xiàng)目需要對(duì)外提供開(kāi)放 API或者有其他語(yǔ)言的服務(wù)端要對(duì)接tRPC 的“函數(shù)調(diào)用”模式就不太合適REST 或 GraphQL 才是兼容性更好的選擇。所以這個(gè)選型適合“前后端都由同一撥人維護(hù)的內(nèi)部工具類項(xiàng)目”t3code恰好屬于這一類。2. 從零搭建 t3code腳手架與核心配置2.1 初始化項(xiàng)目與選項(xiàng)選擇t3code的初始化我用的是官方腳手架一條命令就能拉起整套工程npx create-t3-applatest t3code過(guò)程會(huì)問(wèn)你幾個(gè)問(wèn)題這里把當(dāng)時(shí)的選擇列出來(lái)并解釋原因TypeScript必選整個(gè) T3 棧的基石不選就沒(méi)有類型安全可言。Next.js選 App Router 模式新項(xiàng)目沒(méi)必要再用 Pages Router。tRPC選這是前后端聯(lián)通的核心。Prisma選配合 PostgreSQL 使用。Tailwind CSS選界面開(kāi)發(fā)效率和一致性都靠它。初始化 Git選方便隨時(shí)回滾。導(dǎo)入路徑別名選/別名能讓代碼結(jié)構(gòu)更清晰。跑完之后目錄結(jié)構(gòu)是這樣的核心部分t3code/ ├── prisma/ │ ├── schema.prisma │ └── seed.ts ├── src/ │ ├── app/ │ │ ├── api/trpc/[trpc]/route.ts │ │ ├── layout.tsx │ │ └── page.tsx │ ├── server/ │ │ ├── api/ │ │ │ ├── routers/ │ │ │ ├── root.ts │ │ │ └── trpc.ts │ │ └── db.ts │ ├── trpc/ │ │ ├── server.ts │ │ └── client.ts │ └── styles/ │ └── globals.css └── .env這個(gè)結(jié)構(gòu)最有價(jià)值的地方在于src/server/api里寫(xiě)路由src/trpc里提供前后端共享的類型工具前端頁(yè)面完全可以直接引用server層的類型不需要額外的 d.ts 文件。2.2 環(huán)境變量與數(shù)據(jù)庫(kù)配置接下來(lái)是數(shù)據(jù)庫(kù)部分。t3code用的是 PostgreSQL我在本地用 Docker 起了個(gè)實(shí)例.env 配置如下DATABASE_URLpostgresql://postgres:passwordlocalhost:5432/t3code?schemapublic NEXT_PUBLIC_APP_URLhttp://localhost:3000注意一個(gè)細(xì)節(jié)create-t3-app生成的模板默認(rèn)會(huì)在src/server/db.ts里用globalThis做 Prisma 客戶端的全局緩存防止開(kāi)發(fā)模式下熱更新導(dǎo)致連接數(shù)暴增。這個(gè)是模板自動(dòng)處理的但如果你手動(dòng)搭建 Prisma一定要記得自己加這段。然后執(zhí)行遷移npx prisma migrate dev --name init這一步會(huì)根據(jù) schema 生成遷移 SQL 并同步數(shù)據(jù)庫(kù)同時(shí)生成最新的 Prisma Client整個(gè)鏈路到這里就通了。2.3 Tailwind 主題定制界面方面我沒(méi)有用現(xiàn)成的 UI 組件庫(kù)而是直接用 Tailwind 寫(xiě)了基礎(chǔ)樣式。t3code是一個(gè)內(nèi)部工具不需要花哨的視覺(jué)要的是信息密度和一致性。我在globals.css里定義了幾個(gè)關(guān)鍵的設(shè)計(jì)變量tailwind base; tailwind components; tailwind utilities; layer base { :root { --background: 210 40% 98%; --foreground: 222 47% 11%; --primary: 221 83% 53%; --muted: 214 32% 91%; } }這樣做的原因有兩點(diǎn)第一CSS 變量驅(qū)動(dòng)的主題方便后續(xù)加暗色模式不需要改組件代碼第二Tailwind 的hsl(var(--...))寫(xiě)法比硬編碼顏色更可維護(hù)。寫(xiě)組件時(shí)直接bg-background text-foreground就能跟隨主題變化非常順手。3. 核心鏈路用 tRPC 打通全棧類型安全3.1 tRPC 的三個(gè)核心概念tRPC 上手前先記住三個(gè)詞procedure、router、caller。procedure 是對(duì)后端函數(shù)的一個(gè)抽象分 query查詢和 mutation寫(xiě)操作兩類router 是多個(gè) procedure 的集合可以嵌套caller 是服務(wù)端內(nèi)部調(diào)用路由的方式用于在 Next.js 的 Server Component 里直接拿數(shù)據(jù)。t3code里我設(shè)計(jì)了一個(gè)基礎(chǔ)路由結(jié)構(gòu)// src/server/api/routers/entry.ts import { z } from zod; import { createTRPCRouter, publicProcedure } from ../trpc; export const entryRouter createTRPCRouter({ list: publicProcedure.query(async ({ ctx }) { return ctx.db.entry.findMany({ orderBy: { updatedAt: desc }, }); }), byId: publicProcedure.input(z.string()).query(async ({ ctx, input }) { return ctx.db.entry.findUnique({ where: { id: input } }); }), create: publicProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1), tags: z.array(z.string()).default([]), })) .mutation(async ({ ctx, input }) { return ctx.db.entry.create({ data: input }); }), });這里的zod校驗(yàn)是 tRPC 框架強(qiáng)推的因?yàn)檩斎腩愋秃桶踩ｒ?yàn)可以一次定義。比如create這個(gè) mutation如果前端傳了空字符串程序會(huì)在進(jìn)數(shù)據(jù)庫(kù)之前直接拒絕不需要在業(yè)務(wù)代碼里再寫(xiě)一遍 if 判斷。3.2 一個(gè)完整的 CRUD 實(shí)現(xiàn)鏈路上面這段只是服務(wù)端的路由前端是怎么調(diào)用的呢t3code的頁(yè)面組件里調(diào)用方式是這樣的use client; import { api } from ~/trpc/client; export function EntryList() { const { data, refetch } api.entry.list.useQuery(); const createEntry api.entry.create.useMutation({ onSuccess: () refetch(), }); return ( div {data?.map((entry) ( div key{entry.id} h3{entry.title}/h3 p{entry.content}/p /div ))} button onClick{() createEntry.mutate({ title: test, content: hello })} 添加 /button /div ); }這段代碼里有兩個(gè)容易被忽略但很關(guān)鍵的點(diǎn)。第一api.entry.list.useQuery()返回的data類型是直接從服務(wù)端entry.list這個(gè) procedure 的返回值推斷出來(lái)的。也就是說(shuō)如果后端改了返回結(jié)構(gòu)前端這里會(huì)立刻出現(xiàn)類型報(bào)錯(cuò)不用等接口聯(lián)調(diào)發(fā)現(xiàn)問(wèn)題。第二createEntry.mutate的入?yún)㈩愋鸵彩菑姆?wù)端輸入校驗(yàn)的 zod schema 自動(dòng)推斷的。服務(wù)端要求title必須是字符串且至少 1 個(gè)字符那么前端傳數(shù)字或空字符串在編輯階段就會(huì)報(bào)錯(cuò)。這里的時(shí)間收益是很直觀的內(nèi)部工具的需求變化特別頻繁昨天可能還要tags字段今天就要改成category在 REST 體系下要改后端 schema、前端 interface、接口文檔三處在 tRPC 下只需要改一處剩下兩處類型會(huì)自動(dòng)傳播。3.3 tRPC 和 Next.js Server Component 的結(jié)合除了客戶端調(diào)用t3code的很多頁(yè)面其實(shí)不需要交互只需要在服務(wù)端渲染時(shí)把數(shù)據(jù)取好。這種情況下不需要走 HTTP而是直接用createCaller// src/app/entries/page.tsx import { api } from ~/trpc/server; export default async function EntriesPage() { const entries await api.entry.list(); return ( main {entries.map((entry) ( div key{entry.id}{entry.title}/div ))} /main ); }注意這里的api是~/trpc/server導(dǎo)出的不是客戶端那個(gè)api。它會(huì)在服務(wù)端直接調(diào)用 router 里的函數(shù)數(shù)據(jù)不經(jīng)過(guò)網(wǎng)絡(luò)棧性能上比傳統(tǒng) SSR 還要好。這種寫(xiě)法非常適合內(nèi)容展示類的內(nèi)部頁(yè)面。不過(guò)要注意Server Component 里不能直接調(diào)用需要登錄態(tài)的 mutation因?yàn)?mutation 本身需要返回給前端觸發(fā)。t3code的做法是只讀數(shù)據(jù)用 Server Component需要交互的表單、編輯操作都用 Client Component 調(diào) mutation。4. 數(shù)據(jù)建模與遷移實(shí)戰(zhàn)Prisma 的細(xì)節(jié)與坑4.1 t3code 的數(shù)據(jù)模型設(shè)計(jì)t3code里最核心的數(shù)據(jù)是“條目”也就是那條命令或配置片段。它的模型定義如下model Entry { id String id default(cuid()) title String content String category String? tags String[] status Status default(ACTIVE) authorId String? createdAt DateTime default(now()) updatedAt DateTime updatedAt } enum Status { ACTIVE ARCHIVED } model Tag { id String id default(cuid()) name String unique entries Entry[] }這里我特意選了cuid()而不是自增 id原因很簡(jiǎn)單內(nèi)部工具的數(shù)據(jù)會(huì)頻繁導(dǎo)入導(dǎo)出cuid 不會(huì)因?yàn)閿?shù)據(jù)合并而沖突。tags直接用 PostgreSQL 的 string[] 類型省一張關(guān)聯(lián)表查詢hasTag的場(chǎng)景用tags [docker]就能完成夠用且簡(jiǎn)單。關(guān)于category一開(kāi)始我用了必填字段后來(lái)發(fā)現(xiàn)實(shí)際錄入時(shí)很多條目其實(shí)不好歸類改成了可選。這個(gè)調(diào)整是在實(shí)踐過(guò)程中發(fā)現(xiàn)的也印證了數(shù)據(jù)建模初期別把約束設(shè)得太死盡量給可選等數(shù)據(jù)量上來(lái)了再收緊更穩(wěn)妥。4.2 遷移與重置的坑Prisma 的migrate dev在開(kāi)發(fā)環(huán)境很好用但我踩過(guò)一個(gè)具體的坑當(dāng)我把一個(gè)字段從必填改成可選時(shí)prisma migrate dev生成了一個(gè)帶ALTER COLUMN的 SQL但本地?cái)?shù)據(jù)庫(kù)已經(jīng)有數(shù)據(jù)老數(shù)據(jù)里這個(gè)字段是 null導(dǎo)致在線遷移失敗。這個(gè)問(wèn)題的實(shí)際處理方案是用prisma db push來(lái)繞過(guò)遷移歷史直接同步 schema 到數(shù)據(jù)庫(kù)。但注意這會(huì)改變數(shù)據(jù)庫(kù)結(jié)構(gòu)而不產(chǎn)生遷移文件所以只在純開(kāi)發(fā)環(huán)境用。如果是多環(huán)境部署還是老老實(shí)實(shí)改遷移 SQL或者在 schema 改動(dòng)前先寫(xiě)一個(gè)默認(rèn)值填充腳本。另外還有一個(gè)高頻坑改了schema.prisma之后Prisma Client 的代碼是自動(dòng)生成的但在 Next.js 開(kāi)發(fā)模式下偶爾不會(huì)自動(dòng)刷新導(dǎo)致新字段報(bào)“Unknown argument”。處理方法是強(qiáng)制重新生成npx prisma generate然后重啟 dev server基本都能解決。4.3 種子數(shù)據(jù)與測(cè)試數(shù)據(jù)準(zhǔn)備t3code需要一個(gè)穩(wěn)定的種子數(shù)據(jù)來(lái)驗(yàn)證界面和接口。我在prisma/seed.ts里面放了十幾條真實(shí)常用的命令模板然后用 tsx 運(yùn)行npx tsx prisma/seed.ts種子腳本用 upsert 而不是 create這樣重復(fù)執(zhí)行不會(huì)報(bào)唯一鍵沖突import { PrismaClient } from prisma/client; const prisma new PrismaClient(); async function main() { const dockerEntry await prisma.entry.upsert({ where: { id: seed-docker }, update: {}, create: { id: seed-docker, title: Docker 容器啟動(dòng)模板, content: docker run -d --name demo -p 8080:80 nginx, tags: [docker, nginx], }, }); console.log(Seeded: ${dockerEntry.title}); } main().finally(() prisma.$disconnect());這里用固定 id 是一個(gè)經(jīng)驗(yàn)之談開(kāi)發(fā)時(shí)反復(fù) seed 不會(huì)生成重復(fù)數(shù)據(jù)而且可以放心地在代碼里硬編碼這個(gè) id 作為界面演示數(shù)據(jù)。5. 部署鏈路與性能優(yōu)化要點(diǎn)5.1 部署到 Vercel 的完整配置t3code最終部署在 Vercel 上因?yàn)?Next.js 應(yīng)用用它部署最省心而且支持自動(dòng)預(yù)覽部署分支推送就能生成獨(dú)立預(yù)覽環(huán)境對(duì)團(tuán)隊(duì)協(xié)作很友好。主要配置如下環(huán)境變量DATABASE_URL 用生產(chǎn) PostgreSQL 的地址。構(gòu)建命令prisma migrate deploy next build注意這里是migrate deploy而不是migrate dev前者只會(huì)執(zhí)行已生成的遷移文件不會(huì)在 CI 里創(chuàng)建新遷移?？蚣茴A(yù)設(shè)Vercel 會(huì)自動(dòng)識(shí)別 Next.js不需要額外配置。數(shù)據(jù)庫(kù)用的是 Neon 的 PostgreSQL 免費(fèi)版本身支持連接池。不過(guò)在 Vercel Serverless 環(huán)境下數(shù)據(jù)庫(kù)連接數(shù)很容易被并發(fā)請(qǐng)求打滿我的建議是檢查.env里的DATABASE_URL是否包含連接池參數(shù)例如?pgbouncertrueconnection_limit1。這一點(diǎn)很多人會(huì)忽略但實(shí)際部署后遇到連接數(shù)報(bào)錯(cuò)九成是這個(gè)原因。5.2 構(gòu)建體積與圖片優(yōu)化t3code這個(gè)項(xiàng)目本身不依賴重型可視化庫(kù)但 Next.js 默認(rèn)會(huì)把所有頁(yè)面打包到構(gòu)建產(chǎn)物里時(shí)間久了 bundle 會(huì)膨脹。我做了兩個(gè)優(yōu)化第一動(dòng)態(tài)導(dǎo)入只在需要時(shí)加載的重組件例如代碼高亮器const CodeBlock dynamic(() import(~/components/code-block), { loading: () p加載中.../p, });第二所有靜態(tài)圖片走 Next.js Image 組件自動(dòng)處理尺寸和 webp 格式。對(duì)于內(nèi)部工具圖片不多但每次訪問(wèn)都要拉原始大圖也沒(méi)有必要。Image 組件的sizes屬性一定要寫(xiě)否則會(huì)浪費(fèi)不少帶寬Image src{thumbnail} altcover width{400} height{225} sizes(max-width: 768px) 100vw, 400px /5.3 性能數(shù)據(jù)與復(fù)盤(pán)上線后我觀察了 Vercel 分析面板t3code的首頁(yè) LCP 穩(wěn)定在 1.2 秒以內(nèi)交互頁(yè)面 INP 在 200ms 以內(nèi)。對(duì)于一個(gè)內(nèi)部工具來(lái)說(shuō)這個(gè)數(shù)據(jù)已經(jīng)足夠好。需要注意如果未來(lái)?xiàng)l目數(shù)量增長(zhǎng)到上萬(wàn)條entry.list的裸查可能會(huì)成為瓶頸那時(shí)需要在 Prisma 查詢里加take分頁(yè)參數(shù)或者引入搜索。目前t3code的數(shù)據(jù)量在幾百條量級(jí)索引都命中沒(méi)必要過(guò)度設(shè)計(jì)。6. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄6.1 類型不更新的典型問(wèn)題tRPC 類型傳播是它的賣(mài)點(diǎn)但開(kāi)發(fā)中有一個(gè)很煩的現(xiàn)象后端路由改了前端報(bào)錯(cuò)卻還是舊類型。這個(gè)通常不是 tRPC 的問(wèn)題而是 TypeScript 的編譯器沒(méi)有重新生成聲明。在我遇到的情況里重啟 Next.js dev server 能解決九成問(wèn)題剩下的一成是tsconfig.json的include沒(méi)有覆蓋src/trpc目錄。排查步驟整理如下# 1. 強(qiáng)制重新生成 Prisma Client npx prisma generate # 2. 檢查 tRPC 類型看是否有顯式 any # 在代碼里搜索 : any如果有替換為具體類型 # 3. 重啟開(kāi)發(fā)服務(wù)器 # 如果還不行刪除 .next 目錄再啟動(dòng) rm -rf .next npm run dev這個(gè)三板斧在幾十個(gè)項(xiàng)目里都驗(yàn)證夠了不要一上來(lái)就懷疑框架有問(wèn)題。6.2 Prisma 連接數(shù)超限的排查前文提到了連接池這里展開(kāi)講一下真實(shí)的情況。部署初期t3code在 Vercel 上經(jīng)常報(bào)Too many clients錯(cuò)誤。排查步驟是先看日志確認(rèn)是數(shù)據(jù)庫(kù)連接數(shù)超過(guò) Neon 的限制再看DATABASE_URL有沒(méi)有配置連接池參數(shù)最后檢查代碼里有沒(méi)有重復(fù)創(chuàng)建 PrismaClient。create-t3-app模板自帶globalThis緩存不會(huì)重復(fù)創(chuàng)建最終問(wèn)題就落在連接池參數(shù)上。加上之后服務(wù)穩(wěn)定了沒(méi)有再次出現(xiàn)連接數(shù)告警。6.3 常見(jiàn)問(wèn)題速查表我整理了一張表記錄了t3code開(kāi)發(fā)中實(shí)際遇到的高頻問(wèn)題查閱或排查起來(lái)很省事?，F(xiàn)象原因解決方案本地接口返回 500Prisma Client 版本與數(shù)據(jù)庫(kù) Schema 不匹配執(zhí)行npx prisma generate后重啟 dev server部署構(gòu)建失敗遷移文件未執(zhí)行構(gòu)建命令加npx prisma migrate deploy生產(chǎn)環(huán)境連接數(shù)報(bào)錯(cuò)缺少連接池參數(shù)DATABASE_URL 加?pgbouncertrueconnection_limit1前端類型與后端不一致dev server 緩存舊類型rm -rf .next后重啟種子腳本重復(fù)執(zhí)行報(bào)錯(cuò)未使用 upsert改用upsert并設(shè)置固定 id字段改名后遷移失敗數(shù)據(jù)庫(kù)已有數(shù)據(jù)手動(dòng)編寫(xiě)遷移 SQL 或先補(bǔ)默認(rèn)值6.4 兩個(gè)值得分享的排查經(jīng)驗(yàn)除了上面這些常規(guī)問(wèn)題再講兩個(gè)t3code特有的經(jīng)驗(yàn)都是網(wǎng)上教程很少提到的。第一個(gè)是 Server Component 里調(diào)用 tRPC 時(shí)如果不小心把query寫(xiě)成了mutation瀏覽器端不會(huì)直接報(bào)錯(cuò)而是會(huì)在服務(wù)端渲染過(guò)程中拋出一個(gè)非常不直觀的錯(cuò)誤。排查的時(shí)候要看完整堆棧別只盯瀏覽器 console。正確的做法是只讀數(shù)據(jù)用api.someRouter.query寫(xiě)操作才用mutation兩者不要混用。第二個(gè)是 Tailwind 的自定義顏色變量在服務(wù)端渲染時(shí)可能會(huì)閃爍因?yàn)?CSS 變量在服務(wù)端首屏渲染時(shí)還沒(méi)掛載到:root。解決辦法是確保變量定義在layer base里且沒(méi)有在組件里覆蓋同名變量。這個(gè)問(wèn)題在新項(xiàng)目初始階段不明顯但一旦有人往全局樣式文件里多寫(xiě)了幾個(gè)--primary就會(huì)開(kāi)始亂。講一個(gè)更實(shí)際的經(jīng)驗(yàn)。t3code第二次迭代時(shí)我需要批量更新幾十條 seed 數(shù)據(jù)當(dāng)時(shí)偷懶沒(méi)有寫(xiě)腳本直接在 Prisma Studio 里手動(dòng)改。改到一半發(fā)現(xiàn)某個(gè)字段要全局替換才意識(shí)到這個(gè)操作應(yīng)該在腳本里做。后來(lái)我整理了一遍規(guī)范所有數(shù)據(jù)的導(dǎo)入導(dǎo)出、批量更新、字段遷移都必須通過(guò)prisma/scripts目錄下的腳本執(zhí)行禁止直接在數(shù)據(jù)庫(kù)管理工具里手改。這個(gè)規(guī)范看起來(lái)是自找麻煩但它保證了所有變更都有記錄、可回放對(duì)于內(nèi)部工具來(lái)說(shuō)這比花哨的功能更重要。我自己的體會(huì)是T3 Stack 給的真正優(yōu)勢(shì)不是某一個(gè)框架多強(qiáng)而是它們組合起來(lái)把“定義一次、到處使用”變成了現(xiàn)實(shí)前后端共享類型帶來(lái)的省心感只有當(dāng)你改完后端字段前端整條鏈路自動(dòng)同步時(shí)才有直觀感受。如果你手上也有類似t3code這種前后端同團(tuán)隊(duì)維護(hù)的內(nèi)部項(xiàng)目不妨按這套思路試一次從某種意義上說(shuō)它會(huì)改變你對(duì)全棧開(kāi)發(fā)的某些習(xí)慣。最后留個(gè)擴(kuò)展建議下一步可以給t3code加上簡(jiǎn)單的基于會(huì)話的登錄鑒權(quán)接入 tRPC 的 middleware這樣每一條 procedure 都能統(tǒng)一控制訪問(wèn)權(quán)限項(xiàng)目的完整度會(huì)再上一個(gè)臺(tái)階。