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