以前搭全棧項(xiàng)目最讓我頭疼的從來不是功能復(fù)雜度而是前后端之間那層反復(fù)扯皮的類型定義。后端改了字段名前端編譯直接一片紅更別提寫一整套 API 封裝、手搓類型聲明、再對著文檔排查接口字段的日常。后來接觸到 t3code 這套基于 T3 Stack 的腳手架工作流我最大的感受是它不是在幫你寫代碼而是在重構(gòu)你組織全棧代碼的方式——把“前后端各寫一套”變成“從一個(gè)類型源頭自動(dòng)派生出整個(gè)調(diào)用鏈路”。這篇文章我就用實(shí)際經(jīng)歷聊聊t3code 到底解決了我哪些真實(shí)痛點(diǎn)里面的技術(shù)選型是怎么協(xié)作的以及從初始化到部署我用它做完兩個(gè)項(xiàng)目后沉淀下來的經(jīng)驗(yàn)和幾個(gè)躲不開的坑。1. 為什么我盯上了 t3code從手寫后端到全棧類型安全的轉(zhuǎn)變1.1 全棧項(xiàng)目最消耗精力的是“共識維護(hù)”一提到全棧項(xiàng)目很多人第一反應(yīng)是“技術(shù)棧多”“要學(xué)的東西雜”。但我真正做了幾個(gè)商用規(guī)模的 Web 應(yīng)用之后發(fā)現(xiàn)技術(shù)棧復(fù)雜只是入門門檻真正的隱性成本在于前后端對數(shù)據(jù)結(jié)構(gòu)的共識怎么維護(hù)。傳統(tǒng)方案里前端通常通過 REST API 和 Vue/React 頁面打交道我需要維護(hù)一份 API 文檔或者用 OpenAPI/Swagger 描述接口后端改了 User 模型的字段前端必須同步修改 interface。項(xiàng)目一大了這個(gè)同步過程就會(huì)出現(xiàn)三類問題改了后端字段但前端沒跟上線上頁面白屏或者取到 undefined接口文檔更新不及時(shí)前端按舊文檔聯(lián)調(diào)浪費(fèi)半天時(shí)間某個(gè)字段從 string 變成 number類型沒有編譯期報(bào)錯(cuò)導(dǎo)致運(yùn)行期才暴露異常。t3code 的出現(xiàn)有意思在它換了個(gè)思路與其費(fèi)力維護(hù)前后端的類型共識不如讓后端類型直接生成前端調(diào)用代碼的類型簽名。也就是說前端真正調(diào)用的數(shù)據(jù)是從后端那個(gè)唯一的類型源頭“長”出來的。1.2 t3code 到底是什么雖然現(xiàn)在網(wǎng)上也有各種以 t3 開頭命名的項(xiàng)目但我在實(shí)際開發(fā)中使用的 t3code本質(zhì)上是一套面向全棧 TypeScript 項(xiàng)目的腳手架和模塊初始化工具。它圍繞 T3 StackNext.js TypeScript tRPC Prisma Tailwind CSS把項(xiàng)目的基礎(chǔ)骨架、數(shù)據(jù)模型、認(rèn)證體系、API 路由和前后端調(diào)用關(guān)系一次性裝配起來我拿到手就能直接把精力放到業(yè)務(wù)邏輯上。我自己的體會(huì)是t3code 最適合這幾類人獨(dú)立開發(fā)者想用一份 TypeScript 代碼同時(shí)打通數(shù)據(jù)庫、后端邏輯和前端頁面小型全棧團(tuán)隊(duì)希望減少前后端聯(lián)調(diào)時(shí)的來回溝通成本正在搭建 MVP 的創(chuàng)業(yè)項(xiàng)目需要快速迭代數(shù)據(jù)結(jié)構(gòu)且不想被接口設(shè)計(jì)和類型維護(hù)拖慢速度。如果你平時(shí)只是寫純前端或者純后端t3code 的收益不大但如果你做的是那種“一個(gè)人要包圓前后端數(shù)據(jù)庫”的活它真的能幫你省下很多重復(fù)勞動(dòng)。1.3 它和“低代碼平臺”完全不是一回事第一次聽到這類工具時(shí)我也擔(dān)心過這會(huì)不會(huì)又是一套低代碼平臺把我綁定到某個(gè)私有協(xié)議上以后想遷移都沒法遷移實(shí)際研究過后我可以明確說t3code 不搞任何私有的運(yùn)行時(shí)協(xié)議它輸出的就是一個(gè)標(biāo)準(zhǔn)的 Next.js 項(xiàng)目里面有正常的 Prisma schema、tRPC router、頁面組件和 API 流程。換句話說它幫我完成的是“裝配和初始化”不是“托管和綁架”。項(xiàng)目一旦生成源碼都在我手里所有邏輯都由我自己控制該寫測試寫測試、該做性能優(yōu)化做性能優(yōu)化沒有任何黑盒。1.4 從“寫最少代碼”到“改最少代碼”我用傳統(tǒng)方式做一個(gè)帶用戶系統(tǒng)的內(nèi)容管理后臺大概要經(jīng)歷設(shè)計(jì)數(shù)據(jù)庫表結(jié)構(gòu)、寫后端 CRUD 接口、逐一手寫路由和校驗(yàn)、生成前端 API 封裝、在頁面上手動(dòng)消費(fèi)數(shù)據(jù)、遇到類型不一致再回頭改。整個(gè)流程中真正屬于業(yè)務(wù)邏輯的代碼可能只占 40%剩下 60% 都在做“翻譯”和“適配”工作。t3code 把我從這種狀態(tài)里拉出來之后我明顯感覺到工作模式變了。從前是“寫最少代碼完成任務(wù)”現(xiàn)在更像是“盡量少改代碼地演化業(yè)務(wù)”。數(shù)據(jù)庫加個(gè)字段Prisma 遷移一執(zhí)行類型自動(dòng)更新后端在 tRPC 的 router 里加一個(gè) query前端立刻能在編輯器里拿到帶類型提示的調(diào)用方法甚至參數(shù)結(jié)構(gòu)都是自動(dòng)推導(dǎo)的。這種“一處修改處處類型安全”的體驗(yàn)用一次就回不去。2. t3code 的底層構(gòu)成T3 技術(shù)棧四件套是怎么協(xié)作的2.1 四個(gè)核心依賴各管哪一段t3code 生成的骨架里最核心的是四個(gè)依賴。很多人把它們當(dāng)成單純的技術(shù)組合但我在實(shí)際使用中更關(guān)注它們各自承擔(dān)的角色以及彼此之間的接縫在哪里。一是Next.js負(fù)責(zé)應(yīng)用框架層。它同時(shí)提供 React 頁面渲染、API Route、服務(wù)端渲染和靜態(tài)生成能力。在 T3 Stack 的語境里Next.js 不僅是一個(gè)頁面框架更是把前后端放在同一工程里的容器。二是TypeScript整個(gè)項(xiàng)目的類型系統(tǒng)基底。如果沒有 TypeScript后面講的“端到端類型安全”完全不成立所以我在 t3code 里很少看到 .js 文件所有業(yè)務(wù)代碼和配置文件都以 .ts 或 .tsx 為主。三是tRPC負(fù)責(zé)前后端調(diào)用層的協(xié)議。它不需要我們手寫 REST 路由也不需要生成 GraphQL schema而是直接通過函數(shù)調(diào)用的方式在前端調(diào)用后端方法并且自動(dòng)獲得完整的類型推導(dǎo)。它的實(shí)現(xiàn)原理不復(fù)雜就是依賴 TypeScript 的泛型把 router 類型直接傳遞到前端 hooks 上。四是Prisma負(fù)責(zé)數(shù)據(jù)模型和數(shù)據(jù)庫訪問。它用一個(gè) schema 文件定義模型然后生成類型安全的客戶端。在 t3code 的項(xiàng)目里Prisma 的 model 是整個(gè)應(yīng)用數(shù)據(jù)結(jié)構(gòu)的直接描述者。至于 Tailwind CSS我一般把它看成錦上添花的樣式方案它解決的是 UI 層開發(fā)效率的問題不影響類型閉環(huán)。2.2 類型閉環(huán)是怎么走通的要真正理解 t3code 的價(jià)值我建議你先搞清楚這條類型閉環(huán)的路徑Prisma schema 定義模型 ↓ Prisma Client 生成類型 ↓ tRPC router 里用這些類型處理輸入輸出 ↓ 前端通過 tRPC hooks 調(diào)用 router ↓ 編輯器根據(jù)推導(dǎo)自動(dòng)提示類型和參數(shù)我把這條鏈路拆開講一下。假設(shè)我在prisma/schema.prisma里定義一個(gè)Todo模型model Todo { id String id default(cuid()) title String completed Boolean default(false) createdAt DateTime default(now()) }執(zhí)行npx prisma migrate dev之后Prisma 客戶端會(huì)生成對應(yīng)的Todo類型。接著在 tRPC router 中加入一個(gè)返回所有待辦事項(xiàng)的查詢import { router, publicProcedure } from ../trpc; import { prisma } from ../db; export const todoRouter router({ getAll: publicProcedure.query(() { return prisma.todo.findMany(); }), });前端頁面里我不需要重新定義任何 interface直接調(diào)用import { api } from ~/utils/api; export default function TodoList() { const { data: todos } api.todo.getAll.useQuery(); return ( ul {todos?.map((todo) ( li key{todo.id}{todo.title}/li ))} /ul ); }這里你會(huì)發(fā)現(xiàn)一個(gè)有意思的地方todos的類型是由后端 Prisma 查詢結(jié)果推導(dǎo)出來的而不是我手動(dòng)聲明的。哪怕哪天我往模型里加了字段前端代碼里todo.someNewField也馬上會(huì)有類型提示如果我刪了某個(gè)字段前端用到它的地方會(huì)直接編譯報(bào)錯(cuò)。這條閉環(huán)的意義在于它把“類型正確性”從一種約定變成了一種編譯期保證。我不用再擔(dān)心“前端不知道后端字段改過”這種事因?yàn)轭愋拖到y(tǒng)會(huì)第一時(shí)間攔住我。2.3 和 REST / GraphQL 方案的直觀對比我知道有人會(huì)問我用 REST 加 OpenAPI 也能生成類型用 GraphQL 也能自動(dòng)推導(dǎo)為什么非要用 t3code 這一套我做了一張粗淺的對照表完全基于我的日常體感方案類型安全性聯(lián)調(diào)成本學(xué)習(xí)曲線適用場景REST 手寫類型靠自覺高低傳統(tǒng)前后端分離團(tuán)隊(duì)REST OpenAPI 生成類型中中中接口規(guī)范嚴(yán)格的團(tuán)隊(duì)GraphQL Codegen高低高需要靈活查詢的大前端團(tuán)隊(duì)t3codeT3 Stack高很低中全棧 TypeScript 項(xiàng)目、獨(dú)立開發(fā)者GraphQL 雖然查詢能力很靈活但為了拿到這種靈活性我得維護(hù) schema、寫 resolver、配 codegen還要考慮客戶端緩存策略對一個(gè)人干全棧來說其實(shí)不輕。t3code 里 tRPC 的模型更“純函數(shù)式”前端調(diào)用后端的體驗(yàn)幾乎等于調(diào)用本地函數(shù)而且不用額外跑代碼生成器類型推導(dǎo)是實(shí)時(shí)的。當(dāng)然 tRPC 也有自己的適用范圍——如果前后端完全分離且由不同團(tuán)隊(duì)維護(hù)或者需要對外提供公共 APItRPC 反而不合適。它更多是內(nèi)部后端和前端之間的一種高效溝通方式。選型永遠(yuǎn)要基于項(xiàng)目形態(tài)t3code 適合的是“一個(gè)代碼庫搞定全?！钡膱鼍啊?. 跑通第一個(gè) t3code 項(xiàng)目從初始化到 CRUD 的完整鏈路3.1 初始化項(xiàng)目時(shí)該選哪些模塊t3code 的起點(diǎn)是create-t3-app這個(gè)命令。我在終端執(zhí)行npx create-t3-applatest my-app交互式命令行會(huì)問你項(xiàng)目名稱、要不要啟用 NextAuth.js、Prisma、Tailwind CSS、tRPC 這些模塊以及使用 npm 還是 pnpm 等包管理器。我第一次跑的時(shí)候很老實(shí)把能勾選的全都勾上了。后來實(shí)際開發(fā)才意識到不必為了齊全而全選要根據(jù)業(yè)務(wù)預(yù)判來選。我現(xiàn)在的選擇習(xí)慣是一定會(huì)選 TypeScript、Prisma、tRPC、Next.js這是核心需要用戶登錄時(shí)才會(huì)勾選 NextAuth.js如果只是內(nèi)部系統(tǒng)且不涉及用戶體系不選它反而省事Tailwind CSS 純看項(xiàng)目 UI 需求如果團(tuán)隊(duì)已經(jīng)定了組件庫或者用其他 CSS 方案就不必讓它進(jìn)入代碼庫部署平臺選擇 Vercel 時(shí)腳手架會(huì)順便把本地開發(fā)和生產(chǎn)環(huán)境的配置處理好選 Docker 自托管的話后面要自己留意數(shù)據(jù)庫連接。初始化完成后項(xiàng)目的目錄結(jié)構(gòu)大概是這樣的my-app/ ├── prisma/ │ └── schema.prisma ├── src/ │ ├── pages/ │ ├── server/ │ │ ├── api/ │ │ │ └── trpc/ │ │ ├── auth.ts │ │ └── db.ts │ └── utils/ │ └── api.ts ├── .env └── package.json這里src/server/db.ts是 Prisma Client 單例src/utils/api.ts是前端 tRPC hooks 的封裝入口src/server/api/trpc.ts定義了 router 創(chuàng)建和 procedure 的基礎(chǔ)。我建議拿到項(xiàng)目后先花十分鐘把這三個(gè)文件讀一遍理解它們之間的引用關(guān)系后面寫業(yè)務(wù)會(huì)順很多。3.2 從 schema 到數(shù)據(jù)庫遷移我拿一個(gè)最簡單的博客系統(tǒng)舉例。先在prisma/schema.prisma里定義 Post 和 User 模型model User { id String id default(cuid()) email String unique name String? posts Post[] } model Post { id String id default(cuid()) title String content String published Boolean default(false) authorId String author User relation(fields: [authorId], references: [id]) createdAt DateTime default(now()) updatedAt DateTime updatedAt }然后執(zhí)行npx prisma migrate dev --name init這個(gè)命令會(huì)做兩件事在數(shù)據(jù)庫里創(chuàng)建對應(yīng)的表同時(shí)生成最新版的 Prisma Client。我提醒一句本地?cái)?shù)據(jù)庫連接串記得先寫進(jìn).env很多人第一次跑 migrate 失敗都是因?yàn)榄h(huán)境變量沒配置。3.3 編寫 tRPC router 并注冊接著我在src/server/api/root.ts或其他你自定義的 router 聚合文件里添加一個(gè) postRouterimport { z } from zod; import { createTRPCRouter, publicProcedure } from ~/server/api/trpc; import { prisma } from ~/server/db; export const postRouter createTRPCRouter({ list: publicProcedure.query(() { return prisma.post.findMany({ orderBy: { createdAt: desc }, }); }), byId: publicProcedure .input(z.object({ id: z.string() })) .query(({ input }) { return prisma.post.findUnique({ where: { id: input.id }, include: { author: true }, }); }), create: publicProcedure .input( z.object({ title: z.string().min(1), content: z.string().min(1), authorEmail: z.string().email(), }) ) .mutation(async ({ input }) { const user await prisma.user.upsert({ where: { email: input.authorEmail }, update: {}, create: { email: input.authorEmail, name: input.authorEmail.split()[0] }, }); return prisma.post.create({ data: { title: input.title, content: input.content, authorId: user.id, }, }); }), });這里你可能注意到我用了 zod 做輸入校驗(yàn)。tRPC 原生建議用 zod 作為 schema 校驗(yàn)庫它和 tRPC 的 input 結(jié)合非常好。輸入校驗(yàn)不僅保證了后端接口的參數(shù)安全還讓前端調(diào)用時(shí)能拿到準(zhǔn)確的入?yún)㈩愋吞崾舅闶穷愋烷]環(huán)里的重要一環(huán)。寫完之后必須把 postRouter 注冊到根 router 上否則前端根本訪問不到import { createTRPCRouter } from ~/server/api/trpc; import { postRouter } from ./post; export const appRouter createTRPCRouter({ post: postRouter, }); export type AppRouter typeof appRouter;3.4 前端頁面消費(fèi) API前端頁面直接對應(yīng)src/pages/index.tsx我用一個(gè)列表頁展示所有文章import { api } from ~/utils/api; import Link from next/link; export default function Home() { const { data: posts, isLoading } api.post.list.useQuery(); if (isLoading) return divLoading.../div; return ( div {posts?.map((post) ( Link key{post.id} href{/post/${post.id}} h2{post.title}/h2 p{post.content}/p /Link ))} /div ); }刷新頁面后數(shù)據(jù)就能正常渲染。我沒寫任何額外的 axios 封裝沒有手動(dòng)拼 URL沒有定義 response interface甚至連useQuery的泛型都不用傳類型全是從后端推導(dǎo)過來的。這個(gè)“少寫代碼但類型更強(qiáng)”的體驗(yàn)就是我前面說的核心價(jià)值。如果想做創(chuàng)建文章的交互也很直接const createPost api.post.create.useMutation({ onSuccess: () { utils.post.list.invalidate(); }, }); createPost.mutate({ title: 新文章, content: 正文內(nèi)容, authorEmail: testexample.com, });用invalidate讓列表重新請求一次數(shù)據(jù)自動(dòng)刷新前端邏輯保持得非常干凈。3.5 雙向綁定與 SSR 模式的一點(diǎn)提醒t3code 默認(rèn)會(huì)用 Next.js 的 SSR/SSG 能力來預(yù)取 tRPC 數(shù)據(jù)。也就是說服務(wù)端會(huì)先主動(dòng)調(diào)用 tRPC 方法把數(shù)據(jù)塞進(jìn)頁面 props 里瀏覽器端再用同一個(gè) hook 做水合。這套機(jī)制讓首屏加載很快也不會(huì)有白屏閃爍。但這里的隱性前提是服務(wù)端調(diào)用和客戶端調(diào)用共享同一套 tRPC 邏輯。如果你在 procedure 里訪問了只存在于瀏覽器端的window或者localStorage服務(wù)端執(zhí)行時(shí)就會(huì)直接報(bào)錯(cuò)。我建議你從第一天開始就養(yǎng)成習(xí)慣把涉及瀏覽器環(huán)境變量的邏輯放到獨(dú)立的工具函數(shù)里并且用typeof window ! undefined判斷環(huán)境不然部署到 Vercel 上很容易踩 SSR 相關(guān)的坑。4. 接入認(rèn)證和數(shù)據(jù)庫之后我踩過的那些坑4.1 NextAuth.js 和 Prisma 的適配器問題t3code 腳手架雖然默認(rèn)集成了 NextAuth.js但真正接入登錄功能時(shí)我遇到的第一坑是適配器adapter的配置。NextAuth 要跟 Prisma 配合必須用next-auth/prisma-adapter并且在src/server/auth.ts里正確傳參。如果適配器沒配好最常見的報(bào)錯(cuò)是調(diào)用登錄接口時(shí)數(shù)據(jù)庫無法寫入 session 記錄。我當(dāng)時(shí)的排查過程是這樣的先看服務(wù)端日志確認(rèn)是 session 表寫入失敗再看auth.ts里的配置發(fā)現(xiàn)adapter沒有被傳入。修正后的核心代碼大致是import NextAuth from next-auth; import CredentialsProvider from next-auth/providers/credentials; import { PrismaAdapter } from next-auth/prisma-adapter; import { prisma } from ~/server/db; export const authOptions { adapter: PrismaAdapter(prisma), providers: [ CredentialsProvider({ name: credentials, credentials: { email: { label: Email, type: email }, password: { label: Password, type: password }, }, async authorize(credentials) { // 這里是校驗(yàn)邏輯 }, }), ], session: { strategy: jwt, }, secret: process.env.NEXTAUTH_SECRET, };接下來還有一個(gè)容易忽視的點(diǎn)如果用默認(rèn)的strategy: jwt就不太依賴數(shù)據(jù)庫里的 session 記錄這時(shí) PrismaAdapter 需要同步維護(hù)的其實(shí)是 User、Account、Session 等模型。我在 schema 里如果漏了這些模型登錄時(shí)也會(huì)因?yàn)閿?shù)據(jù)庫缺表而出錯(cuò)。解法很簡單把官網(wǎng)文檔里提供的 NextAuth 相關(guān)模型復(fù)制到schema.prisma再跑一次遷移問題基本就解決了。4.2 環(huán)境變量缺失導(dǎo)致的“幽靈報(bào)錯(cuò)”t3code 初始化后項(xiàng)目根目錄會(huì)生成一個(gè).env文件里面通常會(huì)預(yù)留DATABASE_URL、NEXTAUTH_SECRET、NEXTAUTH_URL這些變量。我最開始忽略了一點(diǎn)本地開發(fā)和生產(chǎn)環(huán)境需要不同取值。比如本地.env里DATABASE_URL指向localhost的 PostgreSQL生產(chǎn)環(huán)境在 Vercel 后臺配的卻是線上數(shù)據(jù)庫地址。如果你在本地跑prisma migrate deploy時(shí)用錯(cuò)了環(huán)境變量有可能把遷移應(yīng)用到線上或者本地庫上那將是災(zāi)難。我的建議是給不同環(huán)境配獨(dú)立的.env文件如.env.local、.env.production并且永遠(yuǎn)只在項(xiàng)目目錄里執(zhí)行數(shù)據(jù)庫遷移命令。雖然這屬于老生常談但團(tuán)隊(duì)協(xié)作時(shí)真的有人會(huì)把線上連接串寫到公共配置里導(dǎo)致泄露。4.3 protectedProcedure 的正確姿勢t3code 腳手架通常會(huì)提供一個(gè)createTRPCContext函數(shù)把當(dāng)前請求的 session 塞進(jìn) context。我后來在寫需要登錄才能調(diào)用的接口時(shí)沒用publicProcedure而是基于 context 判斷后再拋錯(cuò)export const protectedProcedure t.procedure.use(({ ctx, next }) { if (!ctx.session || !ctx.session.user) { throw new Error(Unauthorized); } return next({ ctx: { session: { ...ctx.session, user: ctx.session.user }, }, }); });這個(gè)中間件做完之后我想獲取當(dāng)前用戶時(shí)直接讀ctx.session.user就行。前端調(diào)用時(shí)配合useSession()判斷登錄態(tài)體驗(yàn)整體很順。我踩過的坑是如果 session 類型沒和數(shù)據(jù)庫的 User 模型對齊前端拿到的session.user.id可能被推導(dǎo)成string | undefined導(dǎo)致一些危險(xiǎn)的隱性 bug——比如在創(chuàng)建 Post 時(shí)把 undefined 寫進(jìn) authorId。所以建議大家拿到 session 后先做一次顯式判空再往下走。4.4 CRUD 校驗(yàn)放在服務(wù)端不要在客戶端省事tRPC 的好處是輸入校驗(yàn)天然寫在服務(wù)端 procedure 里但我見過有些同事圖方便只在前端表單里做了校驗(yàn)后端換個(gè)請求工具直接把非法字段傳進(jìn)去。說實(shí)話因?yàn)?tRPC 的類型推導(dǎo)太舒服了人很容易產(chǎn)生“前端類型安全等于接口安全”的錯(cuò)覺。實(shí)際上類型安全不等于安全。zod 校驗(yàn)?zāi)菍臃谰€必須留在服務(wù)端。我在 t3code 項(xiàng)目里的習(xí)慣是所有涉及寫入的操作一律寫 zod input schema并且把z.string().min(1)這類邊界條件寫全。這樣即使有人繞過前端調(diào)后端數(shù)據(jù)也會(huì)被攔截在這層不會(huì)污染數(shù)據(jù)庫。5. 部署與優(yōu)化從開發(fā)機(jī)到生產(chǎn)環(huán)境的最后一公里5.1 部署到 Vercel 前要處理的事情t3code 生成的 Next.js 項(xiàng)目直接對接 Vercel 很方便。我第一次部署時(shí)只把 GitHub 倉庫連到 Vercel然后添加環(huán)境變量就完事了。但后來發(fā)現(xiàn)有幾個(gè)細(xì)節(jié)要提前準(zhǔn)備好否則很容易在線上出現(xiàn)詭異問題。第一Prisma Client 的生成時(shí)機(jī)。Vercel 構(gòu)建時(shí)會(huì)跑prisma generate但只在構(gòu)建環(huán)境里生成如果你本地的 Prisma Client 版本和線上不一致有可能導(dǎo)致運(yùn)行時(shí)錯(cuò)誤。我一般會(huì)在package.json的postinstall腳本里加上postinstall: prisma generate這樣每次裝完依賴都會(huì)從 schema 重新生成客戶端不會(huì)出現(xiàn)版本漂移。第二數(shù)據(jù)庫遷移怎么執(zhí)行。Vercel 的構(gòu)建環(huán)境不是跑遷移的好地方我推薦用 GitHub Actions 或一個(gè)獨(dú)立的環(huán)境去跑prisma migrate deploy。也就是說代碼部署和數(shù)據(jù)庫遷移分成兩個(gè)流程代碼先發(fā)布遷移單獨(dú)控制節(jié)奏。這樣做的好處是一旦遷移失敗不會(huì)把應(yīng)用構(gòu)建直接拖死。第三NEXTAUTH_URL 必須和生產(chǎn)域名一致。NextAuth 在做回調(diào)時(shí)會(huì)校驗(yàn)這個(gè)變量我見過不少案例是由于把它留成http://localhost:3000導(dǎo)致線上登錄后跳轉(zhuǎn)回本地地址表現(xiàn)為“登錄成功但立刻又跳回登錄頁”。這個(gè)坑排查起來其實(shí)不難但確實(shí)很耗時(shí)間。5.2 Serverless 環(huán)境下的數(shù)據(jù)庫連接池Vercel 的 Serverless 函數(shù)是“按請求拉起、跑完即回收”的模型。如果我在每個(gè)函數(shù)實(shí)例里都創(chuàng)建一個(gè)新的 Prisma Client 連接很快會(huì)把數(shù)據(jù)庫連接數(shù)打滿尤其在使用 PostgreSQL 時(shí)特別明顯。t3code 生成的src/server/db.ts里幫我做了一個(gè)全局單例import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma: PrismaClient }; export const prisma globalForPrisma.prisma ?? new PrismaClient({ log: process.env.NODE_ENV development ? [query, error, warn] : [error], }); if (process.env.NODE_ENV ! production) globalForPrisma.prisma prisma;這個(gè)模式的核心意圖是在本地開發(fā)時(shí)熱更新會(huì)導(dǎo)致模塊反復(fù)加載如果不做全局緩存每次刷新都會(huì)創(chuàng)建新的 Prisma 實(shí)例部署到 Serverless 環(huán)境后同一實(shí)例內(nèi)部復(fù)用連接。我在生產(chǎn)環(huán)境跑了一段時(shí)間后數(shù)據(jù)庫連接數(shù)一直保持在一個(gè)健康水位。如果項(xiàng)目流量上來還可以在數(shù)據(jù)庫連接串里加上連接池參數(shù)比如 Prisma 官方建議的?pgbouncertrue配合 PgBouncer 使用。要不要這樣做取決于實(shí)際并發(fā)量我自己的經(jīng)驗(yàn)是中小型應(yīng)用把單例模式做好就夠用了等連接數(shù)告警了再上連接池也不遲。5.3 首屏性能調(diào)優(yōu)的幾個(gè)實(shí)際操作雖然 t3code 的默認(rèn)體驗(yàn)已經(jīng)不錯(cuò)但生產(chǎn)環(huán)境對性能的要求更高。我做過的幾個(gè)有效優(yōu)化排在這里按需取數(shù)據(jù)Prisma 的select和include要按頁面需要來避免一次findMany把幾十個(gè)字段全撈出來。Serverless 函數(shù)的執(zhí)行時(shí)間就是錢數(shù)據(jù)量小一點(diǎn)響應(yīng)自然快。開啟 Next.js 的緩存策略對于不常變的數(shù)據(jù)可以用staleTime控制 tRPC 查詢的緩存時(shí)長。例如文章列表五分鐘內(nèi)不重新請求api.post.list.useQuery(undefined, { staleTime: 5 * 60 * 1000, });嚴(yán)格區(qū)分動(dòng)態(tài)和靜態(tài)頁面博客首頁、關(guān)于頁這種內(nèi)容基本不變的盡量用靜態(tài)生成用戶中心這種強(qiáng)個(gè)性化的頁面再走 SSR 或客戶端渲染。能靜態(tài)就不動(dòng)態(tài)能讓邊緣緩存接住就讓它接住。5.4 日志、監(jiān)控和錯(cuò)誤上報(bào)做全棧項(xiàng)目時(shí)日志是最容易被忽略但又最重要的一環(huán)。t3code 腳手架只給了基礎(chǔ)結(jié)構(gòu)不包含任何監(jiān)控。我后來接了一款錯(cuò)誤監(jiān)控工具把 tRPC 的 errors 統(tǒng)一上報(bào)因?yàn)?tRPC 的錯(cuò)誤信息非常規(guī)范有code、message、path這些字段非常適合直接對接到監(jiān)控平臺上。我在src/server/api/trpc.ts的 errorFormatter 里做了一次全局?jǐn)r截export const t initTRPC.contexttypeof createTRPCContext().create({ errorFormatter({ shape, error }) { // 在這里上報(bào)錯(cuò)誤 return shape; }, });這樣線上如果出現(xiàn) Zod 校驗(yàn)失敗、數(shù)據(jù)庫異常、未授權(quán)訪問我都能第一時(shí)間從監(jiān)控后臺看到具體是哪個(gè) procedure 出了問題而不需要等用戶反饋。6. 回顧 t3code 這段時(shí)間的實(shí)際體驗(yàn)用 t3code 做了完整項(xiàng)目之后我有個(gè)很直接的感覺它把全棧開發(fā)里的“隱形稅”砍掉了一大半。以前我要花很多時(shí)間維護(hù)前后端接口文檔、類型聲明、API 封裝現(xiàn)在這些成本降到了接近零寫業(yè)務(wù)代碼的密度變得很高。對我來說它最大的價(jià)值不在代碼生成而在那套類型閉環(huán)帶來的心智負(fù)擔(dān)減輕。當(dāng)然它也不是銀彈。如果你的團(tuán)隊(duì)前后端完全分離后端需要面向第三方開放 API那 tRPC 這套“服務(wù)端和客戶端強(qiáng)綁定”的方式反而會(huì)成為負(fù)擔(dān)。另外T3 Stack 的生態(tài)相對年輕很多企業(yè)級基礎(chǔ)設(shè)施的兼容方案需要自己探索比如前面說的連接池、多環(huán)境數(shù)據(jù)庫遷移、CI/CD 流程都需要你額外搭建。但如果你是單兵作戰(zhàn)或者小團(tuán)隊(duì)想做一個(gè)類型安全、可快速迭代的 Web 應(yīng)用t3code 這套工作流非常值得試一下。剛開始上手時(shí)多花一點(diǎn)時(shí)間把 Prisma schema、tRPC router、NextAuth 的關(guān)系理解透后續(xù)開發(fā)體驗(yàn)的提升會(huì)大大超出你的預(yù)期。最后再分享一個(gè)小技巧。我用 t3code 時(shí)習(xí)慣把項(xiàng)目里所有數(shù)據(jù)庫寫入操作收斂到mutation里并且做好輸入校驗(yàn)和結(jié)果類型聲明。這樣一旦業(yè)務(wù)邏輯要調(diào)整改動(dòng)范圍會(huì)非常小不會(huì)在十幾個(gè)頁面里到處找散落的 set 調(diào)用。這種習(xí)慣配合 t3code 的類型推導(dǎo)讓整個(gè)項(xiàng)目即使經(jīng)過幾個(gè)月的迭代依然保持著比較好的可維護(hù)性。如果你正準(zhǔn)備上手一個(gè)新的全棧項(xiàng)目我建議你從最小閉環(huán)開始——先不急著一次性引入全部模塊把列表查詢和一條數(shù)據(jù)寫入跑通感受一下“類型自己長腳走完全棧”的體驗(yàn)再做后續(xù)擴(kuò)展也不遲。