先說說 t3code 是什么。它不是一個框架也不是某個大廠的開源項目而是我最近集中精力打磨的一套全棧工程樣例以 Next.js TypeScript 為核心集成了 Tailwind CSS、Prisma、tRPC 等一套組合目標是把“從零到能穩(wěn)定上線”的全過程固化下來讓新項目不用總是重復踩坑。這套組合有一個社區(qū)里的普遍叫法T3 Stack。T3 這個概念最早來自對“TypeScript-first 全棧開發(fā)”的總結核心是相信扁平的端到端類型安全能減少大量無效溝通和低級錯誤。我之所以給項目起名叫 t3code就是想把它當作一套可以不斷復用的代碼底座既能承載真實業(yè)務也可以作為團隊內部腳手架甚至拿來對新人做全棧入門教學。下面這篇文章會把整個項目的設計思路、目錄結構、數(shù)據(jù)模型、API 層、前端交互、測試部署和我在實際開發(fā)中踩過的坑完整講一遍。適合有一定 React 基礎、但對全棧工程化還比較陌生的讀者也適合想優(yōu)化技術棧選型的團隊參考。1. 先把項目拆開t3code 的核心目標與工程邊界1.1 這一套組合解決了什么問題前端項目發(fā)展到今天困擾大家的往往不是“會不會寫組件”而是幾個老生常談的痛點前后端接口文檔對不上、類型不一致、配置分散、部署鏈路太長、新人接手成本高。t3code 選擇 T3 Stack 的原因就在于此。Next.js 負責頁面、路由和服務端渲染框架本身已經(jīng)吸收了大量 Web 性能最佳實踐TypeScript 嚴格模式保證代碼在編譯階段就把大部分類型問題暴露出來不需要等運行時報錯Tailwind CSS 把樣式從“命名地獄”里解放出來改排版再也不用擔心牽一發(fā)動全身Prisma 提供數(shù)據(jù)庫建模、遷移和類型安全的客戶端tRPC 讓前后端 API 像調用本地函數(shù)一樣自然類型直接從服務端傳到客戶端。這一套組合真正解決的核心問題是“認知負載”。你不需要同時維護 REST API 文檔、手寫類型定義、各種代碼生成腳本只需要依賴 TypeScript 編譯器和框架本身的約定就能讓全鏈路保持類型安全。1.2 能力邊界與技術展望t3code 并不想把所有業(yè)務都塞進一套模板里。我在設計的時候明確劃了一條邊界它負責提供一個成熟的起點而不是一個大而全的應用框架。換句話說它默認幫你把路由、樣式、數(shù)據(jù)庫、鑒權、部署這些基礎能力搭好但具體業(yè)務邏輯需要你按自己的領域去填。比如如果你想做一個博客系統(tǒng)可以直接在 Prisma 里加 Post 模型如果你想做一個小型 SaaS可以在 tRPC router 里定義自己的計費接口。這套底座還有一個隱藏優(yōu)勢因為所有模塊都保持解耦后續(xù)把某個部分替換成別的方案也不傷筋動骨。比如你不想用 Prisma完全可以換成 Drizzle 或 TypeORM只要 tRPC 路由對外暴露的輸入輸出不變前端代碼幾乎零改動。1.3 適用人群這個項目特別適合三類人獨立開發(fā)者想在短時間內把一個想法做成可演示的 MVP不需要從零搭配置前端團隊想統(tǒng)一全棧開發(fā)規(guī)范降低協(xié)作成本特別是成員對 Node.js 后端不太熟悉時教學場景用 t3code 作為實訓資料讓學生在真實工程里理解 TypeScript、數(shù)據(jù)庫、服務端渲染之間的關系。如果你已經(jīng)有兩年以上的 React/Node 經(jīng)驗這套代碼讀起來基本沒有門檻如果你剛接觸全棧建議先把 React 基礎過一遍再動手改樣式和數(shù)據(jù)模型。我自己帶過幾個實習生他們第一次看 t3code 的代碼時最大的障礙反而不是語法而是“服務端和客戶端到底怎么區(qū)分”。這一點在交流里我更傾向用最直白的方式解釋src/server 下面的代碼不會進瀏覽器src/app 下面的代碼才是頁面入口剩下的事交給框架約定。2. 從零搭起 t3code工具鏈與工程化2.1 初始化工具鏈不該省的一步我習慣用 pnpm 管理依賴。相比 npm/yarnpnpm 對磁盤空間更友好依賴安裝速度也更快更重要的是它默認做了更嚴格的依賴隔離不容易出現(xiàn)“本地能跑、打包就掛”的問題。初始化 t3code 的時候可以直接用 create-t3-app 命令行工具。執(zhí)行下面的命令pnpm create t3-applatest t3code交互終端會讓你選擇需要哪些模塊我勾選的是Next.jsTypeScriptTailwind CSSPrismatRPCNextAuth.js鑒權項目生成后先進入目錄安裝依賴cd t3code pnpm install這里有一個容易被忽略的細節(jié)create-t3-app 默認會幫你搭好 .env、代碼規(guī)范、tsconfig但不會自動創(chuàng)建數(shù)據(jù)庫。所以在真正啟動開發(fā)服務前你需要先把數(shù)據(jù)庫連接串和認證配置填好。我記得第一次跑的時候漏掉了環(huán)境變量結果 tRPC 路由全部報錯白排查了好幾個小時。還有一個小提醒生成器默認可能在根目錄創(chuàng)建 .env 和 .env.example你可以立即把 .env.example 補全為一份“無敏感信息的模板”。我后來在團隊協(xié)作中受益很大因為新人 clone 下來之后對著 example 文件就能快速知道要配哪些變量不用反復來問。2.2 TS 嚴格性與項目結構t3code 的 TypeScript 配置走的是“嚴格到底”的路線。說實話剛開始寫會覺得有點煩比如可空類型、未使用變量、隱式 any 都會被編譯器攔下來。但這種方式長期看非常劃算尤其是項目規(guī)模變大之后重構時不會出現(xiàn)“改了一個對象屬性十幾個頁面默默出錯”的場面。項目的核心目錄結構如下src/ app/ # Next.js App Router 路由與頁面 components/ # 可復用的 React 組件 lib/ # 全局工具、數(shù)據(jù)庫實例、認證配置 server/ # 服務端邏輯tRPC 路由、鑒權、上下文 styles/ # 全局樣式與 Tailwind 配置 prisma/ schema.prisma # 數(shù)據(jù)模型與數(shù)據(jù)庫配置這個結構并不復雜但它把服務端和客戶端邏輯分得很清楚不會出現(xiàn)業(yè)務代碼互相糾纏的情況。尤其是 tRPC 的實例、上下文、路由必須放在服務端一旦放錯位置很可能會把數(shù)據(jù)庫憑據(jù)泄漏到客戶端 bundle 里這個風險點需要重點記住。實際開發(fā)時我還會順手加一個 src/env 目錄用來集中解析環(huán)境變量。create-t3-app 默認會用 zod 對 env 做運行時校驗這看起來有點小題大做但如果你在團隊里見過“某個變量拼錯了導致線上全掛”的案例就會理解這種“一啟動就報錯”的設計有多友好。2.3 環(huán)境變量與配置管理環(huán)境變量方面我會在 .env 里維護幾類關鍵配置DATABASE_URLmysql://user:passwordlocalhost:3306/t3code NEXTAUTH_SECRETyour-secret NEXTAUTH_URLhttp://localhost:3000其中 DATABASE_URL 是 Prisma 連接數(shù)據(jù)庫的入口NEXTAUTH_SECRET 是 NextAuth 加密會話用的密鑰NEXTAUTH_URL 指定當前應用的地址。這三個是本地開發(fā)最基礎的三件套不要省略。注意生產(chǎn)環(huán)境不要使用本地數(shù)據(jù)庫地址也不要把真實密鑰提交到 Git 倉庫。我在團隊里一直強調.env 文件要進 .gitignore密鑰走專門的密鑰管理服務或部署平臺的 env 配置。順帶一提我在本地經(jīng)常用 docker 起一個 MySQL 實例來跑開發(fā)庫。這個方案最大的好處是環(huán)境一致不會因為每個人本機裝的數(shù)據(jù)庫版本不同而出現(xiàn)奇怪的兼容問題。用 docker compose 起個測試庫基本五分鐘搞定比手動安裝數(shù)據(jù)庫省心。3. 數(shù)據(jù)層與業(yè)務 API從 schema 到 tRPC 的完整鏈路3.1 Prisma 模型設計先想清楚關系t3code 的數(shù)據(jù)模型用 Prisma Schema 聲明。開發(fā)前最好先把“誰和誰有對應關系”想清楚否則后面遷移表結構會比較痛苦。以常見的內容型應用為例generator client { provider prisma-client-js } datasource db { provider mysql url env(DATABASE_URL) } model User { id String id default(cuid()) name String email String unique emailVerified DateTime? posts Post[] } model Post { id String id default(cuid()) title String content String published Boolean default(false) createdAt DateTime default(now()) updatedAt DateTime updatedAt authorId String author User relation(fields: [authorId], references: [id]) }這里有個很典型的例子User 和 Post 是一對多關系Post 通過 authorId 外鍵關聯(lián)到 User。我在實際開發(fā)中經(jīng)?？吹接腥税?createdBy 寫成字符串或者在服務端再手寫一遍關系邏輯這些都是不必要的重復。Prisma 會根據(jù) schema 自動生成帶關系類型的客戶端類型安全是天然的。改完 schema 后運行npx prisma migrate dev --name init這個命令會在數(shù)據(jù)庫里創(chuàng)建對應的表并把 migration 歷史記錄下來方便團隊其他成員同步結構和后續(xù)回滾。如果只是在本地快速驗證也可以先用 npx prisma db push但生產(chǎn)環(huán)境我仍然推薦走正式 migration。關于主鍵類型我默認使用字符串 cuid 而不是自增數(shù)字。原因是自增主鍵容易在數(shù)據(jù)合并、多環(huán)境同步時撞車cuid 則是全局唯一的。雖然字符串索引比數(shù)字略慢一點點但對絕大多數(shù)業(yè)務系統(tǒng)來說完全可接受換來的是更強的可遷移性。3.2 tRPC router 的設計接口即函數(shù)tRPC 的設計哲學是“接口即函數(shù)”。服務端定義一個 router客戶端引入類型后調用起來就像調用本地 Promise 函數(shù)一樣。一個最簡單的 tRPC 查詢可以這樣寫import { createTRPCRouter, protectedProcedure, publicProcedure } from ~/server/trpc; import { z } from zod; import { prisma } from ~/server/db; export const postRouter createTRPCRouter({ list: publicProcedure .input(z.object({ limit: z.number().min(1).max(100).default(10) })) .query(async ({ input }) { const posts await prisma.post.findMany({ take: input.limit, orderBy: { createdAt: desc }, }); return posts; }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1) })) .mutation(async ({ ctx, input }) { return prisma.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id, }, }); }), });這段代碼里publicProcedure 和 protectedProcedure 的區(qū)別就是鑒權。protectedProcedure 要求用戶必須先登錄未登錄時 tRPC 會拋出認證錯誤。對于內容創(chuàng)建這類寫操作我強烈建議只用 protectedProcedure不要為了省事把所有接口都設為 public。zod 的 input 校驗也值得多說兩句。很多人會以為它只是“省去 if 判斷”實際上它同時兼任類型定義和運行時校驗兩個職責。你定義了 z.string().min(1)那么客戶端傳入空字符串時tRPC 會在進入業(yè)務邏輯之前就拒絕請求而不是等數(shù)據(jù)庫報錯。這對接口健壯性的提升是立竿見影的。3.3 中間件與鑒權NextAuth 和 tRPC 的配合在 T3 Stack 里可以說是“官方推薦組合”。它的流程是NextAuth 負責登錄會話tRPC createContext 會讀取 session 信息然后注入到每個路由的 ctx 中。我一開始遇到的問題是把 session 類型定義寫得不夠嚴格導致客戶端拿到的 user 對象可能為 null。后來我加了類型斷言和中間件統(tǒng)一處理export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session?.user) { throw new TRPCError({ code: UNAUTHORIZED }); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }); });這個中間件看起來很簡單但它把“是否登錄”的判斷收斂到了一處。后面所有需要登錄的接口只要套一個 protectedProcedure就不需要再重復寫判斷邏輯也不會出現(xiàn)漏判。注意登錄態(tài)判斷永遠不要只依賴前端。即使你用了 tRPC前端路由可以寫各種守衛(wèi)但真正的數(shù)據(jù)訪問控制一定發(fā)生在服務端。這是安全底線。在 t3code 里我還加了一層資源歸屬校驗。比如用戶只能編輯自己創(chuàng)建的文章這個邏輯不能只靠 protectedProcedure還要在 procedure 內部判斷 resource.ownerId 是否等于 session.user.id。很多數(shù)據(jù)泄露事故本質上都是“能登錄就能看別人數(shù)據(jù)”導致的這一點要在業(yè)務路由里單獨加固。4. 前端體驗UI、狀態(tài)與交互細節(jié)4.1 Tailwind 渲染與設計系統(tǒng)t3code 的樣式層做得比較克制。Tailwind CSS 很適合“只寫該寫的樣式”不會像傳統(tǒng) CSS 那樣產(chǎn)生大量難以維護的類名堆疊。我會先在 tailwind.config.ts 里定義幾個 design token比如主色、圓角、陰影import type { Config } from tailwindcss; export default { content: [./src/**/*.{ts,tsx}], theme: { extend: { colors: { primary: #2563eb, accent: #f59e0b, }, borderRadius: { xl: 1rem, }, }, }, plugins: [], } satisfies Config;實際寫頁面的時候我通常不會把樣式復雜化。比如一個按鈕直接寫 classNamerounded-xl bg-primary px-4 py-2 text-white基本不用再額外寫 CSS 文件。這樣做的收益是新人接手時不需要翻樣式表看到 className 就能猜出大概樣式。我還習慣把重復出現(xiàn)的樣式抽成小組件。比如一個基礎按鈕 Button、一個卡片 Card把這些小組件統(tǒng)一放在 components/ui 下面。這樣既保留了 Tailwind 的靈活性又避免了同一段樣式在二十個頁面里反復復制后續(xù)想統(tǒng)一改圓角、改陰影時只需要動一個地方。4.2 客戶端數(shù)據(jù)流把服務端數(shù)據(jù)拉起來在 t3code 里客戶端調用服務端并不需要寫 fetch 和 URL 拼接。還記得剛才的 postRouter 嗎在 React 組件里可以直接這么用use client; import { api } from ~/utils/api; export default function PostList() { const { data: posts, isLoading } api.post.list.useQuery({ limit: 10 }); if (isLoading) return div加載中.../div; return ( ul {posts?.map((post) ( li key{post.id}{post.title}/li ))} /ul ); }這里的 api.post.list.useQuery 是類型安全的如果你在服務端把返回值改成別的字段客戶端這里立刻會編譯報錯。這種體驗在傳統(tǒng) REST API 開發(fā)里幾乎是不可能的也正因為我親身體驗過我才格外推薦 tRPC。寫操作時可以用 useMutation它會自動管理請求狀態(tài)和緩存失效const utils api.useUtils(); const createPost api.post.create.useMutation({ onSuccess: async () { await utils.post.list.invalidate(); }, });這里 invalidate 是 tRPC 提供的一個很實用的能力它會在創(chuàng)建成功后讓 post.list 自動重新拉取不用手動去改本地緩存。很多人第一次接觸時不太能理解為什么不用手動 setState 去更新列表其實這就是“服務端狀態(tài)”和“客戶端狀態(tài)”的區(qū)別。列表數(shù)據(jù)來自服務端最穩(wěn)妥的更新方式就是讓服務端重新給一份而不是在前端猜。4.3 性能兜底與加載體驗全棧應用很容易出現(xiàn)“數(shù)據(jù)太慢”的問題。t3code 做性能優(yōu)化時主要抓三個點頁面骨架屏用服務端渲染先出 HTML配合 loading 狀態(tài)展示骨架減少白屏焦慮數(shù)據(jù)復用對不常變更的數(shù)據(jù)使用 React Query 的 staleTime 配置避免每次都發(fā)請求按需加載組件層面用 Next.js 的 dynamic import路由拆包避免首屏 bundle 過大。一個典型的示例是在根頁面組件里設置 staleTimeconst { data } api.post.list.useQuery( { limit: 10 }, { staleTime: 30_000 } );這樣 30 秒內再次訪問React Query 不會重新發(fā)起網(wǎng)絡請求直接使用緩存。對訪問量的優(yōu)化非常明顯。這里還要提醒一句React Query 的 cache 默認是內存級的刷新頁面后一定會重新拉數(shù)據(jù)。如果你需要持久化緩存比如把用戶偏好設置存到 localStorage那就不能只依賴 React Query 默認行為得配合 persist 之類的方案。大多數(shù)場景下默認內存緩存已經(jīng)夠用了不需要過早優(yōu)化。5. 測試、部署與運維5.1 自動化測試的最小集很多人習慣手動點一遍頁面就當測試過了但項目到中后期會越來越脆弱。t3code 里我保留了一個最小可用的測試集單元測試主要覆蓋工具函數(shù)和 tRPC 路由的輸入校驗集成測試用 Vitest React Testing Library 渲染關鍵頁面數(shù)據(jù)庫測試在測試環(huán)境里跑內存數(shù)據(jù)庫或獨立的測試庫驗證數(shù)據(jù)模型。Vitest 配置非常輕直接在 vite.config 里加 test 字段就行它的 API 和 Jest 很接近遷移成本低。針對 tRPC 路由測試我一般直接調用 router.createCaller 來模擬客戶端請求比真正起一個 HTTP 服務器更省事。import { postRouter } from ~/server/api/routers/post; import { createCallerFactory } from ~/server/trpc; const caller createCallerFactory(postRouter); test(未登錄用戶不能創(chuàng)建文章, async () { await expect(caller.withContext({ session: null }).create({ title: hello, content: world, })).rejects.toThrow(/UNAUTHORIZED/); });這種測試方式非常貼近真實調用鏈因為 createCaller 會走完整的 zod 校驗和中間件邏輯。只要把 session 傳入不同的 mock 對象就能模擬登錄和未登錄兩種場景不用去 mock 數(shù)據(jù)庫也不用起服務器測試速度非?？?。5.2 部署與數(shù)據(jù)庫前端部分部署到 Vercel 是成本最低的選擇push 到 Git 倉庫后自動構建發(fā)布日常發(fā)布基本不需要手動干預。數(shù)據(jù)庫我一般選擇托管數(shù)據(jù)庫服務避免自己維護服務器和高可用開發(fā)效率優(yōu)先。部署前Build 命令需要提前在環(huán)境變量里配置好DATABASE_URL指向生產(chǎn)數(shù)據(jù)庫NEXTAUTH_URL生產(chǎn)環(huán)境域名NEXTAUTH_SECRET新的隨機密鑰。在 Vercel 上配置時不要直接復制本地 .env應該重新生成一套生產(chǎn)密鑰并限制數(shù)據(jù)庫白名單。很多安全事故其實不是代碼問題而是開發(fā)環(huán)境的密鑰直接被帶到了線上。有一個經(jīng)驗值得分享生產(chǎn)環(huán)境的 DATABASE_URL 要和本地隔離。如果本地和線上共用同一個數(shù)據(jù)庫開發(fā)時的誤操作很可能會污染生產(chǎn)數(shù)據(jù)尤其是跑 migrate reset 之類的命令時后果可能是毀滅性的。我自己的習慣是本地、預發(fā)布、生產(chǎn)各一套數(shù)據(jù)庫再怎么折騰都不影響線上。5.3 監(jiān)控與日志t3code 上線后重點觀察的數(shù)據(jù)有三類頁面錯誤率、接口延遲、數(shù)據(jù)庫連接數(shù)。如果項目還比較小可以先用框架自帶的 logging 和 Sentry 這類服務先頂起來等業(yè)務體量大了再引入更重的可觀測平臺。我的習慣是在 tRPC 路由的外層加一個簡單的錯誤捕獲中間件統(tǒng)一記錄請求路徑、錯誤碼、耗時export const loggingMiddleware t.middleware(async ({ path, type, next, ctx }) { const start Date.now(); try { const result await next(); console.log(${type} ${path} ${Date.now() - start}ms); return result; } catch (err) { console.error(${type} ${path} failed, err); throw err; } });中間件本身不復雜但能把所有接口的可觀測性兜住上線后排查問題會省不少力氣。有朋友問我為什么不用 Grafana / Prometheus 那套重型方案我的回答是看項目階段。如果你每天的請求量連一萬都不到堆一堆監(jiān)控系統(tǒng)反而成了維護負擔。先把 log 打全、把錯誤上報鏈路接好等業(yè)務真的需要再逐步加指標系統(tǒng)這才是更務實的選擇。6. 常見問題速查與個人心得6.1 高頻問題一次說清下面這個表格是我在 t3code 開發(fā)過程中反復遇到的幾個問題整理出來供大家對照排查癥狀常見原因排查思路tRPC 請求全部報 500DATABASE_URL 沒有配置或者數(shù)據(jù)庫沒啟動先確認 .env 加載再執(zhí)行 npx prisma db push 或 migrate登錄后 session 丟失NEXTAUTH_SECRET 不一致或 NEXTAUTH_URL 不對檢查部署環(huán)境和本地環(huán)境是否共用同一密鑰打包后樣式錯亂使用 Tailwind 時漏配置 content 路徑確認 tailwind.config.ts 包含 src 下的所有 tsx 文件表單校驗不生效zod schema 類型和組件 input 類型不一致統(tǒng)一用 z.infer 導出類型給前端用數(shù)據(jù)更新后頁面不刷新沒有調用 invalidate 或 refetch在 mutation onSuccess 里調用對應 query 的 invalidate還有一個容易被忽略的點是權限相關。很多“明明登錄了卻提示未登錄”的案例其實是因為 session 在客戶端和服務端的 secret 不一致。NextAuth 在做加密和簽名時會用到 NEXTAUTH_SECRET本地、Vercel、測試環(huán)境如果各用各的就會導致 token 互相解不開。這個坑我踩過不止一次所以現(xiàn)在我會在部署腳本里強制執(zhí)行一行檢查如果某個環(huán)境的 secret 和本地相同直接中斷部署并給出警告。6.2 我在實際開發(fā)中維護的小習慣最后分享幾點長期改動下來的習慣。第一t3code 的所有數(shù)據(jù)庫模型都盡量以業(yè)務語義命名不在 schema 里堆“技術晦澀”的字段。比如使用 createdAt、updatedAt、authorId而不要用 ctime、utime、owner_id。名字清楚遷移時也容易讀懂歷史記錄。第二每一次修改 Prisma schema 后都立即生成 migration而不是攢到最后一起遷移。中途發(fā)現(xiàn)問題時小的 migration 更好回滾和分析。第三不要在客戶端代碼里直接 import prisma也不要在組件里 import 任何 server-only 文件。t3code 的目錄劃分已經(jīng)把 server 目錄獨立出來這樣不僅能避免類型混亂也能防止把數(shù)據(jù)庫連接代碼打進客戶端 bundle。6.3 后續(xù)還能怎么擴展t3code 這套底座想擴展成其他產(chǎn)品形態(tài)并不難。想做成多用戶協(xié)作工具可以在 User 模型加一個 workspaceId再通過 tRPC 中間件做資源隔離想做內容社區(qū)可以加 Comment 模型和 Tag 模型想接 AI 能力可以在服務端路由里調模型接口再把結果通過 tRPC 返回前端。關鍵在于保持類型安全和分層意識新增功能時先修改 schema再定義路由最后寫界面不容易把系統(tǒng)寫亂。說回最初我起名 t3code 其實沒有太復雜的含義就是“T3 棧的代碼倉庫”的簡稱。但做完整套東西之后我最大的感受是全棧開發(fā)真正要對抗的不是學習難度而是散落各處的信息和不確定性。把不確定的類型、接口、配置都收攏到一處整個開發(fā)體驗就會好非常多。如果你正準備從零開始做一個全棧產(chǎn)品或者想把團隊的技術棧收斂一下建議照這個思路復現(xiàn)一遍 t3code你會少走很多彎路。