做全棧開發(fā)這幾年我最大的痛點不是業(yè)務(wù)邏輯寫不出來而是前后端的數(shù)據(jù)類型就像兩個平行世界——后端定義了接口前端還得手動維護(hù)一份類型定義改一個字段名要跑兩個倉庫。T3 Stack 就是沖著這個痛點來的而 t3code 則是我在這個技術(shù)棧下長期積累的一套完整實踐總結(jié)從項目初始化、數(shù)據(jù)建模、路由編排到頁面落地全部圍繞“端到端類型安全”四個字展開。這套東西適合誰用如果你是剛接觸 Next.js 想做全棧項目、又被各種 ORM 和 API 方案糾結(jié)到失眠的開發(fā)者t3code 可以給你一條順暢的捷徑如果你是已經(jīng)寫過幾年接口的老手想見識下不用手寫 REST API 也能做前后端交互的思路這篇文章里同樣有值得一看的實操細(xì)節(jié)。我會把每一步選型背后的“為什么”也講清楚而不是只丟給你一串命令。1. 整體設(shè)計與思路拆解為什么是 T3 Stack 而不是傳統(tǒng)前后端分離1.1 T3 到底是什么先說清楚這個 T3 不是因為版本號而是 TypeScript、Tailwind、tRPC 三個單詞的縮寫組合。T3 Stack 的完整成員除了這三者通常還包括 Next.js、Prisma 和 NextAuth.js核心目標(biāo)是讓整個全棧項目從數(shù)據(jù)庫到瀏覽器 UI 全程都由 TypeScript 守住類型邊界。傳統(tǒng)做法是前端一個 React 項目、后端一個 Express 項目中間靠 REST API 溝通。這樣拆的代價是接口文檔必須同步、請求和響應(yīng)類型必須手工維護(hù)、部署環(huán)境至少要兩套。T3 Stack 的思路則是用 Next.js 同時承擔(dān)頁面渲染和 API 處理用 Prisma 把數(shù)據(jù)庫表結(jié)構(gòu)同步成 TypeScript 類型再用 tRPC 讓前端直接調(diào)用后端函數(shù)全程不需要生成 OpenAPI 文檔也不用在前后端各寫一份 interface。t3code 本質(zhì)上就是這個選型思路的工程化落地。我見過很多人對 T3 Stack 感興趣但實際搭項目時會在“App Router 還是 Pages Router”、“tRPC 能不能和 Server Action 混用”、“Prisma 到底要不要單獨抽象一層 service”這些問題上糾結(jié)結(jié)果項目搭到一半就泄氣了。1.2 類型安全能解決什么問題拿一個最簡單的“創(chuàng)建文章”功能舉例。傳統(tǒng) REST 流程里前端要記住 POST /api/post 這個地址還要保證傳參里用title還是name和后端代碼一致。一旦兩邊有一個字母拼錯運行時不報錯數(shù)據(jù)卻進(jìn)了數(shù)據(jù)庫錯誤列。這種 Bug 在開發(fā)環(huán)境往往很難第一時間暴露等到前端頁面加載不出來你才意識到類型錯了。T3 Stack 的處理方式完全不同。數(shù)據(jù)庫表用 Prisma Schema 定義生成出來的Post類型全項目通用tRPC 的createPost過程會從數(shù)據(jù)庫層一路推導(dǎo)到前端調(diào)用處如果你傳遞了錯誤字段保存代碼的那一刻 TypeScript 就會亮紅。也就是說接口契約不再是文檔而是直接寫死在類型系統(tǒng)里。t3code 把這類實踐都?xì)w納成了可復(fù)現(xiàn)的模式。我實操下來的體會是類型安全不是一次配置就完事它需要你在建表、寫路由、封裝組件時都遵循同一套約定否則強(qiáng)勢類型反而會變成一堆報錯的麻煩。2. 核心細(xì)節(jié)解析與實操要點2.1 項目初始化create-t3-app 的選項怎么選初始化 T3 項目現(xiàn)在很簡單一條命令搞定pnpm create t3-applatest如果你更喜歡 npm也可以執(zhí)行npm create t3-applatest交互內(nèi)容是一樣的。需要特別注意的是勾選項因為 create-t3-app 會把這幾個技術(shù)棧一次性裝好后面再補(bǔ)會比較麻煩。我一般這樣選擇Next.js 搭配 App Router新項目推薦直接用 App RouterPages Router 屬于老項目過渡場景。TypeScript 必選選框默認(rèn)選中。Tailwind CSS 建議選擇T3 的默認(rèn)樣式方案就是它。trpc 必選如果你跳過它整個 T3 Stack 最核心的端到端類型安全就不存在了。Prisma 建議選擇如果你更習(xí)慣 drizzle 可以手動換但 create-t3-app 內(nèi)置的是 Prisma。NextAuth.js 按需選擇需要登錄鑒權(quán)再勾不必提前引入。生成之后目錄結(jié)構(gòu)是這樣的├── prisma │ └── schema.prisma ├── public ├── src │ ├── app │ ├── pages │ ├── server │ │ ├── api │ │ │ └── root.ts │ │ ├── auth.ts │ │ └── db.ts │ ├── styles │ ├── trpc │ │ ├── react.tsx │ │ ├── query.ts │ │ └── server.ts ├── .env ├── next.config.js ├── package.json └── tsconfig.json這里我踩過一個小坑腳手架生成的src/server和src/trpc這兩個目錄是所有類型安全的根基盡量別擅自改名。特別是trpc/query.ts這個文件它是服務(wù)端路由類型與客戶端 Provider 連接的橋梁把它改動后編輯器里的智能提示會略顯混亂。2.2 Prisma 數(shù)據(jù)建模的核心要點T3 Stack 默認(rèn)使用 Prisma數(shù)據(jù)模型寫在prisma/schema.prisma里。一個最簡單的文章模型長這樣model Post { id String id default(cuid()) title String content String published Boolean default(false) createdAt DateTime default(now()) updatedAt DateTime updatedAt }這里需要注意三個細(xì)節(jié)。第一主鍵用default(cuid())而不是autoincrement()。T3 項目通常部署到 Serverless 環(huán)境自增主鍵在分布式場景下需要額外考慮沖突和協(xié)調(diào)成本而 cuid 生成字符串主鍵幾乎不需要額外配置生成之后也不需要等待主鍵回讀。第二每次修改schema.prisma后一定要執(zhí)行遷移命令pnpm prisma migrate dev這個命令會同時做兩件事生成 SQL 遷移文件并且重新生成 Prisma Client 類型。如果你只改表結(jié)構(gòu)而不重新生成 Client前端那邊引用Post類型時會出現(xiàn)類型過期、字段缺失的詭異現(xiàn)象。第三記得給PrismaClient做單例封裝。Next.js 在開發(fā)環(huán)境的熱更新機(jī)制下如果你的代碼直接new PrismaClient()每改一次代碼就會創(chuàng)建一個新的數(shù)據(jù)庫連接實例連接數(shù)一多數(shù)據(jù)庫就會被拖垮。create-t3-app 生成的src/server/db.ts已經(jīng)處理了這個問題你在自己寫腳本時也要注意。2.3 tRPC 路由設(shè)計模式tRPC 是 T3 Stack 的靈魂。它讓你在函數(shù)級別調(diào)用后端邏輯不需要寫 URL不需要手動處理 JSON更不需要定義 REST 資源。一個最簡單的 tRPC 子路由通常寫作import { createTRPCRouter, publicProcedure } from ~/server/api/trpc; import { z } from zod; export const postRouter createTRPCRouter({ list: publicProcedure .query(async ({ ctx }) { return ctx.db.post.findMany(); }), create: publicProcedure .input(z.object({ title: z.string().min(1), content: z.string(), })) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, }, }); }), });publicProcedure表示公開可調(diào)用不需要登錄。有鑒權(quán)需求時用protectedProcedure它會自動注入當(dāng)前會話用戶信息。input部分使用 zod 做運行時校驗服務(wù)端校驗和類型推導(dǎo)一起完成前端調(diào)用時也會獲得同樣精確的類型提示。我的建議是把 router 文件按業(yè)務(wù)模塊拆分比如postRouter、userRouter、commentRouter然后在root.ts里合并export const appRouter createTRPCRouter({ post: postRouter, user: userRouter, comment: commentRouter, });不要在單個 router 文件里塞幾十個 procedure那會讓調(diào)試體驗極其痛苦。2.4 前端調(diào)用的兩種姿勢T3 項目里調(diào)用 tRPC 有兩種常見方式。Client Component 的方式是通過api對象use client; import { api } from ~/trpc/react; export function PostList() { const { data, isLoading } api.post.list.useQuery(); if (isLoading) return div加載中.../div; return ( div {data?.map((post) ( div key{post.id}{post.title}/div ))} /div ); }Server Component 的方式則是直接調(diào)用服務(wù)端函數(shù)比如在 App Router 的page.tsx里import { api } from ~/trpc/server; export default async function HomePage() { const posts await api.post.list(); return div{posts.length} 篇文章/div; }這兩種方式的核心區(qū)別在于api.post.list.useQuery會經(jīng)過客戶端查詢緩存適合需要響應(yīng)式更新的場景await api.post.list()則在服務(wù)端直接執(zhí)行適合數(shù)據(jù)不需要交互變化的場景。t3code 的準(zhǔn)則是能用 Server Component 取數(shù)就先在服務(wù)端取只有在需要加載態(tài)、緩存更新時才切換到客戶端查詢。3. 實操過程與核心環(huán)節(jié)實現(xiàn)3.1 從零做一個帶數(shù)據(jù)庫的全棧功能為了把 t3code 的完整流程走一遍我準(zhǔn)備做一個“文章發(fā)布器”的簡單需求支持文章列表展示、支持輸入標(biāo)題和內(nèi)容創(chuàng)建文章。麻雀雖小但數(shù)據(jù)庫、后端邏輯、前端交互全都覆蓋到了。第一步定義 Prisma 模型。在schema.prisma中準(zhǔn)備一個Post模型model Post { id String id default(cuid()) title String content String createdAt DateTime default(now()) updatedAt DateTime updatedAt }執(zhí)行遷移pnpm prisma migrate dev --name init_post這一步會創(chuàng)建數(shù)據(jù)庫表并同步生成PrismaClient類型。開發(fā)環(huán)境我一般用本地 SQLite 文件因為不需要單獨啟動數(shù)據(jù)庫服務(wù)。部署到線上時會切換到 PostgreSQL只需要改環(huán)境變量并重新遷移即可。3.2 編寫 tRPC API在src/server/api/routers/post.ts中寫路由import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ~/server/api/trpc; export const postRouter createTRPCRouter({ list: publicProcedure.query(({ ctx }) { return ctx.db.post.findMany({ orderBy: { createdAt: desc }, }); }), create: protectedProcedure .input( z.object({ title: z.string().min(1).max(100), content: z.string().min(1), }) ) .mutation(({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, }, }); }), });list用了publicProcedure因為列表誰都能看。create用protectedProcedure因為只有登錄用戶能發(fā)文。如果項目沒有啟用 NextAuth那你只能先用publicProcedure頂替但真正上線前要換回來。3.3 服務(wù)端數(shù)據(jù)綁定App Router 模式下page.tsx默認(rèn)是 Server Component可以直接調(diào)用 tRPC Server APIimport { api } from ~/trpc/server; import { CreatePost} from ./_components/create-post; import { PostList } from ./_components/post-list; export default async function Home() { const posts await api.post.list(); return ( main classNamemx-auto max-w-2xl p-4 h1 classNametext-2xl font-bold文章發(fā)布器/h1 CreatePost / PostList initialPosts{posts} / /main ); }這里我把PostList設(shè)計成客戶端組件但把服務(wù)端取到的posts作為初始數(shù)據(jù)傳進(jìn)去這樣頁面首屏直接就有內(nèi)容客戶端 hydrate 后又能使用查詢緩存刷新數(shù)據(jù)。是不是有點冗余對但這是新手最容易忽略的優(yōu)化點不要一上來就在客戶端組件里useQuery拉接口導(dǎo)致頁面先空白再加載。PostList組件的實現(xiàn)use client; import { api } from ~/trpc/react; type Post { id: string; title: string; content: string; createdAt: Date; }; export function PostList({ initialPosts }: { initialPosts: Post[] }) { const { data initialPosts } api.post.list.useQuery(undefined, { initialData: initialPosts, }); return ( div classNamemt-6 space-y-4 {data.map((post) ( article key{post.id} classNamerounded border p-4 h2 classNametext-lg font-semibold{post.title}/h2 p{post.content}/p /article ))} /div ); }注意這段代碼里的類型Post是我手寫的其實不太符合 t3code 的風(fēng)格。更優(yōu)雅的做法是直接從 Prisma 導(dǎo)入比如import type { Post } from prisma/client真正實現(xiàn)類型單一事實來源。3.4 表單提交與緩存刷新創(chuàng)建表單同樣是客戶端組件use client; import { useRouter } from next/navigation; import { api } from ~/trpc/react; import { useState } from react; export function CreatePost() { const router useRouter(); const [title, setTitle] useState(); const [content, setContent] useState(); const createPost api.post.create.useMutation({ onSuccess: () { router.refresh(); setTitle(); setContent(); }, }); return ( form onSubmit{(e) { e.preventDefault(); createPost.mutate({ title, content }); }} input value{title} onChange{(e) setTitle(e.target.value)} placeholder標(biāo)題 classNamew-full border p-2 / textarea value{content} onChange{(e) setContent(e.target.value)} placeholder正文 classNamemt-2 w-full border p-2 / button classNamemt-2 bg-blue-600 p-2 text-white {createPost.isLoading ? 發(fā)布中... : 發(fā)布} /button {createPost.isError ( p classNametext-red-500發(fā)布失敗請檢查輸入/p )} /form ); }這里的關(guān)鍵點是router.refresh()。因為列表數(shù)據(jù)的獲取在 Server Component 里單純靠客戶端useMutation的onSuccess不會自動更新服務(wù)端渲染的列表。調(diào)用router.refresh()會重新從服務(wù)端拉取當(dāng)前路由的數(shù)據(jù)這樣一來新發(fā)布的文章才能立刻出現(xiàn)在列表里。3.5 完整功能驗證步驟寫完代碼后我建議按下列順序做一次完整驗證啟動開發(fā)服務(wù)器pnpm dev打開首頁確認(rèn)能看到空狀態(tài)列表提交一篇文章觀察表單重置、列表新增文章手動改一下數(shù)據(jù)庫里某條數(shù)據(jù)的title刷新頁面確保列表與數(shù)據(jù)庫一致這個流程雖然簡單但它能驗證數(shù)據(jù)庫、tRPC 后端、Server Component 取數(shù)、Client Mutation 更新四條鏈路都是通的。我見過太多項目在初期跳過端到端驗證結(jié)果部署時才暴露問題。4. 常見問題與排查技巧實錄4.1 常見錯誤速查表現(xiàn)象可能原因排查方向TypeScript 報錯Object literal may only specify known properties傳的參數(shù)和 zod input 類型不匹配檢查 zod schema 字段名和前端調(diào)用字段名列表一直顯示舊數(shù)據(jù)Router 緩存未失效在 mutation 的onSuccess里補(bǔ)router.refresh()請求返回 401tRPC procedure 用了protectedProcedure但未登錄先檢查 NextAuth 會話狀態(tài)部署后 Prisma 找不到數(shù)據(jù)表線上數(shù)據(jù)庫未執(zhí)行遷移執(zhí)行prisma migrate deployTailwind 樣式不生效內(nèi)容路徑不在 Tailwind content 配置里檢查tailwind.config.ts的content是否覆蓋到該目錄開發(fā)時每次刷新都新建數(shù)據(jù)庫連接PrismaClient 未做單例看看src/server/db.ts是否用全局變量緩存4.2 Router 刷新失效的深坑我在 t3code 實踐中遇到最多的坑就是使用 tRPC mutation 后調(diào)用router.refresh()但頁面數(shù)據(jù)看起來沒變。排查了很久發(fā)現(xiàn)根因是 Server Component 里的await api.post.list()和客戶端組件里的useQuery同時存在?？蛻舳藆seQuery的緩存優(yōu)先級高于服務(wù)端刷新結(jié)果所以即使 server 刷新重新渲染了頁面客戶端拿到的新數(shù)據(jù)又被舊緩存頂?shù)袅?。解決方案有兩種第一種列表只用服務(wù)端渲染客戶端只做表單提交router.refresh()就能穩(wěn)定生效。第二種列表必須用客戶端useQuery和緩存表單提交后調(diào)用api.post.list.invalidate()主動讓緩存失效。不要混用兩種策略這是我踩過幾次坑后的深刻教訓(xùn)。一個頁面只選擇一種數(shù)據(jù)獲取模式理解起來也輕松。4.3 調(diào)試 tRPC 時的小技巧tRPC 是類型安全體系的核心但也意味著一旦類型對不上錯誤信息會比較難定位。我的調(diào)試順序是先看瀏覽器 Network 面板。tRPC 的請求是一個 POST路徑類似/api/trpc/post.create返回 JSON 里會帶錯誤信息。再看服務(wù)端控制臺。如果 zod 校驗失敗服務(wù)端會輸出更詳細(xì)的堆棧信息。最后看類型。如果 TS 報錯說某個 property 不存在大概率是 Prisma Schema 改了但沒重新生成 Client。還有一個小技巧在 tRPC 的 error 回調(diào)里臨時輸出整個錯誤對象而不是直接輸出error.message因為 tRPC 的TRPCClientError有時會帶shape字段直接看 message 可能會遺漏關(guān)鍵信息。4.4 數(shù)據(jù)庫遷移的三個階段開發(fā)環(huán)境我用prisma migrate dev它會重置本地數(shù)據(jù)庫。這個命令在開發(fā)期很舒服但線上不能這么用線上要用prisma migrate deploy。我見過有人把migrate dev用于生產(chǎn)數(shù)據(jù)庫結(jié)果直接把線上數(shù)據(jù)清空或者表結(jié)構(gòu)重做這個教訓(xùn)很深刻。區(qū)分一下prisma migrate dev開發(fā)環(huán)境專用會執(zhí)行遷移、重新生成 Client、可能 reset 數(shù)據(jù)庫。prisma migrate deploy一般用于 CI/CD 或線上部署只應(yīng)用遷移文件不會重置數(shù)據(jù)。T3 項目部署到 Vercel 時我會在構(gòu)建命令里加上prisma generate prisma migrate deploy。不過也要注意Postgres 數(shù)據(jù)庫需要確保遷移服務(wù)能訪問到線上庫像 Vercel 這種 Serverless 平臺跑migrate deploy有時會有網(wǎng)絡(luò)限制建議在本地執(zhí)行遷移后再推代碼。4.5 依賴版本陷阱T3 Stack 的生態(tài)更新速度很快尤其要注意 Next.js 和 tRPC 的版本兼容。create-t3-app 腳手架生成的版本通常是最新組合但如果你手動升級某個包比如把 Next.js 從 14 升到 15tRPC 可能需要跟著調(diào)整 import 路徑。我的建議是生產(chǎn)項目盡量鎖定版本不要隔三岔五無腦升級。如果你想體驗新功能單獨開分支試別在主線項目上升級依賴省得類型系統(tǒng)突然炸一片。5. 代碼組織與項目擴(kuò)展建議5.1 server 與 client 的代碼邊界t3code 里最重要的一條組織原則是能放服務(wù)端的代碼不要放客戶端。具體來說數(shù)據(jù)庫操作只出現(xiàn)在src/server或 router 的 procedure 內(nèi)部與數(shù)據(jù)庫直接相關(guān)的類型不要在前端冗余定義調(diào)用 tRPC 獲取數(shù)據(jù)時優(yōu)先考慮 Server Component 直接取數(shù)只有需要交互、狀態(tài)、動畫、實時更新時才移動客戶端這樣設(shè)計之后整個項目的邏輯主線會變得非常清晰data flow 從數(shù)據(jù)庫到服務(wù)端路由再到頁面組件每個環(huán)節(jié)都經(jīng)過類型校驗不會再出現(xiàn)“前端 mock 數(shù)據(jù)跑得通聯(lián)調(diào)后端就崩”的情況。5.2 如何擴(kuò)展新業(yè)務(wù)模塊模塊一多路由文件會變多這時候項目容易亂。建議按業(yè)務(wù)域建目錄比如src/server/api/routers/ ├── auth.ts ├── post.ts ├── user.ts └── comment.ts在root.ts里統(tǒng)一聚合。每個 router 內(nèi)部可以重復(fù)使用publicProcedure或protectedProcedure如果需要鑒權(quán)變體可以單獨封裝一個帶特定中間件的 procedure而不是在每個業(yè)務(wù)路由里重復(fù)寫邏輯。5.3 部署前要檢查的清單部署 T3 項目前我會例行檢查下面幾項.env文件的數(shù)據(jù)庫地址、認(rèn)證密鑰是否正確Prisma schema 是否已經(jīng)同步到線上數(shù)據(jù)庫next build能不能通過類型檢查是否啟用了 NextAuth 的 NEXTAUTH_URL有沒有把DATABASE_URL誤提交到 Git 倉庫這里有個很容易踩的坑prisma generate生成的 Client 不一定會提交到倉庫線上構(gòu)建時如果沒執(zhí)行 generate就會報找不到 Prisma Client。建議在構(gòu)建命令里加上prisma generate或者把生成命令放到postinstall腳本。5.4 與其他全棧方案的橫向?qū)Ρ扔?t3code 的方法論和別的方案對比Next.js REST API需要手動維護(hù)類型和接口文檔適合多端共用 API 的項目。T3 更適合同構(gòu)全棧、快速迭代的單體項目。Next.js GraphQLGraphQL 靈活但迭代成本高需要 resolver、schema、generator 一堆配置。tRPC 在這些方面更輕量因為它不需要額外的 schema 語言直接用 TypeScript 類型。Next.js Server ActionsServer Action 很新處理表單提交很方便但復(fù)雜的查詢、權(quán)限校驗、復(fù)用還偏年輕。tRPC 生態(tài)更成熟而且和 React Query 搭配緩存和狀態(tài)管理更順手。這并不意味著 T3 一定最好只是它更適合整天和 TypeScript 打交道、不想在接口溝通上消耗太多精力的開發(fā)者。如果你團(tuán)隊里有純前端、純后端分工明確的人REST 可能更合適。個人體會是T3 Stack 最舒服的地方不在于某個單一庫而在于它把整個鏈路擰成一股繩。t3code 的核心也不是復(fù)制粘貼代碼而是理解那種“每個數(shù)據(jù)變動都帶著類型”的開發(fā)節(jié)奏。最后再分享一個小技巧當(dāng)你新建一個業(yè)務(wù)模塊時按“先改 Schema、再寫 router、最后接頁面”的順序推進(jìn)你會發(fā)現(xiàn)類型系統(tǒng)會幫你找出絕大多數(shù)遺漏的字段這種被編譯器提醒的感覺比任何測試都踏實。