實(shí)戰(zhàn)：TypeScript+tRPC+Next.js打造類型安全應(yīng)用)
1. 項(xiàng)目整體設(shè)計(jì)與技術(shù)選型思路1.1 t3code 到底是什么解決什么痛點(diǎn)先說清楚結(jié)論t3code并不是某個(gè)開源框架的名字而是我在實(shí)際工作中沉淀的一套基于 T3 技術(shù)棧的編碼實(shí)踐項(xiàng)目代號(hào)。所謂 T3 棧核心就是TypeScript Tailwind CSS tRPC這三件套的組合通常還會(huì)搭配 Next.js、Prisma、NextAuth.js 一起使用。t3code這個(gè)項(xiàng)目要解決的核心問題其實(shí)非常樸素過去寫一個(gè)全棧應(yīng)用前端、后端、數(shù)據(jù)庫三端各寫各的類型對(duì)不上、接口文檔過時(shí)、聯(lián)調(diào)成本高改一個(gè)字段可能要牽扯三處代碼。T3 棧的價(jià)值在于用 TypeScript 把這三端串成一條完整的類型安全鏈路讓編譯器在開發(fā)階段就幫我們擋住一大半低級(jí)錯(cuò)誤。很多朋友第一次聽到 T3 棧時(shí)會(huì)覺得它是一個(gè)很新的東西其實(shí)它只是把已經(jīng)成熟的工具用一種更舒服的方式組合起來。TypeScript 負(fù)責(zé)全鏈路類型系統(tǒng)Tailwind CSS 負(fù)責(zé)樣式層的原子化表達(dá)tRPC 負(fù)責(zé)前后端接口調(diào)用。這個(gè)組合最吸引人的地方在于你在服務(wù)端寫一個(gè)查詢函數(shù)前端不用手寫 API 請(qǐng)求代碼也不用維護(hù)一份接口定義文件類型和調(diào)用方式會(huì)直接“同步”到客戶端。t3code就是圍繞這套組合做的一個(gè)完整示例工程。適合誰來參考如果你正在做 Next.js 全棧項(xiàng)目或者對(duì)“類型安全”很在意又或者你已經(jīng)被前后端接口對(duì)不上、聯(lián)調(diào)效率低下折磨過那這篇文章的實(shí)操內(nèi)容可以直接套用到你的項(xiàng)目里。如果你是剛接觸 TypeScript 或 Next.js 的新手跟著走一遍也能建立起對(duì)現(xiàn)代全棧開發(fā)流程的完整認(rèn)知。1.2 為什么選 T3 棧類型安全不是玄學(xué)先說 TypeScript?，F(xiàn)在再爭(zhēng)論“要不要用 TypeScript”其實(shí)已經(jīng)沒有意義了真正的問題是怎么用好它。在 t3code 項(xiàng)目里TypeScript 承擔(dān)的角色不只是給變量加類型標(biāo)注而是貫穿整個(gè)應(yīng)用的類型契約制定者。從prisma.schema里定義的數(shù)據(jù)模型到 tRPC router 里的輸入輸出類型再到 React 組件里接收的 props全鏈路都在同一個(gè)類型體系里運(yùn)轉(zhuǎn)。這意味著你在數(shù)據(jù)庫里加了一個(gè)字段保存后類型會(huì)自動(dòng)傳導(dǎo)到前端如果哪個(gè)組件沒適配編輯器里立刻就會(huì)標(biāo)紅。Tailwind CSS 的選擇理由更偏向工程效率。業(yè)務(wù)項(xiàng)目里 80% 的樣式其實(shí)都是“排列、間距、顏色、圓角、陰影”這些組合。用原子類直接在 JSX 里寫省去了頻繁切換 CSS 文件的成本。有人會(huì)詬病 className 太長(zhǎng)但配合組件拆分這其實(shí)不是問題一個(gè)按鈕組件的樣式是固定的你只需要封裝一次后面所有用到的地方都是干凈的接口。Tailwind 還天然解決了樣式作用域問題不會(huì)出現(xiàn)全局樣式互相覆蓋的災(zāi)難。tRPC 是最讓人“上頭”的環(huán)節(jié)。傳統(tǒng)前后端通信要寫 REST 接口、定義 DTO、手寫請(qǐng)求方法還要維護(hù)一份常常過期的接口文檔。tRPC 直接用一個(gè)函數(shù)調(diào)用代替 HTTP 請(qǐng)求的書寫成本前端調(diào)用trpc.post.list.useQuery()后端定義同名 procedure類型和用法全部自動(dòng)推導(dǎo)。這種體驗(yàn)就像在本地調(diào)用一個(gè)異步函數(shù)只不過這個(gè)函數(shù)跑在服務(wù)器上。1.3 方案取舍的深層邏輯選型過程中我也做過其他方向的權(quán)衡。比如為什么不直接用 GraphQLGraphQL 確實(shí)也能做到類型安全但你需要額外配置 schema、resolver、codegen整條鏈路重了不少。對(duì)于中小型項(xiàng)目來說tRPC 的學(xué)習(xí)成本更低心智負(fù)擔(dān)更小。再比如為什么不干脆用 Next.js 的 API Routes React Query這當(dāng)然可行但你需要手動(dòng)維護(hù) API 路徑、請(qǐng)求類型、錯(cuò)誤處理而這些 tRPC 都幫你封裝掉了。t3code項(xiàng)目的最終技術(shù)棧是Next.js 14App Router TypeScript 5 Tailwind CSS 3 tRPC v10 Prisma SQLite。SQLite 的選用是為了本地開發(fā)零配置起步不需要單獨(dú)裝數(shù)據(jù)庫服務(wù)這在演示和教學(xué)場(chǎng)景下是一個(gè)巨大的便利。生產(chǎn)環(huán)境切換到 Postgres 只需要改一行環(huán)境變量和 connection stringPrisma 的適配層把這種切換成本降到了最低。2. 環(huán)環(huán)相扣的初始化實(shí)戰(zhàn)2.1 初始化前的環(huán)境準(zhǔn)備動(dòng)手之前需要確認(rèn)本機(jī)環(huán)境Node.js 18建議 20 LTS我實(shí)際使用的是 20.11、pnpm 包管理器、Git。Node 版本這塊不用太糾結(jié)只要滿足 Next.js 14 的要求就行。包管理器我推薦 pnpm除了安裝速度快更重要的是它嚴(yán)格的依賴隔離能避免很多“我機(jī)器上明明是好的”這類玄學(xué)問題。你用 npm 或者 yarn 也完全沒問題但有一點(diǎn)必須統(tǒng)一鎖文件要提交到倉庫里別在團(tuán)隊(duì)里混用不同包管理器否則 node_modules 結(jié)構(gòu)不一致會(huì)引發(fā)各種詭異 Bug。我見過太多次因?yàn)?npm 和 yarn 混用導(dǎo)致的依賴版本錯(cuò)亂問題了這是新手最容易忽視的細(xì)節(jié)。2.2 create-t3-app 初始化流程初始化使用社區(qū)官方腳手架create-t3-app這條命令會(huì)自動(dòng)完成所有基礎(chǔ)配置。用 pnpm 執(zhí)行pnpm create t3-applatest交互式命令行會(huì)讓你填項(xiàng)目名稱我們輸入t3code。接著是技術(shù)棧選項(xiàng)清單按需勾選Next.js必然項(xiàng)選 App RouterTypeScript默認(rèn)開啟無需取消Tailwind CSS必選這是 T3 的 TtRPC必選這是 T3 的第三個(gè) TPrisma必選負(fù)責(zé)數(shù)據(jù)庫訪問NextAuth.js如果后續(xù)要做登錄注冊(cè)就選上我這個(gè)項(xiàng)目暫時(shí)沒做認(rèn)證所以沒有勾選還有一個(gè)容易被忽略的選項(xiàng)是ESLint / Prettier建議都開啟。ESLint 幫你攔住低級(jí)錯(cuò)誤Prettier 統(tǒng)一代碼風(fēng)格省去團(tuán)隊(duì)里格式化爭(zhēng)論。初始化完成后腳手架會(huì)自動(dòng)安裝依賴并生成完整的目錄結(jié)構(gòu)。注意初始化時(shí)如果網(wǎng)絡(luò)不穩(wěn)定部分依賴下載會(huì)失敗。最直接的解決辦法是刪除 node_modules 和鎖文件后重裝pnpm install。如果公司網(wǎng)絡(luò)受限需要提前配置好 npm 鏡像源。2.3 目錄結(jié)構(gòu)逐層解讀初始化的目錄結(jié)構(gòu)體現(xiàn)了 T3 棧的核心思想我們逐層拆解t3code/ ├── prisma/ │ └── schema.prisma # 數(shù)據(jù)模型定義 ├── src/ │ ├── pages/ # 頁面路由如果選的是 Pages Router │ ├── app/ # App Router 路由 │ ├── server/ │ │ ├── api/ # tRPC 路由注冊(cè) │ │ ├── auth/ # 認(rèn)證相關(guān)本項(xiàng)目未啟用 │ │ ├── db.ts # Prisma 客戶端實(shí)例 │ │ └── trpc.ts # tRPC 上下文與初始化 │ ├── styles/ # 全局樣式 │ ├── trpc/ # 前端 tRPC 客戶端封裝 │ └── utils/ # 工具函數(shù) ├── .env # 環(huán)境變量數(shù)據(jù)庫連接等 └── package.json關(guān)鍵點(diǎn)有兩個(gè)。第一src/server/trpc.ts是整個(gè) tRPC 能力的核心注冊(cè)文件所有 API procedure 的上下文比如當(dāng)前用戶信息、數(shù)據(jù)庫實(shí)例都從這里創(chuàng)建。第二src/trpc目錄對(duì)應(yīng)前端調(diào)用所需的 client 和 hooks 封裝。這兩側(cè)的代碼由腳手架自動(dòng)生成我們實(shí)際開發(fā)時(shí)主要往src/server/api/routers目錄里添加業(yè)務(wù) router。3. 核心功能實(shí)現(xiàn)一個(gè)完整的全棧 CRUD3.1 定義數(shù)據(jù)模型Prisma Schema我實(shí)現(xiàn)了一個(gè)真實(shí)的業(yè)務(wù)場(chǎng)景文章管理。包含分類和文章兩張表文章通過外鍵關(guān)聯(lián)到分類。prisma/schema.prisma的核心定義如下generator client { provider prisma-client-js } datasource db { provider sqlite url env(DATABASE_URL) } model Category { id String id default(cuid()) name String unique slug String unique posts Post[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Post { id String id default(cuid()) title String content String published Boolean default(false) categoryId String category Category relation(fields: [categoryId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt }這里主鍵用的不是自增數(shù)字而是cuid()原因在于分布式環(huán)境下自增 ID 容易在數(shù)據(jù)合并或遷移時(shí)產(chǎn)生沖突cuid 由時(shí)間戳隨機(jī)數(shù)生成不依賴中央序列在導(dǎo)出導(dǎo)入、多環(huán)境部署場(chǎng)景下都更穩(wěn)。多對(duì)多場(chǎng)景你可能會(huì)想用manyToMany但 Prisma 目前更推薦顯式定義中間表來維護(hù)關(guān)系比如文章標(biāo)簽就是三張模型。定義好 schema 后執(zhí)行兩條命令pnpm prisma migrate dev --name init pnpm prisma generate第一條命令創(chuàng)建數(shù)據(jù)庫表結(jié)構(gòu)并生成遷移記錄第二條命令生成類型安全的 Prisma Client。這里特別強(qiáng)調(diào)generate必須每次在 schema 變更后執(zhí)行否則 Prisma Client 無法反映最新的模型而你編輯代碼時(shí)看到的類型提示也會(huì)是舊的。我把postbuild: prisma generate加到了 package.json 的構(gòu)建流程里防止部署時(shí)漏掉這一步。3.2 服務(wù)端 tRPC Router 編寫服務(wù)端 API 的編寫方式非常直接。所有業(yè)務(wù)邏輯都組織在src/server/api/routers目錄下。文章管理的 router 長(zhǎng)這樣import { z } from zod; import { createTRPCRouter, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure .input(z.object({ category: z.string().optional() })) .query(async ({ ctx, input }) { return ctx.db.post.findMany({ where: input.category ? { category: { slug: input.category } } : undefined, include: { category: true }, orderBy: { createdAt: desc }, }); }), byId: publicProcedure .input(z.string()) .query(async ({ ctx, input }) { return ctx.db.post.findUnique({ where: { id: input }, include: { category: true }, }); }), create: publicProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1), categoryId: z.string(), published: z.boolean().default(false), })) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: input }); }), });注意到幾個(gè)關(guān)鍵設(shè)計(jì)。第一publicProcedure表示任何人都能訪問等接入認(rèn)證后可以替換為protectedProcedure。第二輸入校驗(yàn)全部交給 Zod 完成Zod 的類型推導(dǎo)能力讓我們不需要手寫接口的Input和Output類型。第三也是 tRPC 的殺手锏你寫了這份 router 之后前端就能拿到完全對(duì)應(yīng)的類型推導(dǎo)拼錯(cuò)一個(gè)字段名都會(huì)在編譯期報(bào)警而不是等到運(yùn)行時(shí)給你一個(gè) 500 或者 400。list這個(gè) query 我選了按分類 slug 過濾的寫法而沒有直接傳分類 ID因?yàn)榍岸寺酚缮象w現(xiàn)的多是語義化的 slug比如/posts/tech。語義化標(biāo)識(shí)作為對(duì)外暴露的查詢條件內(nèi)部 ID 作為關(guān)聯(lián)約束這種區(qū)分在建模時(shí)是個(gè)重要的習(xí)慣。3.3 前端調(diào)用與服務(wù)端無縫銜接前端代碼需要考慮的反而更少這是好事。在服務(wù)端寫好了postRouter之后要在根 router 里掛載// src/server/api/root.ts export const appRouter createTRPCRouter({ post: postRouter, category: categoryRouter, });前端通過生成的 React hooks 調(diào)用import { api } from ~/trpc/react; export function PostList({ categorySlug }: { categorySlug?: string }) { const { data, isLoading, error } api.post.list.useQuery({ category: categorySlug, }); if (isLoading) return div加載中.../div; if (error) return div加載失敗{error.message}/div; return ( div classNamegrid gap-4 {data?.map((post) ( article key{post.id} classNamerounded-lg border p-4 h2 classNametext-xl font-semibold{post.title}/h2 p classNametext-sm text-gray-500{post.category.name}/p p classNamemt-2 line-clamp-3{post.content}/p /article ))} /div ); }注意data的類型它是Post { category: Category }[]是服務(wù)端返回結(jié)構(gòu)的精確映射。這就是 tRPC 最讓人踏實(shí)的地方前后端口徑不一致的問題從架構(gòu)層面被消滅了接口文檔、“手寫 DTO”這些概念都變成了歷史名詞。新寫一個(gè) mutation 也同樣簡(jiǎn)單調(diào)用api.post.create.useMutation()提交成功后刷新列表即可。這里我踩過一個(gè)坑mutation 之后需要手動(dòng)執(zhí)行utils.post.list.invalidate()來刷新緩存如果不做這步新建的數(shù)據(jù)不會(huì)立刻出現(xiàn)在列表里。這一點(diǎn)和 React Query 的失效機(jī)制一致寫業(yè)務(wù)代碼時(shí)很容易忘。3.4 頁面組裝與 Tailwind 樣式落地有了 API 能力頁面組裝就是純粹的 UI 工作。我用 Tailwind 構(gòu)建了一個(gè)簡(jiǎn)易的發(fā)布頁面表單字段包括標(biāo)題、正文、分類和發(fā)布開關(guān)。表單提交部分的代碼const createPost api.post.create.useMutation({ onSuccess: () { utils.post.list.invalidate(); router.push(/); }, }); function handleSubmit(e: React.FormEvent) { e.preventDefault(); const formData new FormData(e.currentTarget); createPost.mutate({ title: String(formData.get(title)), content: String(formData.get(content)), categoryId: String(formData.get(category)), }); }UI 上用 Tailwind 類控制間距和邊框整個(gè)開發(fā)過程不需要碰 CSS 文件。Tailwind 的daisyUI或shadcn/ui組件庫可以進(jìn)一步提速但我建議在學(xué)原理階段先手寫樣式這樣對(duì)布局和響應(yīng)式斷點(diǎn)會(huì)有更扎實(shí)的理解。4. 常見問題與排查技巧實(shí)錄4.1 Prisma 數(shù)據(jù)庫連接與遷移問題問題一DATABASE_URL未設(shè)置初始化后第一件必做的事是配置.env。腳手架會(huì)生成一個(gè).env模板但不會(huì)自動(dòng)填入值。直接用相對(duì)路徑配置 SQLiteDATABASE_URLfile:./db.sqlite如果不設(shè)置就運(yùn)行prisma migrate會(huì)直接報(bào)錯(cuò)提示環(huán)境變量缺失。這個(gè)問題很蠢但很多人遇到過包括我自己。問題二遷移歷史沖突本地開發(fā)時(shí)經(jīng)常要改 schema有時(shí)直接改了 schema 但沒有跑 migration下一次migrate dev時(shí)會(huì)提示 migration history 不一致。解決辦法是在非生產(chǎn)環(huán)境直接prisma migrate reset清庫重來但生產(chǎn)環(huán)境千萬別這么干。更穩(wěn)妥的方式是遵從migrate dev --create-only先生成 SQL檢查無誤后再migrate dev執(zhí)行。4.2 tRPC 類型推導(dǎo)失效的排查問題一前端 api 對(duì)象找不到新加的 router我遇到過兩次這種情況。root router 里已經(jīng)掛載了新 router但前端始終無法識(shí)別。排查后發(fā)現(xiàn)是tsc的 watch 模式?jīng)]完全重啟或者 dev server 緩存了舊的類型聲明。解決方案是重啟 dev server如果重啟后問題依舊檢查src/trpc/react.tsx中引用的AppRouter類型是不是來自root.ts確實(shí)有同事直接 import 了錯(cuò)誤路徑的 router 類型。路徑寫錯(cuò)時(shí)前端類型肯定不對(duì)。問題二Zod 輸入類型收窄不理想tRPC 的輸入類型由 Zod schema 推導(dǎo)如果你用了.transform()或.refine()推導(dǎo)出的類型可能是精煉后的類型而不是原始輸入類型。這時(shí)候需要顯式聲明.input(z.object({ id: z.string() }).transform((val) ({ id: val.id })))這個(gè) transform 的輸出類型會(huì)被當(dāng)作 procedure 的輸入類型。理解這一點(diǎn)排查 Zod 相關(guān)類型問題會(huì)快很多。4.3 常見錯(cuò)誤速查表錯(cuò)誤現(xiàn)象可能原因處理方式PrismaClientInitializationError數(shù)據(jù)庫文件不存在或路徑錯(cuò)誤檢查.env的DATABASE_URL執(zhí)行prisma migrate devtRPC 調(diào)用返回 404router 未掛載到 root router檢查root.ts確認(rèn)已添加對(duì)應(yīng) router前端 TypeScript 報(bào)錯(cuò)Property does not existtRPC 類型未更新重啟 dev server刪除.next緩存構(gòu)建失敗Type errorZod 類型和實(shí)際返回類型不一致檢查 mutation/query 的返回值和模型字段是否對(duì)應(yīng)樣式不生效Tailwind 掃描路徑配置不全確認(rèn)tailwind.config.ts的 content 字符串包含./src/**/*.{ts,tsx}表單中文無法正常提交字符編碼問題確保頁面設(shè)置了 UTF-8且數(shù)據(jù)庫編碼正確SQLite 本身無此問題遷移到 MySQL/Postgres 時(shí)注意4.4 兩個(gè)值得復(fù)制的實(shí)戰(zhàn)習(xí)慣第一個(gè)習(xí)慣是寫 seed 數(shù)據(jù)。開發(fā)階段沒有數(shù)據(jù)列表頁永遠(yuǎn)是空的你很難判斷布局。我在prisma/seed.ts里寫了幾條示例數(shù)據(jù)然后加入 package.json 腳本prisma:seed: tsx prisma/seed.ts執(zhí)行pnpm prisma db seed即可填充基礎(chǔ)數(shù)據(jù)這比起手打樣本快得多。seed 腳本里我反復(fù)調(diào)用 upsert 保證冪等性重復(fù)執(zhí)行不會(huì)堆積重復(fù)數(shù)據(jù)。第二個(gè)習(xí)慣是給 tRPC procedure 加合理的錯(cuò)誤處理。默認(rèn)情況下Zod 校驗(yàn)失敗會(huì)拋異常前端收到一個(gè)籠統(tǒng)的Bad Request。更友好的做法是在 router 里用try/catch包裹業(yè)務(wù)邏輯并通過TRPCError拋出結(jié)構(gòu)化錯(cuò)誤碼import { TRPCError } from trpc/server; if (!category) { throw new TRPCError({ code: NOT_FOUND, message: 分類不存在, }); }這樣前端拿到錯(cuò)誤提示就能直接展示給用戶而不是看到一行技術(shù)文檔式的英文報(bào)錯(cuò)。5. 前后端交互的進(jìn)階優(yōu)化5.1 樂觀更新體驗(yàn)CRUD 功能跑通并不意味體驗(yàn)就合格。寫評(píng)論或編輯文章時(shí)如果每次都要等服務(wù)器返回后才刷新界面整個(gè)操作會(huì)顯得很遲鈍。tRPC 基于 React Query天然支持樂觀更新。以一個(gè)更新文章標(biāo)題的例子說明const updateTitle api.post.updateTitle.useMutation({ onMutate: async ({ id, title }) { // 取消正在進(jìn)行的查詢避免覆蓋樂觀更新 await utils.post.list.cancel(); // 讀取當(dāng)前緩存快照 const prev utils.post.list.getData(); // 直接修改緩存中的文章標(biāo)題 utils.post.list.setData(undefined, (old) old?.map((post) post.id id ? { ...post, title } : post) ); return { prev }; }, onError: (err, _vars, context) { // 回滾原來的標(biāo)題 utils.post.list.setData(undefined, context?.prev); }, onSettled: () { // 最終重新拉取服務(wù)器數(shù)據(jù)保證一致 utils.post.list.invalidate(); }, });這個(gè)模式的核心價(jià)值在于響應(yīng)是即時(shí)的無論網(wǎng)絡(luò)多慢界面都先給用戶反饋。連帶思路要提的是不適合樂觀更新的場(chǎng)景是寫操作依賴服務(wù)端計(jì)算結(jié)果的邏輯比如金額計(jì)算這種就別樂觀更新了老老實(shí)實(shí)等真實(shí)返回。5.2 服務(wù)端查詢與數(shù)據(jù)復(fù)用Next.js App Router 下 tRPC 的另一個(gè)好搭檔是 Server Components。你可以直接在服務(wù)端調(diào)用 tRPC procedureimport { api } from ~/trpc/server; async function Page({ params }: { params: { slug: string } }) { const posts await api.post.list.query({ category: params.slug }); return PostGrid posts{posts} /; }這種方式?jīng)]有額外的客戶端網(wǎng)絡(luò)請(qǐng)求頁面渲染性能更好同時(shí)類型依然是全鏈路安全的。實(shí)際項(xiàng)目中公開數(shù)據(jù)比如文章詳情可以用服務(wù)端查詢而需要交互的數(shù)據(jù)比如點(diǎn)贊、收藏則交給客戶端 hooks。兩條路徑和諧共存不會(huì)互相沖突。6. 部署上線與監(jiān)控補(bǔ)全6.1 SQLite 到生產(chǎn)數(shù)據(jù)庫的切換本地用 SQLite 太舒適等要部署到生產(chǎn)時(shí)必須慎重。SQLite 并發(fā)性能有限生產(chǎn)推薦切換到 Postgres。修改方法很簡(jiǎn)單.env里換成 Postgres 的連接串然后在 schema 文件把 provider 改成postgresql執(zhí)行prisma migrate deploy。這里有個(gè)關(guān)鍵點(diǎn)連接串不要寫在倉庫里放到部署平臺(tái)的環(huán)境變量中.env始終通過.env.example模板來約定字段。6.2 部署到 VercelT3 棧項(xiàng)目部署到 Vercel 是相當(dāng)順滑的。Vercel 會(huì)自動(dòng)識(shí)別 Next.js 項(xiàng)目你只需要在后臺(tái)配置好環(huán)境變量。有一個(gè)容易踩的坑Vercel 的構(gòu)建環(huán)境是只讀文件系統(tǒng)而 Prisma 在構(gòu)建時(shí)需要生成 client。我的做法是在 package.json 的 build 腳本里加上prisma generate確保構(gòu)建時(shí)生成正確類型的 client。另外構(gòu)建階段不需要執(zhí)行 migrate因?yàn)閿?shù)據(jù)庫遷移應(yīng)該在發(fā)布流程中單獨(dú)跑或者在 Vercel 的 Prebuild 命令里顯式運(yùn)行prisma migrate deploy二選一別重復(fù)執(zhí)行。6.3 日志、監(jiān)控與錯(cuò)誤收集上線之后不能當(dāng)瞎子。我個(gè)人推薦接一套監(jiān)控方案Sentry 負(fù)責(zé)前端與后端異常收集Logflare 或類似服務(wù)收集應(yīng)用日志。tRPC 的錯(cuò)誤會(huì)通過 JSON 返回前端Sentry 的 Next.js SDK 會(huì)自動(dòng)捕捉 unhandled rejection 和部分 fetch 錯(cuò)誤但要確保把 tRPCError 也傳播給 Sentry。加上按錯(cuò)誤碼和路徑分組的維度后線上問題定位會(huì)快很多。部署完成后再次加強(qiáng)環(huán)境NODE_ENVproduction、DATABASE_URL指向生產(chǎn)庫、NEXTAUTH_SECRET如果啟用認(rèn)證隨機(jī)生成。Vercel 里可以關(guān)閉自動(dòng)休眠以便內(nèi)部工具保持響應(yīng)但不用過度追求 Serverless 性能調(diào)優(yōu)先把服務(wù)跑穩(wěn)比什么都重要。7. 常見問題的最后一輪梳理再整理幾個(gè)我從t3code項(xiàng)目排障過程中總結(jié)出的高頻問題方便你做 checklist。依賴/環(huán)境類create-t3-app初始化時(shí) Node 版本過低提示需要 18升級(jí) Node 后解決。安裝后pnpm dev報(bào)Cannot find module把 node_modules 重裝一遍同時(shí)檢查 pnpm 版本。Tailwind class 不生效檢查tailwind.config.ts中的 content 是否覆蓋了src/**。Prisma 類prisma migrate dev報(bào)錯(cuò)Environment variable not found: DATABASE_URL原因和解決辦法上文已說。字段改了但前端類型沒變記得prisma generate并重啟 dev server。生產(chǎn)環(huán)境用 SQLite 導(dǎo)致并發(fā)寫入鎖 DB盡早切到 Postgres。tRPC 類新加 router 后前端api對(duì)象 404確認(rèn) root router 已掛載。前端報(bào)NOT_FOUND或UNAUTHORIZED確認(rèn) procedure 用的是publicProcedure還是protectedProcedure。輸入校驗(yàn)不通過返回 400利用 Zod 的.message()給中文提示提升聯(lián)調(diào)效率。開發(fā)體驗(yàn)類mutation 成功后 UI 沒更新調(diào)用invalidate刷新緩存。類型推導(dǎo)不出來的地方把鼠標(biāo)懸停在調(diào)用點(diǎn)看懂推導(dǎo)鏈路往往能定位問題。強(qiáng)烈建議用 ESLint 規(guī)則typescript-eslint/consistent-type-imports強(qiáng)制import type避免運(yùn)行時(shí) import 類型造成模塊加載問題。t3code做到這個(gè)階段已經(jīng)是一個(gè)非常完整的中小型全棧應(yīng)用了。它覆蓋了模型建模、API 實(shí)現(xiàn)、前端消費(fèi)、部署上線和問題監(jiān)控的全流程。個(gè)人體驗(yàn)下來T3 棧最大的爽感在于每次改動(dòng)字段后整個(gè)前后端圍繞字段的類型都跟著同步那種“編譯器幫我檢查一切”的安心感是傳統(tǒng) REST 開發(fā)完全給不了的。如果你正在規(guī)劃自己的下一個(gè)全棧小項(xiàng)目完全可以拿這個(gè)套路練手把認(rèn)證加進(jìn)去再補(bǔ)一個(gè)后臺(tái)管理系統(tǒng)就變成了一個(gè)能直接對(duì)外展示的作品。 T3棧全棧開發(fā)實(shí)戰(zhàn)：TypeScript+tRPC+Next.js打造類型安全應(yīng)用
1. 項(xiàng)目整體設(shè)計(jì)與技術(shù)選型思路1.1 t3code 到底是什么解決什么痛點(diǎn)先說清楚結(jié)論t3code并不是某個(gè)開源框架的名字而是我在實(shí)際工作中沉淀的一套基于 T3 技術(shù)棧的編碼實(shí)踐項(xiàng)目代號(hào)。所謂 T3 棧核心就是TypeScript Tailwind CSS tRPC這三件套的組合通常還會(huì)搭配 Next.js、Prisma、NextAuth.js 一起使用。t3code這個(gè)項(xiàng)目要解決的核心問題其實(shí)非常樸素過去寫一個(gè)全棧應(yīng)用前端、后端、數(shù)據(jù)庫三端各寫各的類型對(duì)不上、接口文檔過時(shí)、聯(lián)調(diào)成本高改一個(gè)字段可能要牽扯三處代碼。T3 棧的價(jià)值在于用 TypeScript 把這三端串成一條完整的類型安全鏈路讓編譯器在開發(fā)階段就幫我們擋住一大半低級(jí)錯(cuò)誤。很多朋友第一次聽到 T3 棧時(shí)會(huì)覺得它是一個(gè)很新的東西其實(shí)它只是把已經(jīng)成熟的工具用一種更舒服的方式組合起來。TypeScript 負(fù)責(zé)全鏈路類型系統(tǒng)Tailwind CSS 負(fù)責(zé)樣式層的原子化表達(dá)tRPC 負(fù)責(zé)前后端接口調(diào)用。這個(gè)組合最吸引人的地方在于你在服務(wù)端寫一個(gè)查詢函數(shù)前端不用手寫 API 請(qǐng)求代碼也不用維護(hù)一份接口定義文件類型和調(diào)用方式會(huì)直接“同步”到客戶端。t3code就是圍繞這套組合做的一個(gè)完整示例工程。適合誰來參考如果你正在做 Next.js 全棧項(xiàng)目或者對(duì)“類型安全”很在意又或者你已經(jīng)被前后端接口對(duì)不上、聯(lián)調(diào)效率低下折磨過那這篇文章的實(shí)操內(nèi)容可以直接套用到你的項(xiàng)目里。如果你是剛接觸 TypeScript 或 Next.js 的新手跟著走一遍也能建立起對(duì)現(xiàn)代全棧開發(fā)流程的完整認(rèn)知。1.2 為什么選 T3 棧類型安全不是玄學(xué)先說 TypeScript?，F(xiàn)在再爭(zhēng)論“要不要用 TypeScript”其實(shí)已經(jīng)沒有意義了真正的問題是怎么用好它。在 t3code 項(xiàng)目里TypeScript 承擔(dān)的角色不只是給變量加類型標(biāo)注而是貫穿整個(gè)應(yīng)用的類型契約制定者。從prisma.schema里定義的數(shù)據(jù)模型到 tRPC router 里的輸入輸出類型再到 React 組件里接收的 props全鏈路都在同一個(gè)類型體系里運(yùn)轉(zhuǎn)。這意味著你在數(shù)據(jù)庫里加了一個(gè)字段保存后類型會(huì)自動(dòng)傳導(dǎo)到前端如果哪個(gè)組件沒適配編輯器里立刻就會(huì)標(biāo)紅。Tailwind CSS 的選擇理由更偏向工程效率。業(yè)務(wù)項(xiàng)目里 80% 的樣式其實(shí)都是“排列、間距、顏色、圓角、陰影”這些組合。用原子類直接在 JSX 里寫省去了頻繁切換 CSS 文件的成本。有人會(huì)詬病 className 太長(zhǎng)但配合組件拆分這其實(shí)不是問題一個(gè)按鈕組件的樣式是固定的你只需要封裝一次后面所有用到的地方都是干凈的接口。Tailwind 還天然解決了樣式作用域問題不會(huì)出現(xiàn)全局樣式互相覆蓋的災(zāi)難。tRPC 是最讓人“上頭”的環(huán)節(jié)。傳統(tǒng)前后端通信要寫 REST 接口、定義 DTO、手寫請(qǐng)求方法還要維護(hù)一份常常過期的接口文檔。tRPC 直接用一個(gè)函數(shù)調(diào)用代替 HTTP 請(qǐng)求的書寫成本前端調(diào)用trpc.post.list.useQuery()后端定義同名 procedure類型和用法全部自動(dòng)推導(dǎo)。這種體驗(yàn)就像在本地調(diào)用一個(gè)異步函數(shù)只不過這個(gè)函數(shù)跑在服務(wù)器上。1.3 方案取舍的深層邏輯選型過程中我也做過其他方向的權(quán)衡。比如為什么不直接用 GraphQLGraphQL 確實(shí)也能做到類型安全但你需要額外配置 schema、resolver、codegen整條鏈路重了不少。對(duì)于中小型項(xiàng)目來說tRPC 的學(xué)習(xí)成本更低心智負(fù)擔(dān)更小。再比如為什么不干脆用 Next.js 的 API Routes React Query這當(dāng)然可行但你需要手動(dòng)維護(hù) API 路徑、請(qǐng)求類型、錯(cuò)誤處理而這些 tRPC 都幫你封裝掉了。t3code項(xiàng)目的最終技術(shù)棧是Next.js 14App Router TypeScript 5 Tailwind CSS 3 tRPC v10 Prisma SQLite。SQLite 的選用是為了本地開發(fā)零配置起步不需要單獨(dú)裝數(shù)據(jù)庫服務(wù)這在演示和教學(xué)場(chǎng)景下是一個(gè)巨大的便利。生產(chǎn)環(huán)境切換到 Postgres 只需要改一行環(huán)境變量和 connection stringPrisma 的適配層把這種切換成本降到了最低。2. 環(huán)環(huán)相扣的初始化實(shí)戰(zhàn)2.1 初始化前的環(huán)境準(zhǔn)備動(dòng)手之前需要確認(rèn)本機(jī)環(huán)境Node.js 18建議 20 LTS我實(shí)際使用的是 20.11、pnpm 包管理器、Git。Node 版本這塊不用太糾結(jié)只要滿足 Next.js 14 的要求就行。包管理器我推薦 pnpm除了安裝速度快更重要的是它嚴(yán)格的依賴隔離能避免很多“我機(jī)器上明明是好的”這類玄學(xué)問題。你用 npm 或者 yarn 也完全沒問題但有一點(diǎn)必須統(tǒng)一鎖文件要提交到倉庫里別在團(tuán)隊(duì)里混用不同包管理器否則 node_modules 結(jié)構(gòu)不一致會(huì)引發(fā)各種詭異 Bug。我見過太多次因?yàn)?npm 和 yarn 混用導(dǎo)致的依賴版本錯(cuò)亂問題了這是新手最容易忽視的細(xì)節(jié)。2.2 create-t3-app 初始化流程初始化使用社區(qū)官方腳手架create-t3-app這條命令會(huì)自動(dòng)完成所有基礎(chǔ)配置。用 pnpm 執(zhí)行pnpm create t3-applatest交互式命令行會(huì)讓你填項(xiàng)目名稱我們輸入t3code。接著是技術(shù)棧選項(xiàng)清單按需勾選Next.js必然項(xiàng)選 App RouterTypeScript默認(rèn)開啟無需取消Tailwind CSS必選這是 T3 的 TtRPC必選這是 T3 的第三個(gè) TPrisma必選負(fù)責(zé)數(shù)據(jù)庫訪問NextAuth.js如果后續(xù)要做登錄注冊(cè)就選上我這個(gè)項(xiàng)目暫時(shí)沒做認(rèn)證所以沒有勾選還有一個(gè)容易被忽略的選項(xiàng)是ESLint / Prettier建議都開啟。ESLint 幫你攔住低級(jí)錯(cuò)誤Prettier 統(tǒng)一代碼風(fēng)格省去團(tuán)隊(duì)里格式化爭(zhēng)論。初始化完成后腳手架會(huì)自動(dòng)安裝依賴并生成完整的目錄結(jié)構(gòu)。注意初始化時(shí)如果網(wǎng)絡(luò)不穩(wěn)定部分依賴下載會(huì)失敗。最直接的解決辦法是刪除 node_modules 和鎖文件后重裝pnpm install。如果公司網(wǎng)絡(luò)受限需要提前配置好 npm 鏡像源。2.3 目錄結(jié)構(gòu)逐層解讀初始化的目錄結(jié)構(gòu)體現(xiàn)了 T3 棧的核心思想我們逐層拆解t3code/ ├── prisma/ │ └── schema.prisma # 數(shù)據(jù)模型定義 ├── src/ │ ├── pages/ # 頁面路由如果選的是 Pages Router │ ├── app/ # App Router 路由 │ ├── server/ │ │ ├── api/ # tRPC 路由注冊(cè) │ │ ├── auth/ # 認(rèn)證相關(guān)本項(xiàng)目未啟用 │ │ ├── db.ts # Prisma 客戶端實(shí)例 │ │ └── trpc.ts # tRPC 上下文與初始化 │ ├── styles/ # 全局樣式 │ ├── trpc/ # 前端 tRPC 客戶端封裝 │ └── utils/ # 工具函數(shù) ├── .env # 環(huán)境變量數(shù)據(jù)庫連接等 └── package.json關(guān)鍵點(diǎn)有兩個(gè)。第一src/server/trpc.ts是整個(gè) tRPC 能力的核心注冊(cè)文件所有 API procedure 的上下文比如當(dāng)前用戶信息、數(shù)據(jù)庫實(shí)例都從這里創(chuàng)建。第二src/trpc目錄對(duì)應(yīng)前端調(diào)用所需的 client 和 hooks 封裝。這兩側(cè)的代碼由腳手架自動(dòng)生成我們實(shí)際開發(fā)時(shí)主要往src/server/api/routers目錄里添加業(yè)務(wù) router。3. 核心功能實(shí)現(xiàn)一個(gè)完整的全棧 CRUD3.1 定義數(shù)據(jù)模型Prisma Schema我實(shí)現(xiàn)了一個(gè)真實(shí)的業(yè)務(wù)場(chǎng)景文章管理。包含分類和文章兩張表文章通過外鍵關(guān)聯(lián)到分類。prisma/schema.prisma的核心定義如下generator client { provider prisma-client-js } datasource db { provider sqlite url env(DATABASE_URL) } model Category { id String id default(cuid()) name String unique slug String unique posts Post[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Post { id String id default(cuid()) title String content String published Boolean default(false) categoryId String category Category relation(fields: [categoryId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt }這里主鍵用的不是自增數(shù)字而是cuid()原因在于分布式環(huán)境下自增 ID 容易在數(shù)據(jù)合并或遷移時(shí)產(chǎn)生沖突cuid 由時(shí)間戳隨機(jī)數(shù)生成不依賴中央序列在導(dǎo)出導(dǎo)入、多環(huán)境部署場(chǎng)景下都更穩(wěn)。多對(duì)多場(chǎng)景你可能會(huì)想用manyToMany但 Prisma 目前更推薦顯式定義中間表來維護(hù)關(guān)系比如文章標(biāo)簽就是三張模型。定義好 schema 后執(zhí)行兩條命令pnpm prisma migrate dev --name init pnpm prisma generate第一條命令創(chuàng)建數(shù)據(jù)庫表結(jié)構(gòu)并生成遷移記錄第二條命令生成類型安全的 Prisma Client。這里特別強(qiáng)調(diào)generate必須每次在 schema 變更后執(zhí)行否則 Prisma Client 無法反映最新的模型而你編輯代碼時(shí)看到的類型提示也會(huì)是舊的。我把postbuild: prisma generate加到了 package.json 的構(gòu)建流程里防止部署時(shí)漏掉這一步。3.2 服務(wù)端 tRPC Router 編寫服務(wù)端 API 的編寫方式非常直接。所有業(yè)務(wù)邏輯都組織在src/server/api/routers目錄下。文章管理的 router 長(zhǎng)這樣import { z } from zod; import { createTRPCRouter, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ list: publicProcedure .input(z.object({ category: z.string().optional() })) .query(async ({ ctx, input }) { return ctx.db.post.findMany({ where: input.category ? { category: { slug: input.category } } : undefined, include: { category: true }, orderBy: { createdAt: desc }, }); }), byId: publicProcedure .input(z.string()) .query(async ({ ctx, input }) { return ctx.db.post.findUnique({ where: { id: input }, include: { category: true }, }); }), create: publicProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1), categoryId: z.string(), published: z.boolean().default(false), })) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: input }); }), });注意到幾個(gè)關(guān)鍵設(shè)計(jì)。第一publicProcedure表示任何人都能訪問等接入認(rèn)證后可以替換為protectedProcedure。第二輸入校驗(yàn)全部交給 Zod 完成Zod 的類型推導(dǎo)能力讓我們不需要手寫接口的Input和Output類型。第三也是 tRPC 的殺手锏你寫了這份 router 之后前端就能拿到完全對(duì)應(yīng)的類型推導(dǎo)拼錯(cuò)一個(gè)字段名都會(huì)在編譯期報(bào)警而不是等到運(yùn)行時(shí)給你一個(gè) 500 或者 400。list這個(gè) query 我選了按分類 slug 過濾的寫法而沒有直接傳分類 ID因?yàn)榍岸寺酚缮象w現(xiàn)的多是語義化的 slug比如/posts/tech。語義化標(biāo)識(shí)作為對(duì)外暴露的查詢條件內(nèi)部 ID 作為關(guān)聯(lián)約束這種區(qū)分在建模時(shí)是個(gè)重要的習(xí)慣。3.3 前端調(diào)用與服務(wù)端無縫銜接前端代碼需要考慮的反而更少這是好事。在服務(wù)端寫好了postRouter之后要在根 router 里掛載// src/server/api/root.ts export const appRouter createTRPCRouter({ post: postRouter, category: categoryRouter, });前端通過生成的 React hooks 調(diào)用import { api } from ~/trpc/react; export function PostList({ categorySlug }: { categorySlug?: string }) { const { data, isLoading, error } api.post.list.useQuery({ category: categorySlug, }); if (isLoading) return div加載中.../div; if (error) return div加載失敗{error.message}/div; return ( div classNamegrid gap-4 {data?.map((post) ( article key{post.id} classNamerounded-lg border p-4 h2 classNametext-xl font-semibold{post.title}/h2 p classNametext-sm text-gray-500{post.category.name}/p p classNamemt-2 line-clamp-3{post.content}/p /article ))} /div ); }注意data的類型它是Post { category: Category }[]是服務(wù)端返回結(jié)構(gòu)的精確映射。這就是 tRPC 最讓人踏實(shí)的地方前后端口徑不一致的問題從架構(gòu)層面被消滅了接口文檔、“手寫 DTO”這些概念都變成了歷史名詞。新寫一個(gè) mutation 也同樣簡(jiǎn)單調(diào)用api.post.create.useMutation()提交成功后刷新列表即可。這里我踩過一個(gè)坑mutation 之后需要手動(dòng)執(zhí)行utils.post.list.invalidate()來刷新緩存如果不做這步新建的數(shù)據(jù)不會(huì)立刻出現(xiàn)在列表里。這一點(diǎn)和 React Query 的失效機(jī)制一致寫業(yè)務(wù)代碼時(shí)很容易忘。3.4 頁面組裝與 Tailwind 樣式落地有了 API 能力頁面組裝就是純粹的 UI 工作。我用 Tailwind 構(gòu)建了一個(gè)簡(jiǎn)易的發(fā)布頁面表單字段包括標(biāo)題、正文、分類和發(fā)布開關(guān)。表單提交部分的代碼const createPost api.post.create.useMutation({ onSuccess: () { utils.post.list.invalidate(); router.push(/); }, }); function handleSubmit(e: React.FormEvent) { e.preventDefault(); const formData new FormData(e.currentTarget); createPost.mutate({ title: String(formData.get(title)), content: String(formData.get(content)), categoryId: String(formData.get(category)), }); }UI 上用 Tailwind 類控制間距和邊框整個(gè)開發(fā)過程不需要碰 CSS 文件。Tailwind 的daisyUI或shadcn/ui組件庫可以進(jìn)一步提速但我建議在學(xué)原理階段先手寫樣式這樣對(duì)布局和響應(yīng)式斷點(diǎn)會(huì)有更扎實(shí)的理解。4. 常見問題與排查技巧實(shí)錄4.1 Prisma 數(shù)據(jù)庫連接與遷移問題問題一DATABASE_URL未設(shè)置初始化后第一件必做的事是配置.env。腳手架會(huì)生成一個(gè).env模板但不會(huì)自動(dòng)填入值。直接用相對(duì)路徑配置 SQLiteDATABASE_URLfile:./db.sqlite如果不設(shè)置就運(yùn)行prisma migrate會(huì)直接報(bào)錯(cuò)提示環(huán)境變量缺失。這個(gè)問題很蠢但很多人遇到過包括我自己。問題二遷移歷史沖突本地開發(fā)時(shí)經(jīng)常要改 schema有時(shí)直接改了 schema 但沒有跑 migration下一次migrate dev時(shí)會(huì)提示 migration history 不一致。解決辦法是在非生產(chǎn)環(huán)境直接prisma migrate reset清庫重來但生產(chǎn)環(huán)境千萬別這么干。更穩(wěn)妥的方式是遵從migrate dev --create-only先生成 SQL檢查無誤后再migrate dev執(zhí)行。4.2 tRPC 類型推導(dǎo)失效的排查問題一前端 api 對(duì)象找不到新加的 router我遇到過兩次這種情況。root router 里已經(jīng)掛載了新 router但前端始終無法識(shí)別。排查后發(fā)現(xiàn)是tsc的 watch 模式?jīng)]完全重啟或者 dev server 緩存了舊的類型聲明。解決方案是重啟 dev server如果重啟后問題依舊檢查src/trpc/react.tsx中引用的AppRouter類型是不是來自root.ts確實(shí)有同事直接 import 了錯(cuò)誤路徑的 router 類型。路徑寫錯(cuò)時(shí)前端類型肯定不對(duì)。問題二Zod 輸入類型收窄不理想tRPC 的輸入類型由 Zod schema 推導(dǎo)如果你用了.transform()或.refine()推導(dǎo)出的類型可能是精煉后的類型而不是原始輸入類型。這時(shí)候需要顯式聲明.input(z.object({ id: z.string() }).transform((val) ({ id: val.id })))這個(gè) transform 的輸出類型會(huì)被當(dāng)作 procedure 的輸入類型。理解這一點(diǎn)排查 Zod 相關(guān)類型問題會(huì)快很多。4.3 常見錯(cuò)誤速查表錯(cuò)誤現(xiàn)象可能原因處理方式PrismaClientInitializationError數(shù)據(jù)庫文件不存在或路徑錯(cuò)誤檢查.env的DATABASE_URL執(zhí)行prisma migrate devtRPC 調(diào)用返回 404router 未掛載到 root router檢查root.ts確認(rèn)已添加對(duì)應(yīng) router前端 TypeScript 報(bào)錯(cuò)Property does not existtRPC 類型未更新重啟 dev server刪除.next緩存構(gòu)建失敗Type errorZod 類型和實(shí)際返回類型不一致檢查 mutation/query 的返回值和模型字段是否對(duì)應(yīng)樣式不生效Tailwind 掃描路徑配置不全確認(rèn)tailwind.config.ts的 content 字符串包含./src/**/*.{ts,tsx}表單中文無法正常提交字符編碼問題確保頁面設(shè)置了 UTF-8且數(shù)據(jù)庫編碼正確SQLite 本身無此問題遷移到 MySQL/Postgres 時(shí)注意4.4 兩個(gè)值得復(fù)制的實(shí)戰(zhàn)習(xí)慣第一個(gè)習(xí)慣是寫 seed 數(shù)據(jù)。開發(fā)階段沒有數(shù)據(jù)列表頁永遠(yuǎn)是空的你很難判斷布局。我在prisma/seed.ts里寫了幾條示例數(shù)據(jù)然后加入 package.json 腳本prisma:seed: tsx prisma/seed.ts執(zhí)行pnpm prisma db seed即可填充基礎(chǔ)數(shù)據(jù)這比起手打樣本快得多。seed 腳本里我反復(fù)調(diào)用 upsert 保證冪等性重復(fù)執(zhí)行不會(huì)堆積重復(fù)數(shù)據(jù)。第二個(gè)習(xí)慣是給 tRPC procedure 加合理的錯(cuò)誤處理。默認(rèn)情況下Zod 校驗(yàn)失敗會(huì)拋異常前端收到一個(gè)籠統(tǒng)的Bad Request。更友好的做法是在 router 里用try/catch包裹業(yè)務(wù)邏輯并通過TRPCError拋出結(jié)構(gòu)化錯(cuò)誤碼import { TRPCError } from trpc/server; if (!category) { throw new TRPCError({ code: NOT_FOUND, message: 分類不存在, }); }這樣前端拿到錯(cuò)誤提示就能直接展示給用戶而不是看到一行技術(shù)文檔式的英文報(bào)錯(cuò)。5. 前后端交互的進(jìn)階優(yōu)化5.1 樂觀更新體驗(yàn)CRUD 功能跑通并不意味體驗(yàn)就合格。寫評(píng)論或編輯文章時(shí)如果每次都要等服務(wù)器返回后才刷新界面整個(gè)操作會(huì)顯得很遲鈍。tRPC 基于 React Query天然支持樂觀更新。以一個(gè)更新文章標(biāo)題的例子說明const updateTitle api.post.updateTitle.useMutation({ onMutate: async ({ id, title }) { // 取消正在進(jìn)行的查詢避免覆蓋樂觀更新 await utils.post.list.cancel(); // 讀取當(dāng)前緩存快照 const prev utils.post.list.getData(); // 直接修改緩存中的文章標(biāo)題 utils.post.list.setData(undefined, (old) old?.map((post) post.id id ? { ...post, title } : post) ); return { prev }; }, onError: (err, _vars, context) { // 回滾原來的標(biāo)題 utils.post.list.setData(undefined, context?.prev); }, onSettled: () { // 最終重新拉取服務(wù)器數(shù)據(jù)保證一致 utils.post.list.invalidate(); }, });這個(gè)模式的核心價(jià)值在于響應(yīng)是即時(shí)的無論網(wǎng)絡(luò)多慢界面都先給用戶反饋。連帶思路要提的是不適合樂觀更新的場(chǎng)景是寫操作依賴服務(wù)端計(jì)算結(jié)果的邏輯比如金額計(jì)算這種就別樂觀更新了老老實(shí)實(shí)等真實(shí)返回。5.2 服務(wù)端查詢與數(shù)據(jù)復(fù)用Next.js App Router 下 tRPC 的另一個(gè)好搭檔是 Server Components。你可以直接在服務(wù)端調(diào)用 tRPC procedureimport { api } from ~/trpc/server; async function Page({ params }: { params: { slug: string } }) { const posts await api.post.list.query({ category: params.slug }); return PostGrid posts{posts} /; }這種方式?jīng)]有額外的客戶端網(wǎng)絡(luò)請(qǐng)求頁面渲染性能更好同時(shí)類型依然是全鏈路安全的。實(shí)際項(xiàng)目中公開數(shù)據(jù)比如文章詳情可以用服務(wù)端查詢而需要交互的數(shù)據(jù)比如點(diǎn)贊、收藏則交給客戶端 hooks。兩條路徑和諧共存不會(huì)互相沖突。6. 部署上線與監(jiān)控補(bǔ)全6.1 SQLite 到生產(chǎn)數(shù)據(jù)庫的切換本地用 SQLite 太舒適等要部署到生產(chǎn)時(shí)必須慎重。SQLite 并發(fā)性能有限生產(chǎn)推薦切換到 Postgres。修改方法很簡(jiǎn)單.env里換成 Postgres 的連接串然后在 schema 文件把 provider 改成postgresql執(zhí)行prisma migrate deploy。這里有個(gè)關(guān)鍵點(diǎn)連接串不要寫在倉庫里放到部署平臺(tái)的環(huán)境變量中.env始終通過.env.example模板來約定字段。6.2 部署到 VercelT3 棧項(xiàng)目部署到 Vercel 是相當(dāng)順滑的。Vercel 會(huì)自動(dòng)識(shí)別 Next.js 項(xiàng)目你只需要在后臺(tái)配置好環(huán)境變量。有一個(gè)容易踩的坑Vercel 的構(gòu)建環(huán)境是只讀文件系統(tǒng)而 Prisma 在構(gòu)建時(shí)需要生成 client。我的做法是在 package.json 的 build 腳本里加上prisma generate確保構(gòu)建時(shí)生成正確類型的 client。另外構(gòu)建階段不需要執(zhí)行 migrate因?yàn)閿?shù)據(jù)庫遷移應(yīng)該在發(fā)布流程中單獨(dú)跑或者在 Vercel 的 Prebuild 命令里顯式運(yùn)行prisma migrate deploy二選一別重復(fù)執(zhí)行。6.3 日志、監(jiān)控與錯(cuò)誤收集上線之后不能當(dāng)瞎子。我個(gè)人推薦接一套監(jiān)控方案Sentry 負(fù)責(zé)前端與后端異常收集Logflare 或類似服務(wù)收集應(yīng)用日志。tRPC 的錯(cuò)誤會(huì)通過 JSON 返回前端Sentry 的 Next.js SDK 會(huì)自動(dòng)捕捉 unhandled rejection 和部分 fetch 錯(cuò)誤但要確保把 tRPCError 也傳播給 Sentry。加上按錯(cuò)誤碼和路徑分組的維度后線上問題定位會(huì)快很多。部署完成后再次加強(qiáng)環(huán)境NODE_ENVproduction、DATABASE_URL指向生產(chǎn)庫、NEXTAUTH_SECRET如果啟用認(rèn)證隨機(jī)生成。Vercel 里可以關(guān)閉自動(dòng)休眠以便內(nèi)部工具保持響應(yīng)但不用過度追求 Serverless 性能調(diào)優(yōu)先把服務(wù)跑穩(wěn)比什么都重要。7. 常見問題的最后一輪梳理再整理幾個(gè)我從t3code項(xiàng)目排障過程中總結(jié)出的高頻問題方便你做 checklist。依賴/環(huán)境類create-t3-app初始化時(shí) Node 版本過低提示需要 18升級(jí) Node 后解決。安裝后pnpm dev報(bào)Cannot find module把 node_modules 重裝一遍同時(shí)檢查 pnpm 版本。Tailwind class 不生效檢查tailwind.config.ts中的 content 是否覆蓋了src/**。Prisma 類prisma migrate dev報(bào)錯(cuò)Environment variable not found: DATABASE_URL原因和解決辦法上文已說。字段改了但前端類型沒變記得prisma generate并重啟 dev server。生產(chǎn)環(huán)境用 SQLite 導(dǎo)致并發(fā)寫入鎖 DB盡早切到 Postgres。tRPC 類新加 router 后前端api對(duì)象 404確認(rèn) root router 已掛載。前端報(bào)NOT_FOUND或UNAUTHORIZED確認(rèn) procedure 用的是publicProcedure還是protectedProcedure。輸入校驗(yàn)不通過返回 400利用 Zod 的.message()給中文提示提升聯(lián)調(diào)效率。開發(fā)體驗(yàn)類mutation 成功后 UI 沒更新調(diào)用invalidate刷新緩存。類型推導(dǎo)不出來的地方把鼠標(biāo)懸停在調(diào)用點(diǎn)看懂推導(dǎo)鏈路往往能定位問題。強(qiáng)烈建議用 ESLint 規(guī)則typescript-eslint/consistent-type-imports強(qiáng)制import type避免運(yùn)行時(shí) import 類型造成模塊加載問題。t3code做到這個(gè)階段已經(jīng)是一個(gè)非常完整的中小型全棧應(yīng)用了。它覆蓋了模型建模、API 實(shí)現(xiàn)、前端消費(fèi)、部署上線和問題監(jiān)控的全流程。個(gè)人體驗(yàn)下來T3 棧最大的爽感在于每次改動(dòng)字段后整個(gè)前后端圍繞字段的類型都跟著同步那種“編譯器幫我檢查一切”的安心感是傳統(tǒng) REST 開發(fā)完全給不了的。如果你正在規(guī)劃自己的下一個(gè)全棧小項(xiàng)目完全可以拿這個(gè)套路練手把認(rèn)證加進(jìn)去再補(bǔ)一個(gè)后臺(tái)管理系統(tǒng)就變成了一個(gè)能直接對(duì)外展示的作品。