如果你最近在關(guān)注 TypeScript 全棧開發(fā)大概率繞不開t3code這個(gè)名字。它不是某個(gè)單一的開源庫(kù)也不是一款具體的云服務(wù)而是一整套以T3 Stack為核心的全棧代碼實(shí)踐方案用 Next.js 搭界面、用 tRPC 打通前后端、用 Prisma 管數(shù)據(jù)庫(kù)、用 Tailwind 寫樣式再加上 TypeScript 把所有環(huán)節(jié)的類型串成一條線。這篇文章我從實(shí)際開發(fā)角度拆解這套技術(shù)棧講清楚每個(gè)環(huán)節(jié)為什么這么選、具體怎么落地、遇到問(wèn)題怎么排查適合正在學(xué)習(xí)全棧開發(fā)、準(zhǔn)備從傳統(tǒng) REST API 轉(zhuǎn)向端到端類型安全的同學(xué)參考。1. 內(nèi)容整體設(shè)計(jì)與思路拆解1.1 t3code 的核心定位不是框架是一套組合拳先說(shuō)結(jié)論t3code這個(gè)代號(hào)背后代表的是一套已經(jīng)過(guò)了大規(guī)模驗(yàn)證的全棧應(yīng)用組織方式。它沒(méi)有發(fā)明多少新東西而是把 Next.js、TypeScript、Tailwind CSS、tRPC、Prisma 這些成熟工具按照類型安全優(yōu)先的原則組合在一起。很多人第一次聽到T3會(huì)以為是某個(gè)新框架實(shí)際上它是 The T3 Stack 的簡(jiǎn)稱核心原則很簡(jiǎn)單能編譯期解決的就不要留到運(yùn)行時(shí)。這套組合拳最讓我看重的點(diǎn)在于開發(fā)體驗(yàn)的連續(xù)性。以前我做一個(gè)全棧功能前端寫一遍接口類型定義后端又要維護(hù)一份兩邊經(jīng)常對(duì)不上聯(lián)調(diào)時(shí)大量時(shí)間浪費(fèi)在你返回的字段名拼錯(cuò)了這種低級(jí)問(wèn)題上。T3 技術(shù)棧把 API 層直接做成類型安全的 RPC 調(diào)用后端定義什么類型前端拿到的就是什么類型鼠標(biāo)懸停就能看到完整的返回結(jié)構(gòu)徹底告別接口文檔滯后的問(wèn)題。從項(xiàng)目管理的角度看t3code 這種模式天然適合中小型團(tuán)隊(duì)。你把數(shù)據(jù)庫(kù) schema、路由處理、頁(yè)面組件放在一個(gè)代碼庫(kù)里前后端同學(xué)可以并行開發(fā)同一個(gè)功能的不同層級(jí)又因?yàn)轭愋图s束很難出現(xiàn)前端等后端接口的阻塞狀態(tài)。這里涉及一個(gè)很重要的思考技術(shù)選型不是追新而是看它能不能把團(tuán)隊(duì)協(xié)作摩擦降到最低。1.2 為什么選擇 Next.js tRPC傳統(tǒng) REST API 的痛點(diǎn)傳統(tǒng)的前后端分離架構(gòu)里前端用 axios 請(qǐng)求 REST API你需要自己處理請(qǐng)求路徑、參數(shù)序列化、錯(cuò)誤碼判斷、響應(yīng)類型斷言。一套正常的中型系統(tǒng)光接口定義文檔就能寫幾百頁(yè)而且后端一改字段前端根本感知不到直到接口返回空值才反應(yīng)過(guò)來(lái)。Next.js 作為 React 框架其實(shí)解決的是渲染層面的問(wèn)題它本身并不管數(shù)據(jù)怎么流通。真正讓 t3code 變得好用的關(guān)鍵是 tRPC 這套遠(yuǎn)程調(diào)用方案。你可以把 tRPC 理解成給函數(shù)調(diào)用裝上網(wǎng)絡(luò)傳輸能力后端寫好一個(gè)函數(shù)procedure前端像調(diào)用本地函數(shù)一樣調(diào)用它。不需要手工拼接 URL不需要請(qǐng)求庫(kù)不需要 mock 數(shù)據(jù)類型是從數(shù)據(jù)庫(kù)一路傳遞到頁(yè)面組件的。小提示tRPC 不等于 GraphQL。GraphQL 的核心價(jià)值是客戶端按需選擇字段tRPC 的核心價(jià)值是端到端類型安全兩者解決的不是同一個(gè)問(wèn)題不要混為一談。也許有人會(huì)問(wèn)既然 RPC 這么好為什么不是所有項(xiàng)目都用它答案在于適用邊界。T3 技術(shù)棧適合前后端共享代碼庫(kù)的全棧應(yīng)用、MVP 產(chǎn)品、內(nèi)部工具但如果你需要流式傳輸、長(zhǎng)連接推送、對(duì)外開放給第三方開發(fā)者使用那還得靠更通用的 HTTP API 方案。選型永遠(yuǎn)是 trade-off沒(méi)有銀彈。1.3 技術(shù)棧全景每個(gè)成員各司其職我按照數(shù)據(jù)流的方向把這套技術(shù)棧的關(guān)鍵成員排列一下層級(jí)工具職責(zé)核心優(yōu)勢(shì)數(shù)據(jù)庫(kù)層Prisma SQLite/PostgreSQL數(shù)據(jù)建模與遷移Schema 即類型來(lái)源服務(wù)層tRPC Router業(yè)務(wù)邏輯與數(shù)據(jù)校驗(yàn)端到端類型自動(dòng)推導(dǎo)表現(xiàn)層Next.js TypeScript頁(yè)面渲染與路由SSR、RSC 靈活組合樣式層Tailwind CSS原子化樣式開發(fā)速度與一致性工程化create-t3-app腳手架初始化統(tǒng)一目錄與規(guī)范認(rèn)證可選NextAuth.js登錄與會(huì)話管理與 tRPC 無(wú)縫集成這份清單里我最想強(qiáng)調(diào)的是 Prisma 的角色。Prisma 通過(guò) schema.prisma 文件定義數(shù)據(jù)模型啟動(dòng)時(shí)生成 TypeScript 類型tRPC 的 query 返回結(jié)果直接帶上這些類型前端調(diào)用后自動(dòng)獲得類型推斷。整個(gè)鏈路里唯一需要人工維護(hù)的事實(shí)來(lái)源就是數(shù)據(jù)庫(kù) schema剩下的類型都是一層層自動(dòng)推導(dǎo)出來(lái)的。我用的類比是這就像一條流水線原料數(shù)據(jù)模型進(jìn)機(jī)器出來(lái)的都是包裝好的標(biāo)品帶類型的函數(shù)調(diào)用不需要中途再手動(dòng)貼標(biāo)簽。2. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)2.1 手寫 create-t3-app初始化項(xiàng)目到底發(fā)生了什么初始化一個(gè) t3code 項(xiàng)目你只需要跑一條命令npx create-t3-applatest my-t3-app執(zhí)行這條命令時(shí)腳手架會(huì)以交互模式詢問(wèn)你要啟用哪些模塊Next.js 配置、TypeScript 嚴(yán)格模式、Tailwind、Prisma、tRPC、NextAuth。我建議第一遍使用全部默認(rèn)選項(xiàng)讓腳手架把整個(gè)骨架搭起來(lái)后面再逐步改造。命令行終端會(huì)提示你選擇包管理器我一般用 pnpm原因不是快而是依賴鏈接方式更嚴(yán)格能提前暴露隱式依賴問(wèn)題。腳手架生成的項(xiàng)目結(jié)構(gòu)有幾個(gè)關(guān)鍵節(jié)點(diǎn)值得先說(shuō)清楚prisma/schema.prisma所有數(shù)據(jù)模型的唯一來(lái)源src/server/api/root.tstRPC 路由的根節(jié)點(diǎn)所有子路由都在這里匯聚src/server/api/routers/按業(yè)務(wù)域拆分的路由文件目錄src/trpc/server.ts服務(wù)端 tRPC 上下文創(chuàng)建邏輯src/trpc/react.tsx客戶端 tRPC Provider 封裝src/env.js環(huán)境變量校驗(yàn)文件用了 zod 做運(yùn)行時(shí)校驗(yàn)第一次看到這么多文件可能有點(diǎn)懵但我給你一個(gè)定心丸這個(gè)目錄命名和代碼組織方式不是腳手架隨機(jī)生成的而是社區(qū)反復(fù)迭代后的最佳實(shí)踐。你別急著重構(gòu)目錄結(jié)構(gòu)先用它跑通一條完整鏈路再根據(jù)業(yè)務(wù)規(guī)模決定要不要繼續(xù)拆分。2.2 TypeScript 嚴(yán)格模式的真實(shí)價(jià)值把錯(cuò)誤堵在編譯期T3 技術(shù)棧在初始化時(shí)默認(rèn)開啟strict: true還會(huì)配置路徑別名/指向src/。這些配置不是錦上添花而是整個(gè)類型安全體系的地基。如果你把 strict 關(guān)掉tRPC 的很多類型推斷會(huì)退化為any這套技術(shù)棧的優(yōu)勢(shì)直接歸零。我用一個(gè)生活中的類比解釋嚴(yán)格模式的價(jià)值你拿到一份外賣訂單紙面上寫著中辣如果接到訂單的人必須口頭確認(rèn)辣度級(jí)別就可能出現(xiàn)偏差但如果訂單系統(tǒng)從一開始就規(guī)定辣度字段只能是微辣/中辣/特辣三選一整個(gè)流程就不會(huì)有歧義。TypeScript 嚴(yán)格模式做的就是這件事把接口邊界、空值處理、類型斷言全部規(guī)范化讓整個(gè)系統(tǒng)從源頭減少歧義。實(shí)操中我會(huì)額外在tsconfig.json里開啟幾個(gè)衍生選項(xiàng){ compilerOptions: { noUncheckedIndexedAccess: true, exactOptionalPropertyTypes: true, noPropertyAccessFromIndexSignature: true } }noUncheckedIndexedAccess會(huì)強(qiáng)制你處理數(shù)組元素可能是 undefined 的情況這在實(shí)際開發(fā)中能抓到大量隱性 bug。剛開這些選項(xiàng)時(shí)項(xiàng)目里會(huì)冒出一大片紅色波浪線別慌那都是在提醒你之前哪里寫得不夠嚴(yán)謹(jǐn)逐個(gè)修復(fù)就好不用為了省事關(guān)掉它們。2.3 tRPC 的邊界設(shè)計(jì)query、mutate 與 protectedProceduretRPC 路由層是 t3code 最核心的部分。它把 API 定義為兩類函數(shù)query負(fù)責(zé)獲取數(shù)據(jù)mutation負(fù)責(zé)修改數(shù)據(jù)。這個(gè)概念很像 GraphQL 的 Query 和 Mutation 之分但實(shí)現(xiàn)方式輕量得多。先從最簡(jiǎn)單的例子直觀感受一下代碼形態(tài)。定義一個(gè)帖子列表接口// src/server/api/routers/post.ts import { z } from zod; import { createTRPCRouter, publicProcedure } from ~/trpc/server; export const postRouter createTRPCRouter({ list: publicProcedure .query(async ({ ctx }) { return ctx.db.post.findMany({ orderBy: { createdAt: desc }, take: 20, }); }), });前端調(diào)用時(shí)不需要任何 URL 拼接或請(qǐng)求配置const { data, isLoading } api.post.list.useQuery();data的類型就是Post[]自動(dòng)帶上了 Prisma 查詢結(jié)果的全部類型信息。這里請(qǐng)注意一個(gè)細(xì)節(jié)useQuery返回的data類型中包含了createdAt等數(shù)據(jù)庫(kù)字段如果你只想暴露部分字段需要在服務(wù)端查詢里用select顯式控制返回結(jié)構(gòu)而不是指望客戶端去過(guò)濾因?yàn)?tRPC 的類型安全是編譯期的不是運(yùn)行時(shí)約束。對(duì)于需要登錄才能訪問(wèn)的接口T3 技術(shù)棧提供了protectedProcedure封裝。它的思路是在 tRPC 上下文里先拿到 session如果用戶未登錄直接拋出錯(cuò)誤后續(xù)所有路由都不需要再關(guān)注鑒權(quán)邏輯。2.4 Tailwind CSS 在真實(shí)項(xiàng)目中的組織方式Tailwind CSS 在 T3 技術(shù)棧里是默認(rèn)樣式方案但它不是唯一選擇。很多人對(duì)原子化 CSS 有偏見覺(jué)得它會(huì)讓 HTML 類名變得又臭又長(zhǎng)。我的看法是在 t3code 這種快速迭代的全棧項(xiàng)目里Tailwind 的收益遠(yuǎn)大于代價(jià)。我推薦一個(gè)組件級(jí)樣式組織策略把經(jīng)常重復(fù)的 UI 模式封裝成 React 組件組件內(nèi)部使用 Tailwind 類名對(duì)外暴露簡(jiǎn)潔的 props。比如一個(gè) Card 組件// src/components/ui/card.tsx import { cn } from ~/lib/utils; export function Card({ className, children }: { className?: string; children: React.ReactNode }) { return ( div className{cn(rounded-2xl border border-gray-200 bg-white p-6 shadow-sm, className)} {children} /div ); }這樣外部使用者只需要Card classNamemt-4不用關(guān)心內(nèi)部是一坨什么類名。把可變的產(chǎn)物留給組件內(nèi)部把業(yè)務(wù)頁(yè)面的差異化通過(guò)className傳進(jìn)來(lái)這是我實(shí)測(cè)最平衡且好維護(hù)的方案。如果團(tuán)隊(duì)打算在 t3code 基礎(chǔ)上構(gòu)建一個(gè)中大型應(yīng)用我會(huì)建議引入 shadcn/ui 那一套組件工廠模式但項(xiàng)目的初版階段自己封裝幾個(gè)基礎(chǔ)組件就夠了。3. 實(shí)操過(guò)程與核心環(huán)節(jié)實(shí)現(xiàn)3.1 從零到一用 t3code 搭一個(gè)可復(fù)現(xiàn)的記賬本應(yīng)用紙上談兵沒(méi)有意思我實(shí)際帶大家走一遍完整流程以一個(gè)記賬本應(yīng)用為例。這個(gè)例子包含列表展示、金額記錄、分類篩選能覆蓋 tRPC 最常見的用法。創(chuàng)建項(xiàng)目時(shí)我們?cè)诮换ミx項(xiàng)里選擇 Prisma、tRPC、NextAuth先用郵箱登錄占位數(shù)據(jù)庫(kù)先選 SQLite 降低啟動(dòng)成本后面部署再換 PostgreSQL。這里多說(shuō)一句SQLite 與 PostgreSQL 在 Prisma schema 語(yǔ)法層面幾乎一致只是 provider 字段不同所以前期用 SQLite 做本地開發(fā)完全沒(méi)有問(wèn)題。初始化完成后第一步修改數(shù)據(jù)模型// prisma/schema.prisma generator client { provider prisma-client-js } datasource db { provider sqlite url env(DATABASE_URL) } model Transaction { id String id default(cuid()) amount Float category String note String? createdAt DateTime default(now()) index([category]) }改完 schema 后執(zhí)行npx prisma migrate dev --name init。這條命令會(huì)創(chuàng)建遷移文件并生成 Prisma Client。注意一個(gè)關(guān)鍵順序必須先遷移、后啟動(dòng)開發(fā)服務(wù)器否則 tRPC 路由里使用ctx.db時(shí)會(huì)因?yàn)?Prisma Client 尚未生成而報(bào)錯(cuò)。初次執(zhí)行時(shí)你可能會(huì)發(fā)現(xiàn)node_modules/.prisma/client目錄出現(xiàn)了大量新文件這是正常現(xiàn)象不要因?yàn)槎喑龅奈募械讲话病?.2 設(shè)計(jì) tRPC Router記賬本的核心接口業(yè)務(wù)接口分兩大塊查詢流水列表、新增一筆流水。篩選條件通過(guò) input 傳入。這里重點(diǎn)展示輸入校驗(yàn)的作用因?yàn)楹芏嗳藭?huì)把 tRPC 的 input 校驗(yàn)忽略掉導(dǎo)致前端傳歪數(shù)據(jù)數(shù)據(jù)庫(kù)層才開始報(bào)錯(cuò)為時(shí)已晚。// src/server/api/routers/transaction.ts import { z } from zod; import { createTRPCRouter, publicProcedure } from ~/trpc/server; const transactionSchema z.object({ amount: z.number().positive(金額必須大于0), category: z.string().min(1, 分類不能為空), note: z.string().max(100).optional(), }); export const transactionRouter createTRPCRouter({ list: publicProcedure .input( z.object({ category: z.string().optional(), limit: z.number().int().min(1).max(50).default(20), }) ) .query(async ({ ctx, input }) { const whereClause input.category ? { category: input.category } : {}; return ctx.db.transaction.findMany({ where: whereClause, orderBy: { createdAt: desc }, take: input.limit, }); }), create: publicProcedure .input(transactionSchema) .mutation(async ({ ctx, input }) { return ctx.db.transaction.create({ data: input, }); }), });這段代碼同時(shí)體現(xiàn)了兩層價(jià)值第一層是類型安全性ctx.db.transaction.findMany返回的字段自動(dòng)推導(dǎo)到前端第二層是數(shù)據(jù)校驗(yàn)zod 會(huì)在請(qǐng)求進(jìn)入數(shù)據(jù)庫(kù)前就攔截非法數(shù)據(jù)。比如amount: -5會(huì)被直接拒絕而不是落到 SQL 層才出錯(cuò)。從我踩過(guò)的坑來(lái)看很多人會(huì)在前端表單里做校驗(yàn)服務(wù)端不設(shè)防這是很危險(xiǎn)的因?yàn)榻涌谝坏┍荒_本繞過(guò)頁(yè)面直連沒(méi)有服務(wù)端校驗(yàn)的系統(tǒng)就會(huì)灌入臟數(shù)據(jù)。路由寫完后把它掛載到根節(jié)點(diǎn)// src/server/api/root.ts import { createTRPCRouter } from ~/trpc/server; import { transactionRouter } from ./routers/transaction; export const appRouter createTRPCRouter({ transaction: transactionRouter, }); export type AppRouter typeof appRouter;注意export type AppRouter這行它把路由類型導(dǎo)出客戶端會(huì)從同一個(gè).ts文件拿到類型定義這就是端到端類型安全的物理基礎(chǔ)。3.3 前端頁(yè)面從 useQuery 到交互全部打通前端部分使用 Next.js App Router。因?yàn)?t3code 自動(dòng)分離服務(wù)端和客戶端組件我們需要用useQuery時(shí)一定要在組件頂部加use client指令否則會(huì)報(bào) Server Components 無(wú)法使用 hook 的錯(cuò)誤。記賬本首頁(yè)的簡(jiǎn)化實(shí)現(xiàn)// src/app/page.tsx use client; import { api } from ~/trpc/react; import { useState } from react; export default function HomePage() { const [categoryFilter, setCategoryFilter] useState(); const { data: transactions, refetch } api.transaction.list.useQuery({ category: categoryFilter || undefined, }); const createMutation api.transaction.create.useMutation({ onSuccess: () { refetch(); }, }); const handleSubmit (e: React.FormEvent) { e.preventDefault(); const formData new FormData(e.currentTarget as HTMLFormElement); createMutation.mutate({ amount: Number(formData.get(amount)), category: String(formData.get(category)), note: String(formData.get(note)), }); }; return ( main classNamemx-auto max-w-2xl p-8 h1 classNametext-2xl font-bold記賬本/h1 form onSubmit{handleSubmit} classNamemy-6 flex gap-3 input nameamount typenumber step0.01 placeholder金額 classNameborder p-2 / input namecategory placeholder分類 classNameborder p-2 / input namenote placeholder備注 classNameborder p-2 / button typesubmit classNamebg-blue-600 text-white px-4 py-2 rounded 添加 /button /form ul {transactions?.map((tx) ( li key{tx.id} classNameflex justify-between border-b py-2 span{tx.category}/span span￥{tx.amount.toFixed(2)}/span /li ))} /ul /main ); }這段代碼可以原樣跑起來(lái)但我得提醒幾個(gè)關(guān)鍵點(diǎn)。第一api.transaction.list.useQuery會(huì)走 tRPC 內(nèi)部狀態(tài)管理它不發(fā)表單請(qǐng)求也不會(huì)手動(dòng)維護(hù) URL所有請(qǐng)求細(xì)節(jié)都被封裝好了。第二useMutation的onSuccess里調(diào)用refetch是初版最直接的刷新方式后期可以換成 tRPC 的utils.transaction.list.invalidate()這是官方推薦方式能讓所有監(jiān)聽同一 key 的組件同時(shí)刷新。3.4 構(gòu)建與部署本地驗(yàn)證和生產(chǎn)環(huán)境的差異開發(fā)環(huán)境跑通之后部署時(shí)最大的變化是數(shù)據(jù)庫(kù)和后端環(huán)境變量。本地開發(fā)用 SQLite部署到生產(chǎn)環(huán)境我會(huì)換成 PostgreSQL。這個(gè)切換在 t3code 里只是改 provider 字段和 DATABASE_URL 的值嗎沒(méi)那么簡(jiǎn)單有幾個(gè)隱藏點(diǎn)需要同步處理。prisma/schema.prisma中 datasource provider 需要從sqlite改成postgresql然后重新生成遷移。PostgreSQL 需要額外的連接池參數(shù)如果不設(shè)置默認(rèn)連接數(shù)可能在并發(fā)上來(lái)之后被打滿。我習(xí)慣在src/server/db.ts中擴(kuò)展 PrismaClient 實(shí)例// src/server/db.ts import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma?: PrismaClient }; export const db globalForPrisma.prisma ?? new PrismaClient({ log: process.env.NODE_ENV development ? [query, error, warn] : [error], }); if (process.env.NODE_ENV ! production) globalForPrisma.prisma db;這段代碼是社區(qū)里的標(biāo)準(zhǔn)防熱重載方案。Next.js 開發(fā)模式下模塊可能被反復(fù)加載如果每次加載都新建一個(gè) PrismaClient最終會(huì)耗盡數(shù)據(jù)庫(kù)連接數(shù)。把實(shí)例掛到globalThis上開發(fā)模式就只會(huì)在全局創(chuàng)建一個(gè)實(shí)例。生產(chǎn)環(huán)境下不需要這個(gè)緩存邏輯所以用環(huán)境變量做了區(qū)分。部署階段我建議用 Docker 把 Next.js 應(yīng)用和數(shù)據(jù)庫(kù)一起編排出鏡像但這篇文章不展開 Docker 細(xì)節(jié)。我只強(qiáng)調(diào)一個(gè)踩坑點(diǎn)在 Serverless 平臺(tái)上部署時(shí)PrismaClient 初始化時(shí)機(jī)要避開請(qǐng)求熱路徑否則每個(gè)冷啟動(dòng)實(shí)例都可能創(chuàng)建新的連接池造成數(shù)據(jù)庫(kù)鏈接耗盡。4. 常見問(wèn)題與排查技巧實(shí)錄4.1 tRPC 類型報(bào)錯(cuò)data 提示 undefined 或類型不匹配這是初學(xué)者遇到最多的一類問(wèn)題。現(xiàn)象是data的類型看起來(lái)是Transaction[]但實(shí)際使用時(shí)報(bào)Object is possibly undefined。原因在于 React Query 的data本質(zhì)上是個(gè)可空值查詢未完成時(shí)是 undefined查詢失敗也是 undefined。所以正確的寫法是先用條件判斷保護(hù){!transactions ? ( p加載中.../p ) : ( transactions.map((tx) div key{tx.id}{tx.amount}/div) )}另一個(gè)高發(fā)問(wèn)題是前后端類型不匹配。如果你的 tRPC 路由返回字段和前端期望不一致大部分情況是 Prisma 的 select 字段沒(méi)有包含前端需要的屬性。這個(gè)編譯期就會(huì)報(bào)錯(cuò)很容易修但有一個(gè)隱蔽場(chǎng)景你給某個(gè)字段起了別名或用了 include 關(guān)聯(lián)查詢返回結(jié)構(gòu)嵌套層級(jí)變深前端可能拿不到嵌套對(duì)象。我的排查建議是優(yōu)先懸停查看data的類型展開把鼠標(biāo)放到變量上看編輯器給出的結(jié)構(gòu)確認(rèn)哪一層開始斷掉的。這個(gè)習(xí)慣比盲猜字段名靠譜得多。4.2 Prisma 遷移記錄的坑migrate dev 與數(shù)據(jù)庫(kù)不同步npx prisma migrate dev偶爾會(huì)卡在生成歷史記錄上尤其是團(tuán)隊(duì)成員各自改了 schema 又拉了別人的遷移文件。我遇到過(guò)的典型報(bào)錯(cuò)是P3005提示遷移記錄與數(shù)據(jù)庫(kù)不一致。處理方式分兩類本地開發(fā)且數(shù)據(jù)不重要時(shí)可以執(zhí)行npx prisma migrate reset它會(huì)把數(shù)據(jù)庫(kù)重建到最新 schema代價(jià)是清空所有數(shù)據(jù)如果數(shù)據(jù)需要保留就只能手工檢查 migrations 文件夾里的 SQL 文件確認(rèn)哪一條沒(méi)有成功應(yīng)用然后手動(dòng)執(zhí)行補(bǔ)丁。這里我給一條經(jīng)驗(yàn)項(xiàng)目初期就把遷移文件當(dāng)成代碼一樣審查每次提交prisma/migrations/目錄里的新增文件時(shí)打開看一遍 SQL 內(nèi)容確認(rèn)字段類型、索引、外鍵都符合預(yù)期。數(shù)據(jù)庫(kù)是長(zhǎng)期資產(chǎn)遷移歷史的混亂比代碼混亂的代價(jià)高一個(gè)量級(jí)。4.3 NextAuth 與 tRPC 的上下文時(shí)機(jī)session 怎么取集成 NextAuth 時(shí)不少同學(xué)發(fā)現(xiàn)protectedProcedure時(shí)而有效時(shí)而無(wú)權(quán)訪問(wèn)。排查時(shí)先確認(rèn) tRPC 的上下文創(chuàng)建函數(shù)里是否按需注入了 session// src/trpc/server.ts export const createTRPCContext async (opts: { headers: Headers }) { const session await getServerSession(authOptions); return { db, session, ...opts, }; };這個(gè)getServerSession只能在服務(wù)端組件或 API 路由里調(diào)用。如果你在客戶端調(diào)useQuery時(shí)把 session 手動(dòng)塞進(jìn)去反而會(huì)破壞 tRPC 的封裝鏈路。正確做法是所有受保護(hù)路由都在服務(wù)端上下文里讀取 session前端只需關(guān)心有沒(méi)有 token不需要自己傳 session。另外一個(gè)容易踩的坑是 NextAuth 的authOptions定義在src/server/auth.ts而你注意到 create-t3-app 腳手架生成的路徑里可能有 plan 或 edge 兼容問(wèn)題。不要為了省事把 authOptions 復(fù)制到多個(gè)文件保持單一來(lái)源否則 session 校驗(yàn)邏輯不一致會(huì)出現(xiàn)登錄了但 tRPC 說(shuō)沒(méi)登錄的詭異現(xiàn)象。4.4 環(huán)境變量校驗(yàn)運(yùn)行時(shí)發(fā)現(xiàn)變量缺失腳手架默認(rèn)生成env.js做環(huán)境變量運(yùn)行時(shí)校驗(yàn)這其實(shí)是個(gè)被很多人忽略的救命設(shè)計(jì)。本地啟動(dòng)時(shí)如果缺少DATABASE_URL會(huì)出現(xiàn)帶堆棧的報(bào)錯(cuò)指向 PrismaClient 初始化那行。很多人會(huì)以為 Prisma 裝壞了其實(shí)只要檢查.env文件即可。我建議在生產(chǎn)構(gòu)建前先執(zhí)行一次next build如果 env.js 的校驗(yàn)失敗構(gòu)建會(huì)直接中斷。這個(gè)特性讓你在部署之前就發(fā)現(xiàn)配置缺失而不是容器跑起來(lái)后靠日志排查。注意 env.js 里定義的變量必須與.env.example保持一致否則新同事加入時(shí)復(fù)制示例文件后仍然缺變量。養(yǎng)成把新增變量同步到.env.example的習(xí)慣團(tuán)隊(duì)協(xié)作時(shí)能省很多溝通成本。4.5 Tailwind 類名好像沒(méi)生效內(nèi)容路徑配置Tailwind 的 JIT 模式掃描文件是有范圍限制的。如果你把組件放到腳手架默認(rèn)的src/components之外或者新建了一個(gè)不在掃描路徑里的目錄樣式就編譯不進(jìn)去。這個(gè)問(wèn)題最常見于 monorepo 結(jié)構(gòu)你有一個(gè)獨(dú)立的 ui 包Tailwind 在應(yīng)用層沒(méi)有掃描到那個(gè)包的路徑。解決方案是在tailwind.config.ts里補(bǔ)充 content 配置content: [./src/**/*.{js,ts,jsx,tsx}, ../../packages/ui/**/*.{js,ts,jsx,tsx}]改完后重啟開發(fā)服務(wù)器Tailwind 才會(huì)重新掃描文件。另外注意 class 名不要拼成動(dòng)態(tài)字符串比如bg-${color}-500這種寫法Tailwind 無(wú)法在編譯期識(shí)別樣式必然丟失。這也是很多人寫死 class 都有樣式、拆成變量就失效的根源。結(jié)尾t3code 還可以這樣擴(kuò)展我個(gè)人在實(shí)際開發(fā)中的體會(huì)是t3code 這套組合最難得的地方不在于某個(gè)單一技術(shù)多強(qiáng)大而在于它把類型安全的理念貫徹到了數(shù)據(jù)鏈路的每個(gè)環(huán)節(jié)。這里最后分享一個(gè)擴(kuò)展方向當(dāng)團(tuán)隊(duì)業(yè)務(wù)復(fù)雜度上來(lái)后會(huì)需要給公開頁(yè)面做一個(gè)獨(dú)立的 React Native 應(yīng)用這時(shí) tRPC 就不是唯一通道了我會(huì)在 t3code 的體系之外另起一個(gè) BFF 層用 Hono 或 Fastify 包裝一部分帶鑒權(quán)的 REST API供移動(dòng)端使用。這不意味著放棄 t3code而是把傳統(tǒng) API 保留在外部邊界讓內(nèi)部核心邏輯繼續(xù)享受這套類型安全體系帶來(lái)的紅利。希望這篇文章能幫你少踩一些坑建議你拿記賬本這個(gè)例子親手跑一遍跑通之后再替換成自己的業(yè)務(wù)字段很快你就能理解這套技術(shù)棧的設(shè)計(jì)精髓了。