1. t3code在解決什么問題一次全棧項(xiàng)目選型的真實(shí)算賬t3code是我在GitHub上維護(hù)的一套全棧樣板工程核心思路很樸素把 Next.js、TypeScript、tRPC、Prisma、Tailwind 這五個(gè)工具以類型安全為共同主線串成一個(gè)開箱即用的底座。很多人第一次看到 T3 Stack 會(huì)覺得它是網(wǎng)紅技術(shù)棧真正用起來(lái)才發(fā)現(xiàn)它解決的問題非常具體——前后端聯(lián)調(diào)時(shí)那種接口文檔寫了等于沒寫、改個(gè)字段兩邊同時(shí)炸的尷尬在 t3code 這套架構(gòu)里會(huì)大幅減少。1.1 傳統(tǒng)分工模式里類型斷裂的代價(jià)被低估了先說(shuō)說(shuō)我為什么最終選了這套方案。早幾年做全棧項(xiàng)目最常見的結(jié)構(gòu)是前端一個(gè)倉(cāng)庫(kù)、后端一個(gè)倉(cāng)庫(kù)前端用 Axios 手寫接口調(diào)用后端用 Swagger 出文檔。這種模式在項(xiàng)目小的時(shí)候很順暢一旦業(yè)務(wù)復(fù)雜起來(lái)問題就暴露了后端改了接口返回結(jié)構(gòu)前端只要沒及時(shí)更新類型定義運(yùn)行時(shí)大概率直接拿不到字段。接口文檔要么沒人維護(hù)要么反序列化類型和真實(shí)返回根本對(duì)不上聯(lián)調(diào)階段一半時(shí)間在扯皮。所有接口調(diào)用都得手寫一遍類型聲明一百個(gè)接口就是一百份重復(fù)勞動(dòng)模板代碼多到讓人麻木。t3code 這套東西最核心的思路就是把這些手寫類型的環(huán)節(jié)改成自動(dòng)推導(dǎo)。數(shù)據(jù)庫(kù)表結(jié)構(gòu)由 Prisma 的 schema 定義類型從 schema 生成后端接口由 tRPC 的 router 定義前端調(diào)用方可以直接復(fù)用同一套類型。換句話說(shuō)類型不是人寫的而是從源頭流出來(lái)的。我第一次跑通這條鏈路的時(shí)候感覺最明顯的變化是前后端對(duì)字段的理解從約定變成了編譯期強(qiáng)制。1.2 選型時(shí)我也對(duì)比過(guò)其他方案不只是跟風(fēng)可能有人會(huì)說(shuō)Next.js 自帶 API Route也可以用 GraphQL為什么偏偏選 tRPC我實(shí)際對(duì)比過(guò)幾種方案方案類型穿透能力學(xué)習(xí)成本服務(wù)端緩存/鑒權(quán)靈活性適合場(chǎng)景REST 手寫類型弱需要維護(hù)兩份代碼低高完全自定義團(tuán)隊(duì)已有成熟規(guī)范GraphQL codegen中等需要生成步驟中高中需要自己處理緩存復(fù)雜聚合查詢、多端復(fù)用Next.js API Route fetch弱仍需額外類型層低高簡(jiǎn)單項(xiàng)目夠用tRPC強(qiáng)端到端自動(dòng)推導(dǎo)中理解泛型需要時(shí)間中高procedure 可包裝鑒權(quán)全棧 TypeScript 團(tuán)隊(duì)真實(shí)體驗(yàn)下來(lái)tRPC 并不是萬(wàn)能的。如果你的項(xiàng)目需要給第三方提供公開 API或者前端不只是 Web 端還有大量小程序/移動(dòng)端REST 或者 GraphQL 仍然是更穩(wěn)的選擇。t3code 的定位是內(nèi)部全棧項(xiàng)目尤其是一個(gè)團(tuán)隊(duì)同時(shí)寫前端和后端的場(chǎng)景。類型穿透的優(yōu)勢(shì)在這個(gè)場(chǎng)景下被放到最大而對(duì)外暴露接口的劣勢(shì)則不太重要。1.3 t3code 的邊界感它不是什么都能干我特別想強(qiáng)調(diào)一點(diǎn)t3code 不是拿來(lái)即用的業(yè)務(wù)框架它更像一個(gè)骨架清晰的最小可運(yùn)行系統(tǒng)。你拿它起步能省掉配環(huán)境、折騰連接、搭建目錄結(jié)構(gòu)的瑣碎時(shí)間但業(yè)務(wù)邏輯還是要自己寫。它也不會(huì)替你決定部署方式、數(shù)據(jù)庫(kù)到底用 PostgreSQL 還是 MySQL、組件庫(kù)用哪個(gè)——這些是需要你自己拍板的部分。如果你正處在一個(gè)想試試全棧 TypeScript但不知道從哪下手的狀態(tài)或者被前后端類型不一致的 bug 折磨過(guò)這篇文章接下來(lái)的內(nèi)容會(huì)很有用。我會(huì)把 t3code 的骨架邏輯、一個(gè)真實(shí)功能的落地過(guò)程以及我在生產(chǎn)環(huán)境里踩過(guò)的坑一條一條拆開講。2. 骨架拆解五個(gè)核心成員是怎么咬合在一起的開始實(shí)戰(zhàn)之前有必要先把 t3code 的骨架邏輯講清楚。這五個(gè)工具各司其職但真正讓它們產(chǎn)生化學(xué)反應(yīng)的是彼此之間的接口設(shè)計(jì)。理解了這個(gè)咬合關(guān)系后面遇到報(bào)錯(cuò)時(shí)你能更快判斷問題出在哪一層。2.1 Next.js 是底座App Router 決定了邊界的劃分t3code 基于 Next.js 的 App Router 構(gòu)建。App Router 帶來(lái)的一個(gè)關(guān)鍵變化是服務(wù)端組件和客戶端組件的邊界。服務(wù)端組件在服務(wù)器上執(zhí)行可以直接訪問數(shù)據(jù)庫(kù)、讀取環(huán)境變量代碼不會(huì)打包到瀏覽器?？蛻舳私M件需要標(biāo)記use client在瀏覽器里運(yùn)行負(fù)責(zé)交互邏輯。這個(gè)邊界對(duì)類型安全很重要。t3code 里的 tRPC 在服務(wù)端可以直接調(diào)用在客戶端則需要走一個(gè)專門的 hooks 封裝。你要做的是清晰地區(qū)分哪些邏輯必須在服務(wù)端處理比如直接查庫(kù)、處理密鑰相關(guān)的操作和哪些邏輯必須交給瀏覽器比如點(diǎn)擊事件、表單狀態(tài)。我在剛上手時(shí)經(jīng)常犯的錯(cuò)是把所有組件都寫成客戶端組件導(dǎo)致服務(wù)端該干的事跑到瀏覽器里去干類型倒是沒崩性能和安全性先崩了。2.2 tRPC 是無(wú)文檔的契約tRPC 的特別之處在于它不需要你寫接口文檔也不需要你手寫類型定義。你在服務(wù)端定義了一個(gè) router// server/api/routers/post.ts 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({ orderBy: { createdAt: desc }, }); }), create: publicProcedure .input(z.object({ title: z.string().min(1), content: z.string().optional(), })) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: input }); }), });前端調(diào)用時(shí)類型會(huì)被自動(dòng)推斷出來(lái)連輸入?yún)?shù)的校驗(yàn)規(guī)則都是同一份// app/_components/post-list.tsx use client; import { api } from ~/trpc/react; export function PostList() { const { data: posts, refetch } api.post.list.useQuery(); const createPost api.post.create.useMutation({ onSuccess: () refetch(), }); return ( div {posts?.map((post) ( div key{post.id} h3{post.title}/h3 {post.content p{post.content}/p} /div ))} button onClick{() createPost.mutate({ title: 新文章, content: 內(nèi)容 }) } 新建 /button /div ); }注意這里的api.post.list.useQuery()不是普通的函數(shù)它背后是 React Query 的 hooks。也就是說(shuō)緩存、重試、請(qǐng)求狀態(tài)管理這些邏輯也被 tRPC 的 React 封裝一并處理了不需要你再單獨(dú)引入一套數(shù)據(jù)請(qǐng)求方案。2.3 Prisma 是類型的源頭在 t3code 里數(shù)據(jù)庫(kù)表結(jié)構(gòu)由 Prisma 的 schema 定義。你只要維護(hù)一個(gè)schema.prisma文件Prisma 就能生成對(duì)應(yīng)的 TypeScript 類型和 Client。這意味著數(shù)據(jù)庫(kù)字段變成代碼里的類型這個(gè)環(huán)節(jié)是自動(dòng)的不存在數(shù)據(jù)庫(kù)改了個(gè)字段代碼里忘了同步的問題。generator client { provider prisma-client-js } datasource db { provider postgresql url env(DATABASE_URL) } model Post { id String id default(cuid()) title String content String? createdAt DateTime default(now()) updatedAt DateTime updatedAt }執(zhí)行npx prisma migrate dev之后ctx.db.post.findMany()里返回的post對(duì)象就是帶類型的。這個(gè)類型再被 tRPC 的返回值攜帶一路傳到前端組件整個(gè)鏈路就通了。我在實(shí)際使用中最喜歡的細(xì)節(jié)是改 schema 之后只要重新生成 Prisma Client前端代碼馬上會(huì)報(bào)出所有字段名對(duì)不上的地方這種安全感是傳統(tǒng)接口聯(lián)調(diào)給不了的。2.4 Tailwind 是樣式層但要配合組件規(guī)范Tailwind 在 t3code 里承擔(dān)的是樣式職責(zé)。它本身和上面的類型鏈路關(guān)系不大但它決定了樣板工程的 UI 長(zhǎng)什么樣。我是這么看 Tailwind 的它可以讓你不寫 CSS 文件就完成大部分布局但如果完全靠 utility class 堆頁(yè)面后期維護(hù)會(huì)更吃力。在 t3code 里我會(huì)建議搭配一個(gè)組件庫(kù)比如 shadcn/ui來(lái)收斂樣式原子。Tailwind 負(fù)責(zé)基礎(chǔ)原子類組件庫(kù)負(fù)責(zé)提供結(jié)構(gòu)化的組件業(yè)務(wù)頁(yè)面只關(guān)心數(shù)據(jù)和布局不用每次從零拼按鈕和輸入框。這個(gè)組合用起來(lái)比較順手也不容易出現(xiàn)改一個(gè)按鈕樣式要翻十幾個(gè)文件的窘境。2.5 一張圖看完整鏈路如果把它們的關(guān)系簡(jiǎn)化為一條數(shù)據(jù)流大概是這樣的Prisma Schema → 數(shù)據(jù)庫(kù)表 TypeScript 類型 ↓ tRPC Router → 輸入校驗(yàn) 業(yè)務(wù)邏輯 類型導(dǎo)出 ↓ React Query Hooks → 狀態(tài)管理 緩存 ↓ React 組件 → 渲染與交互這條鏈路的每一個(gè)環(huán)節(jié)類型的承重墻都是自動(dòng)生成的人只負(fù)責(zé)寫業(yè)務(wù)邏輯。理解了這點(diǎn)后面排查問題時(shí)會(huì)非常有用——當(dāng)你看到一個(gè)類型報(bào)錯(cuò)你要判斷的其實(shí)是它發(fā)生在哪一層數(shù)據(jù)庫(kù)層、接口層、還是組件層。3. t3code 實(shí)戰(zhàn)落地從數(shù)據(jù)庫(kù)到頁(yè)面的類型閉環(huán)理論講完接下來(lái)把袖子擼起來(lái)。我用一個(gè)真實(shí)的例子——從初始化項(xiàng)目到實(shí)現(xiàn)一個(gè)帶數(shù)據(jù)庫(kù)寫入和列表展示的完整功能——帶你跑一遍 t3code 的落地過(guò)程。3.1 初始化項(xiàng)目交互式命令行里有哪些選項(xiàng)先說(shuō)明一下如果你要手動(dòng)復(fù)刻 t3code 的結(jié)構(gòu)最直接的方式是用官方腳手架生成一個(gè)同構(gòu)項(xiàng)目npx create-t3-applatest my-app執(zhí)行命令后交互式界面會(huì)問你要不要啟用 Tailwind、tRPC、Prisma、NextAuth 等模塊。我的建議是如果只是學(xué)類型閉環(huán)Prisma 和 tRPC 必須勾上。NextAuth 可以先不勾它處理的是鑒權(quán)邏輯第一次上手時(shí)容易把注意力從類型鏈路上帶偏。Tailwind 建議勾上即使你不用它后續(xù)調(diào)整界面也方便。腳手架生成完之后目錄結(jié)構(gòu)大致是這樣的prisma/ schema.prisma src/ server/ api/ root.ts # 匯總所有子 router routers/ post.ts # 業(yè)務(wù) router trpc.ts # tRPC 實(shí)例與上下文 db.ts # Prisma Client 單例 trpc/ react.tsx # 客戶端 tRPC provider 與 hooks server.ts # 服務(wù)端 tRPC caller可選 app/ api/trpc/[trpc]/ route.ts # tRPC 的 HTTP 入口 _components/ post-list.tsx page.tsx這個(gè)結(jié)構(gòu)本身是 t3code 的核心價(jià)值——它把所有樣板代碼和配置文件都擺好了你不用從空白開始思考tRPC 掛在哪個(gè)文件、Prisma Client 怎么全局共享這類問題。3.2 配置數(shù)據(jù)庫(kù)環(huán)境變量與連接串的講究默認(rèn)情況下腳手架會(huì)用 SQLite 起步但我建議你直接換成 PostgreSQL 或者 MySQL因?yàn)樯a(chǎn)環(huán)境基本不會(huì)用 SQLite。修改prisma/schema.prismadatasource db { provider postgresql url env(DATABASE_URL) }然后在.env里配置DATABASE_URLpostgresql://user:passwordlocalhost:5432/t3code這里有一個(gè)很容易踩的坑不要把包含敏感信息的 .env 文件提交到 Git。腳手架生成的.gitignore通常已經(jīng)幫你把.env排除掉了但如果你是自己手動(dòng)搭的環(huán)境一定要檢查確認(rèn)。數(shù)據(jù)庫(kù)連接串相當(dāng)于數(shù)據(jù)庫(kù)的鑰匙泄露出去就是一個(gè)嚴(yán)重的安全事故。配置好之后在 schema 里加上最簡(jiǎn)單的 Post 模型然后執(zhí)行遷移npx prisma migrate dev --name init這個(gè)命令會(huì)把變更同步到數(shù)據(jù)庫(kù)同時(shí)生成 Prisma Client。如果沒有任何報(bào)錯(cuò)你打開src/server/db.ts里面應(yīng)該是這樣的import { PrismaClient } from prisma/client; const globalForPrisma globalThis as unknown as { prisma?: PrismaClient }; export const db globalForPrisma.prisma ?? new PrismaClient(); if (process.env.NODE_ENV ! production) { globalForPrisma.prisma db; }這個(gè)全局單例的模式很關(guān)鍵。它確保在開發(fā)環(huán)境的模塊熱更新HMR過(guò)程中不會(huì)因?yàn)槊看挝募兏紕?chuàng)建新的 Prisma Client 而導(dǎo)致連接數(shù)暴增。不寫這個(gè)單例開發(fā)到一半你可能會(huì)看到數(shù)據(jù)庫(kù)連接被占滿的警告。3.3 寫第一個(gè) tRPC 接口從 router 到頁(yè)面接下來(lái)定義一個(gè) post router并在根 router 里注冊(cè)// src/server/api/root.ts import { createTRPCRouter } from ~/server/api/trpc; import { postRouter } from ~/server/api/routers/post; export const appRouter createTRPCRouter({ post: postRouter, }); export type AppRouter typeof appRouter;回到之前那個(gè)例子——我們已經(jīng)有l(wèi)ist和create兩個(gè) procedure 了?，F(xiàn)在重點(diǎn)是理解前端如何調(diào)用。在服務(wù)的入口處t3code 已經(jīng)把 HTTP 路由掛好了src/app/api/trpc/[trpc]/route.ts所以前端不需要關(guān)心請(qǐng)求路徑。你只需要在客戶端組件里使用api對(duì)象use client; import { api } from ~/trpc/react; export function PostList() { const utils api.useUtils(); const { data: posts, isLoading } api.post.list.useQuery(); const createPost api.post.create.useMutation({ onSuccess: () utils.post.list.invalidate(), }); if (isLoading) return divLoading.../div; return ( div {posts?.map((post) ( div key{post.id}{post.title}/div ))} button onClick{() createPost.mutate({ title: Hello t3code })} 新增 /button /div ); }這里你可能注意到我沒有用refetch而是用了utils.post.list.invalidate()。這是 React Query 比較推薦的做法讓緩存失效后自動(dòng)重新拉取而不是手動(dòng)觸發(fā)請(qǐng)求。在 t3code 里React Query 的緩存策略可以按業(yè)務(wù)場(chǎng)景定制比如設(shè)置staleTime減少不必要的請(qǐng)求。3.4 類型是怎么流動(dòng)的以及為什么你不會(huì)漏改字段很多人第一次看 t3code 會(huì)有個(gè)疑問前端代碼明明沒有導(dǎo)入任何后端類型為什么posts是帶類型的答案在于 tRPC 的泛型推導(dǎo)。api.post.list.useQuery()的api對(duì)象是createTRPCReactAppRouter()生成的而AppRouter又是typeof appRouter。所以TypeScript 會(huì)把a(bǔ)ppRouter里所有 router 的輸入輸出類型全部推導(dǎo)出來(lái)并注入到前端的 hooks 類型參數(shù)中。這相當(dāng)于一個(gè)全項(xiàng)目的類型地圖前端不需要手動(dòng) import編輯器自動(dòng)補(bǔ)全就能看到返回字段。這套機(jī)制帶來(lái)的實(shí)際效果是如果后端list返回值從{ title: string }變成了{(lán) title: string; content: string }前端除非顯式解構(gòu)字段否則不會(huì)報(bào)錯(cuò)但如果后端改了字段名比如title改成name前端所有用到post.title的地方會(huì)立即標(biāo)紅。這種改錯(cuò)名十分鐘內(nèi)發(fā)現(xiàn)的體驗(yàn)在傳統(tǒng)接口聯(lián)調(diào)里幾乎不敢想。4. 生產(chǎn)環(huán)境最容易翻車的坑和完整的排查鏈路t3code 這套架構(gòu)本地跑得很順但一到生產(chǎn)環(huán)境還是有幾個(gè)高頻問題我一個(gè)個(gè)說(shuō)清楚包括排查思路和解決方案。4.1 數(shù)據(jù)庫(kù)連接被邊緣函數(shù)打滿Prisma 連接池配置如果你把 Next.js 部署到 Vercel 這類邊緣/Serverless 環(huán)境會(huì)遇到一個(gè)特別典型的坑Prisma Client 默認(rèn)創(chuàng)建的連接池和 Serverless 按需啟動(dòng)的短生命周期實(shí)例不匹配?，F(xiàn)象是請(qǐng)求量稍微上來(lái)之后數(shù)據(jù)庫(kù)報(bào)錯(cuò)P1001連接超時(shí)或者后臺(tái)看到大量閑置連接。原因是每個(gè) Serverless 實(shí)例都會(huì)創(chuàng)建自己的 Prisma Client實(shí)例銷毀時(shí)連接池來(lái)不及釋放積少成多。排查鏈路先看日志是不是PrismaClientInitializationError或者連接數(shù)告警。確認(rèn)是否每個(gè) function 實(shí)例都持有了數(shù)據(jù)庫(kù)連接。解決方向有兩個(gè)一個(gè)是在數(shù)據(jù)庫(kù)里把直接連接地址和連接池地址分開一個(gè)是用外置連接池。在我的 t3code 倉(cāng)庫(kù)里推薦的做法是在.env里區(qū)分兩個(gè)變量DATABASE_URLpostgresql://user:passwordhost:5432/db?pgbouncertrueconnection_limit1 DIRECT_URLpostgresql://user:passwordhost:5432/db然后在 schema 里聲明datasource db { provider postgresql url env(DATABASE_URL) directUrl env(DIRECT_URL) }DATABASE_URL走連接池適合 Prisma Client 在 Serverless 環(huán)境里頻繁創(chuàng)建連接DIRECT_URL走直連適合執(zhí)行遷移命令時(shí)使用。遷移的時(shí)候不需要連接池直連更可靠。4.2 tRPC 類型不同步兩端的版本斷裂t3code 的強(qiáng)項(xiàng)是類型穿透但如果你把前后端拆成兩個(gè)倉(cāng)庫(kù)部署或者一個(gè)倉(cāng)庫(kù)里前后端依賴版本不一致就會(huì)出現(xiàn)后端新加了一個(gè) procedure前端類型卻沒更新的情況。這種斷裂在 monorepo 結(jié)構(gòu)里尤其常見。典型報(bào)錯(cuò)是前端調(diào)用api.xxx.yyy時(shí)TypeScript 提示Property yyy does not exist on type ...。排查鏈路確認(rèn)是否運(yùn)行過(guò)npm install確保trpc/server和trpc/react-query版本一致。確認(rèn)src/server/api/root.ts里新 router 有沒有正確注冊(cè)。清掉 TypeScript 的增量緩存npx tsc --noEmit如果仍報(bào)錯(cuò)再看編輯器里的 TypeScript 服務(wù)是否舊緩存重啟 TS Server。如果你用了 monorepo檢查子包之間的依賴是否指向了舊構(gòu)建產(chǎn)物必要時(shí)重新 build。這類問題的根源基本不在代碼而在類型生成層沒有同步。我建議把prisma generate和類型檢查放進(jìn) CI 流程任何一步?jīng)]跑過(guò)都不允許合并。4.3 App Router 的use client邊界錯(cuò)誤使用帶來(lái)的混亂App Router 出現(xiàn)之后哪些組件能直接用 tRPC hooks成了新問題。tRPC 的 React hooks 依賴客戶端狀態(tài)React Query 的 Provider所以只能在客戶端組件里調(diào)用。但是很多新手會(huì)把整個(gè)頁(yè)面都標(biāo)成use client導(dǎo)致服務(wù)端組件完全失效首屏渲染變成瀏覽器渲染性能明顯下滑。正確做法是頁(yè)面外殼保持服務(wù)端組件只有需要交互的葉子組件按鈕、表單、列表容器單獨(dú)標(biāo)記use client。比如在 t3code 里一個(gè)典型的服務(wù)端頁(yè)面骨架// app/page.tsx服務(wù)端組件 import { PostList } from ./_components/post-list; export default function HomePage() { return ( main h1文章列表/h1 PostList / /main ); }而PostList內(nèi)部才是一個(gè)客戶端組件。這樣做的好處是頁(yè)面首屏可以靜默渲染只有列表區(qū)域在客戶端進(jìn)行交互。如果你發(fā)現(xiàn)自己把use client寫到了頁(yè)面最頂層就要停下來(lái)想想是不是所有代碼都真的需要運(yùn)行在瀏覽器上。排查思路用 React DevTools 看組件是否被正確區(qū)分為 Server/Client用構(gòu)建產(chǎn)物檢查瀏覽器 bundle 的大小如果服務(wù)端代碼被打進(jìn)去了邊界就出問題了。4.4 Zod 校驗(yàn)失敗時(shí)的模糊報(bào)錯(cuò)tRPC 的輸入校驗(yàn)依賴 Zod。當(dāng)你傳的參數(shù)不合法時(shí)報(bào)錯(cuò)信息有時(shí)會(huì)比較原始尤其是嵌套對(duì)象里的字段名錯(cuò)誤容易看得一頭霧水。我踩過(guò)的一個(gè)典型例子createPost.mutate({ title: });z.string().min(1)會(huì)拋錯(cuò)但如果你沒有配置全局錯(cuò)誤處理或者前端顯示邏輯用戶只會(huì)看到一個(gè)籠統(tǒng)的錯(cuò)誤。解決辦法是在客戶端統(tǒng)一做錯(cuò)誤映射const createPost api.post.create.useMutation({ onError: (err) { const message err.shape?.message ?? 請(qǐng)求失敗; // 在這里把 message 展示給用戶 }, });生產(chǎn)環(huán)境里我建議前端對(duì)用戶輸入先做一層 UI 校驗(yàn)比如禁用按鈕、提示必填Zod 校驗(yàn)作為后端兜底。這樣既保證用戶體驗(yàn)流暢也不會(huì)依賴后端錯(cuò)誤提示的文案質(zhì)量。5. 部署收尾連接池、邊緣函數(shù)與構(gòu)建配置最后聊聊把 t3code 從開發(fā)機(jī)推到生產(chǎn)環(huán)境時(shí)我在部署層面整理的幾條經(jīng)驗(yàn)。5.1 數(shù)據(jù)庫(kù)連接方案按部署環(huán)境區(qū)分前面已經(jīng)提到連接池的問題這里再細(xì)化一下。在生產(chǎn)環(huán)境我通常給數(shù)據(jù)庫(kù)配置兩個(gè)連接地址DATABASE_URL給應(yīng)用運(yùn)行時(shí)使用走連接池比如通過(guò)外部連接池服務(wù)或者數(shù)據(jù)庫(kù)自帶的連接池端口。DIRECT_URL給prisma migrate deploy這類遷移命令使用直連更穩(wěn)定。如果是 PostgreSQL還建議設(shè)置合理的connection_limit。在 Serverless 場(chǎng)景下單個(gè)實(shí)例的并發(fā)請(qǐng)求數(shù)通常很小connection_limit1是合理的起點(diǎn)。不要把它設(shè)得太大否則實(shí)例一多連接數(shù)會(huì)迅速膨脹。5.2 構(gòu)建階段的類型檢查不要跳過(guò)t3code 的腳手架在構(gòu)建時(shí)會(huì)默認(rèn)跑tsc --noEmit和next build。很多人嫌慢會(huì)在 CI 里把類型檢查關(guān)掉這是個(gè)典型隱患。類型安全是這個(gè)架構(gòu)的地基如果構(gòu)建階段不檢查類型等于把自動(dòng)推導(dǎo)的優(yōu)勢(shì)白白扔掉了。我的建議是本地開發(fā)npm run dev可以跳過(guò)完整類型檢查保證熱更新速度。CI/生產(chǎn)構(gòu)建必須跑npm run build它會(huì)執(zhí)行完整類型檢查。首次啟動(dòng)慢一點(diǎn)沒關(guān)系換來(lái)的是類型斷裂不會(huì)悄悄溜進(jìn)生產(chǎn)。5.3 邊緣運(yùn)行時(shí)Edge Runtime和 Node 運(yùn)行時(shí)的選擇Next.js 頁(yè)面可以配置為 Edge Runtime 或 Node.js Runtime。tRPC 和 Prisma 有一些生態(tài)兼容性差異尤其是 Prisma它依賴 Node 的部分原生能力和 Edge Runtime 的兼容性并不總是理想。我的經(jīng)驗(yàn)是如果用了 Prisma就老老實(shí)實(shí)用 Node.js Runtime。Edge Runtime 的優(yōu)勢(shì)在于全球低延遲響應(yīng)但前提是你的數(shù)據(jù)層也要跟著駐留邊緣否則請(qǐng)求最終還是得回源到數(shù)據(jù)庫(kù)所在區(qū)域優(yōu)化效果非常有限。在 t3code 里我會(huì)讓 API 路由和頁(yè)面都使用默認(rèn)的 Node.js Runtime優(yōu)先保證穩(wěn)定性和功能完整。5.4 環(huán)境變量的三個(gè)必須部署到托管平臺(tái)不管 Vercel、Netlify 還是自建 Node 服務(wù)環(huán)境變量都要單獨(dú)檢查一遍漏掉任何一個(gè)都會(huì)在運(yùn)行時(shí)出問題。我的檢查清單是DATABASE_URL和DIRECT_URL是否正確指向生產(chǎn)數(shù)據(jù)庫(kù)。NODE_ENV是否自動(dòng)設(shè)置為production大多數(shù)平臺(tái)會(huì)自動(dòng)處理。是否有任何第三方服務(wù)的密鑰、公開地址被硬編碼進(jìn)代碼里。另外有一點(diǎn)要特別提醒前端的構(gòu)建產(chǎn)物里不要包含任何服務(wù)端密鑰。Next.js 里只有以NEXT_PUBLIC_開頭的環(huán)境變量才會(huì)被打進(jìn)瀏覽器 bundle其他變量只在服務(wù)器端可見。在 t3code 里數(shù)據(jù)庫(kù)連接串永遠(yuǎn)不要以NEXT_PUBLIC_開頭否則等于把數(shù)據(jù)庫(kù)鑰匙掛在門口。最后聊幾句實(shí)際使用感受如果你現(xiàn)在正在糾結(jié)要不要仿照 t3code 的方式搭業(yè)務(wù)我的個(gè)人建議是先在一個(gè)小項(xiàng)目上試水而不要一上來(lái)就全量遷移。t3code 這套架構(gòu)的好處是類型安全和開發(fā)體驗(yàn)代價(jià)是你需要習(xí)慣所有東西都要先定義類型的思路。有些同學(xué)剛開始會(huì)覺得麻煩但跑通第一個(gè)功能后大多數(shù)人回不去手寫接口類型的日子。小技巧放最后開發(fā)時(shí)如果你發(fā)現(xiàn)編輯器卡頓或者類型提示不更新先試試重啟 TypeScript 服務(wù)如果問題還在再清node_modules/.cache。這類問題八成不是代碼錯(cuò)誤而是 TypeScript 的增量緩存和 tRPC 的復(fù)雜泛型在較老的 IDE 版本上鬧脾氣。換新版本或者升級(jí)依賴后通常就好了。