：打造端到端類型安全的全棧應用)
我起項目代號很隨意但工具鏈一點都不隨意。t3code這個項目名來自我去年在團隊內部做技術分享時隨手起的代號——t3取自T3 Stackcode則因為整個項目從數(shù)據(jù)層到界面層全部圍繞類型安全的代碼鏈路展開。說白了t3code就是我基于TypeScript、Next.js、tRPC、Prisma、Tailwind這套組合從零搭起來的一個全棧Web應用示例項目用來驗證“端到端類型安全”到底能在真實業(yè)務里省多少事。如果你正打算選型一套前后端分離但又不愿意維護雙端類型定義的項目或者想看看T3 Stack在實際落地時有哪些坑和細節(jié)這篇就當一次同事間的技術復盤看。我會把項目的設計思路、核心鏈路、實操步驟以及我踩過的真實問題全部鋪開講代碼片段可以直接拿去改。1. 項目整體設計與技術選型1.1 為什么選T3 Stack這套組合先說結論T3 Stack不是框架不是官方發(fā)布的東西它是一套由社區(qū)主導的最佳實踐組合。核心哲學很直白——能不用JavaScript的地方就不用JavaScript全部換TypeScript讓類型從數(shù)據(jù)庫一直灌到瀏覽器里。我在做t3code之前用過常規(guī)的REST API方案寫過GraphQL方案也試過純服務端渲染加少量交互的方案但總會遇到同一個毛病改了后端字段前端要手動同步類型定義漏一次就是線上運行時才發(fā)現(xiàn)Bug。T3 Stack恰好解決了這個痛點。它把Next.js當應用骨架Prisma做數(shù)據(jù)庫映射tRPC替代REST和GraphQLNextAuth做認證Tailwind負責樣式最后用TypeScript把所有環(huán)節(jié)粘起來。從Prisma的model定義出發(fā)類型直接推導到tRPC的返回值再通過React Query的hooks傳到組件props全程你不寫一行手動的interface編輯器都能給你提示字段錯誤。這對一個以“少寫重復代碼”為目標的項目來說幾乎是降維打擊。選它還有一個實際原因社區(qū)生態(tài)足夠成熟。T3相關的關鍵詞在GitHub上能搜出大量模板和討論遇到問題有現(xiàn)成的排查思路不像某些新興框架連文檔都不全。t3code的定位是“生產級示例”所以我更看重穩(wěn)定性和可維護性而不是炫技。1.2 技術棧逐項拆解與分工t3code用到的核心依賴如下模塊選型職責框架Next.js 14App Router模式服務端渲染、路由、API層承載語言TypeScript 5.x全鏈路靜態(tài)類型檢查數(shù)據(jù)庫ORMPrisma 5.x數(shù)據(jù)建模、遷移、查詢RPC層tRPC 10.x前后端類型安全的API調用數(shù)據(jù)請求TanStack Query 5.x緩存的client端狀態(tài)管理認證NextAuth.jsAuth.js登錄會話與OAuth授權樣式Tailwind CSS 3.x原子化CSS與響應式布局這個分工最舒服的地方在于每個工具都只管自己最擅長的事Next.js負責渲染與路由的框架邏輯Prisma不碰業(yè)務邏輯只做數(shù)據(jù)映射tRPC不代替業(yè)務框架只做類型安全的函數(shù)調用Tailwind不管數(shù)據(jù)只負責樣式。層與層之間的邊界非常干凈定位問題的時候能快速縮小范圍。1.3 腳手架初始化與工程規(guī)范t3code初始化用的是Create T3 App的標準命令npm create t3-applatest t3code交互式選項里我按項目需要勾選了Next.js、Tailwind、tRPC、Prisma、NextAuth把ESLint也帶上。初始化完目錄結構已經有了基礎的“三段式”分層src/ app/ // Next.js App Router的頁面與布局 server/ // api路由、auth配置、db實例、tRPC根路由 trpc/ // tRPC的客戶端封裝與server返回類型 prisma/ schema.prisma // 數(shù)據(jù)模型定義這里有個容易忽略的細節(jié)Create T3 App生成的項目默認使用嚴格模式的TypeScript配置noUncheckedIndexedAccess也是開的。這意味著你不能隨便用array[0]而不處理undefined。剛開始會有點煩但適應之后代碼質量確實高了不少很多運行時錯誤在設計期就被堵住了。2. 核心鏈路類型安全的數(shù)據(jù)流設計2.1 Prisma數(shù)據(jù)建模與遷移策略t3code的業(yè)務模型我設計得比較簡單——模擬一個帶用戶系統(tǒng)的內容管理場景有User、Post、Comment三個核心實體。先看最關鍵的Prisma schemamodel User { id String id default(cuid()) name String? email String unique emailVerified DateTime? image String? posts Post[] comments Comment[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Post { id String id default(cuid()) title String content String published Boolean default(false) author User relation(fields: [authorId], references: [id]) authorId String comments Comment[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Comment { id String id default(cuid()) content String post Post relation(fields: [postId], references: [id], onDelete: Cascade) postId String author User relation(fields: [authorId], references: [id]) authorId String createdAt DateTime default(now()) }我選擇cuid()作為主鍵而不是自增整數(shù)主要是考慮到數(shù)據(jù)可能在多個環(huán)境間遷移、合并CUID能避免沖突。值得注意的是外鍵關系一定要明確寫onDelete策略。比如評論關聯(lián)帖子帖子刪除時評論應該一起刪這里就配置了onDelete: Cascade否則數(shù)據(jù)庫層面會限制刪除操作業(yè)務里就要額外寫清理邏輯。遷移我習慣用prisma migrate dev在本地開發(fā)生產環(huán)境則用prisma migrate deploynpx prisma migrate dev --name init_t3code npx prisma migrate deploy2.2 tRPC路由劃分與類型推導機制tRPC的核心思想是后端導出的router類型前端直接就能推斷出來。t3code的tRPC架構是標準的“根路由聚合子路由”模型// src/server/api/root.ts export const appRouter router({ post: postRouter, user: userRouter, comment: commentRouter, }); export type AppRouter typeof appRouter;每個子路由內部再拆procedure// src/server/api/routers/post.ts import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ all: publicProcedure.query(async ({ ctx }) { return ctx.db.post.findMany({ where: { published: true }, orderBy: { createdAt: desc }, include: { author: { select: { name: true, image: true } } }, }); }), byId: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx }) { return ctx.db.post.findUnique({ where: { id: input.id }, include: { comments: { include: { author: true } } }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1) })) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id }, }); }), });注意這里的publicProcedure和protectedProcedure是區(qū)分權限的關鍵。t3code在createTRPCContext里注入了當前session若用戶未登錄protectedProcedure會直接拋401前端拿到錯誤后就能跳轉登錄頁。這樣的好處是權限控制不再散落在每個API handler里而是通過“中間件”統(tǒng)一治理。2.3 client端React Query的自動生成與緩存tRPC最爽的使用體驗在前端。初始化時通過createTRPCReact創(chuàng)建hooks類型自動從AppRouter推導// src/trpc/react.tsx import { createTRPCReact } from trpc/react-query; export const api createTRPCReactAppRouter();頁面里直接用const { data, refetch } api.post.all.useQuery(); const createPost api.post.create.useMutation({ onSuccess: () { utils.post.all.invalidate(); }, });useMutation的onSuccess里調用invalidate()刪除或創(chuàng)建數(shù)據(jù)后自動觸發(fā)相關查詢的重新拉取。這是React Query最核心的緩存機制幾乎不用手動管理loading狀態(tài)比手工寫fetch然后自己setState要省太多。建議新手重點理解失效invalidate和緩存命中兩個概念這是和傳統(tǒng)fetch方案最大的分水嶺。3. 實操過程與核心環(huán)節(jié)實現(xiàn)3.1 認證模塊NextAuth接入與自定義登錄t3code默認集成了NextAuth但要讓它跑起來有幾個必填環(huán)境變量DATABASE_URLpostgresql://... NEXTAUTH_SECRET生成一串隨機字符串 NEXTAUTH_URLhttp://localhost:3000我強烈建議用openssl rand -base64 32生成NEXTAUTH_SECRET不要自己編一個短字符串否則生產環(huán)境會告警。NextAuth的配置集中在src/server/auth.tsexport const authOptions: NextAuthOptions { providers: [ GitHubProvider({ clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, }), ], callbacks: { session({ session, user }) { return { ...session, user: { ...session.user, id: user.id } }; }, }, };理論上到這里GitHub登錄就能用了但實際落地時還有一個坑NextAuth默認的session類型里沒有user.id需要自己擴展類型聲明。我會在src/types/next-auth.d.ts里寫declare module next-auth { interface Session { user: { id: string; name?: string | null; email?: string | null; image?: string | null; }; } }不補這個類型ctx.session.user.id在tRPC里會直接報類型錯誤。這個細節(jié)教程里很少提到但幾乎所有基于NextAuth tRPC的項目都會遇到。3.2 核心頁面與SSR數(shù)據(jù)加載策略t3code里我寫了三個主要頁面首頁帖子列表、單個帖子詳情、個人中心。每個頁面的數(shù)據(jù)加載策略不一樣這是Next.js App Router模式下需要仔細權衡的點。首頁用服務端組件直接調tRPC是不行的因為App Router的服務端組件不能直接使用基于React Query的tRPC hooks。正確做法是調用tRPC的server端函數(shù)// src/app/page.tsx import { api } from ~/trpc/server; export default async function HomePage() { const posts await api.post.all.query(); return PostList initialPosts{posts} /; }詳情頁則可以在Server Component里通過動態(tài)路由參數(shù)調用api.post.byId.query({ id })這樣首屏HTML直接包含完整數(shù)據(jù)SEO友好不用客戶端再等一個loading。個人中心需要登錄后展示自己的帖子這種情況我選擇“混合策略”外殼用Server Component判斷session內部交互組件用Client Component tRPC query。這個邊界要分清楚Server Component負責首屏靜態(tài)數(shù)據(jù)Client Component負責需要交互的查詢和mutation。3.3 環(huán)境變量管理與多環(huán)境部署t3code用了三個環(huán)境文件來管理不同階段的配置.env.example # 模板提交到倉庫 .env.development # 本地開發(fā) .env.production # 線上部署一個重要的安全習慣.env.example里只寫鍵名和占位符真正的密鑰永遠不要提交到Git倉庫。我在項目根目錄放了.gitignore默認會忽略所有.env*但如果你把.env.example也忽略了隊友拉代碼就會一臉懵。建議做兩件事保留.env.example進倉庫手動在.gitignore里加一行!.env.example。生產部署我用的是Vercel Postgres托管Vercel平臺對Next.js的支持確實省心連接數(shù)據(jù)庫只需要在平臺環(huán)境變量面板里把DATABASE_URL和兩個認證密鑰填上。如果要部署到自建服務器則用Dockerfile構建FROM node:20-alpine AS base RUN npm i -g pnpm WORKDIR /app FROM base AS deps COPY package.json pnpm-lock.yaml ./ RUN pnpm install --frozen-lockfile FROM base AS build COPY --fromdeps /app/node_modules ./node_modules COPY . . RUN pnpm prisma generate pnpm build FROM node:20-alpine AS runner COPY --frombuild /app/.next/standalone ./ COPY --frombuild /app/.next/static ./.next/static CMD [node, server.js]Docker部署時務必注意Prisma的query engine是平臺相關的二進制在alpine鏡像里需要額外安裝openssl兼容層否則跑起來報錯Query engine library for current platform linux-musl could not be found。如果你不想折騰原生依賴直接用Vercel這類托管平臺能省掉這個煩惱。4. 常見問題與排查技巧實錄4.1 tRPC調用報500錯誤但日志空白這是我在t3code開發(fā)中遇到最多的一類問題。tRPC的錯誤處理默認會把具體錯誤信息藏在response里但如果你開了Next.js的production模式日志里可能只顯示一行Error: Internal Server Error看不到stack trace排錯效率極低。排查思路分三步走。先看network響應體的error.data字段tRPC會把錯誤堆棧放在data.stack里。如果響應體也是空的那就去服務端日志里找Prisma的查詢報錯。還有一個高頻原因在Server Component里直接調api.post.all.query()時忘記給context傳入session導致ctx.session為null。解決方法是給createTRPCContext里做空值兜底export const createTRPCContext (opts: CreateNextContextOptions) { const session getServerSession(authOptions); return { db, session: session ?? null }; };然后protectedProcedure內部通過middleware拋錯而不是在context構建階段就崩潰。這樣至少錯誤信息能正確分類為UNAUTHORIZED而不是籠統(tǒng)的500。4.2 Prisma migrate產生歷史分叉多人協(xié)作時如果你本地的_prisma_migrations歷史記錄和主線不一致prisma migrate dev會報“migration history is diverged”。我實操中的快速處理方式是確認數(shù)據(jù)庫當前狀態(tài)沒問題保存現(xiàn)有數(shù)據(jù)后重置遷移記錄npx prisma migrate reset --force --skip-seed npx prisma migrate dev但reset會清空數(shù)據(jù)所以在非本地環(huán)境千萬別直接跑這條命令。更穩(wěn)妥的做法是刪掉本地prisma/migrations目錄里多余的歷史遷移文件只保留與生產一致的基線再重新生成一個合并遷移。另外生產環(huán)境數(shù)據(jù)庫我一般會額外做每日備份保證出問題時能回滾。4.3 Tailwind響應式樣式不生效Tailwind的類名在t3code里偶爾會出現(xiàn)“編譯了但樣式沒生效”的情況。最常見的原因是把動態(tài)拼接的類名寫進了模板字符串比如className{bg-${color}-500}。Tailwind的掃描器在構建時靜態(tài)識別類名字符串動態(tài)拼接的類名會被直接跳過不會生成對應CSS。解決辦法是使用完整的類名映射表const colorClasses { red: bg-red-500 hover:bg-red-600, blue: bg-blue-500 hover:bg-blue-600, }; button className{colorClasses[color]} /另外一個容易踩的坑是App Router里給服務端組件賦值use client組件或者反過來。如果你在layout.tsx里用了一個Client Component包裹內容且這個Client Component沒有匹配好SSR和客戶端渲染條件會出現(xiàn)首屏FOUC閃白。t3code里我把所有“需登錄才顯示”的導航區(qū)塊單獨隔離成Client Component避免把整個layout強行標記成客戶端渲染。4.4 生產環(huán)境首屏接口過慢與緩存優(yōu)化t3code上線內測時發(fā)現(xiàn)帖子列表頁的首屏加載在弱網環(huán)境下需要2秒以上。排查后定位到兩個瓶頸一是首頁query串行請求了作者信息二是沒有做靜態(tài)緩存。優(yōu)化方案是Prisma查詢里用select按需取字段避免include整張關聯(lián)表include: { author: { select: { name: true, image: true }, // 只取需要字段 }, }同時對于“按時間排序的文章列表”這類很少變化的接口我在Next.js里聲明了revalidate 60讓頁面每分鐘增量重新生成一次靜態(tài)結果。tRPC的server調用本身不受影響但Next.js緩存層就能把大部分請求擋住200并發(fā)壓測下響應時間從1.8秒降到了200毫秒左右。注意如果用cookies()或headers()讀取請求上下文Next.js會自動禁用靜態(tài)緩存所以“純公開數(shù)據(jù)”的部分才適合加revalidate。4.5 常見問題速查表現(xiàn)象直接原因快速解法類型報錯Property id does not exist on type Session沒有擴展NextAuth類型聲明添加next-auth.d.ts并覆蓋Session接口Prisma報Environment variable not found: DATABASE_URL環(huán)境變量未加載檢查.env文件位置是否在項目根目錄重新sourcetRPC mutation成功但頁面不更新缺少invalidate操作在mutation的onSuccess里調用相關的invalidate()Tailwind類名顏色不生效動態(tài)拼接類名改成完整類名映射表部署到Docker后Prisma engine報錯alpine缺少平臺依賴用slim鏡像或安裝openssl兼容層NextAuth登錄后session為空NEXTAUTH_SECRET未配置設置32字節(jié)以上的隨機字符串5. 一條龍上線的完整復盤5.1 開發(fā)階段容易忽略的配置細節(jié)如果你準備完整照著t3code的思路復刻有四個配置細節(jié)我建議從一開始就做對。第一tsconfig.json里打開strict和noUncheckedIndexedAccess雖然前期會多寫很多空值判斷但等代碼規(guī)模上來之后這個決定能幫你擋住大量邊界Bug。第二ESLint配置里加上typescript-eslint的推薦規(guī)則t3code的腳手架默認帶了別手滑刪掉。它能在你寫異步邏輯時提示未處理Promise這類錯誤在運行時往往最難定位。第三Prisma的url使用connection pooler還是直連要提前想清楚。我踩過的坑是在Serverless環(huán)境用直連Postgres短連接被數(shù)據(jù)庫拒絕。如果是Vercel Postgres一定要把DATABASE_URL配置成連接池地址否則并發(fā)請求一多就會報連接數(shù)超限。第四所有需要登錄的tRPC mutation入?yún)⒗锒疾灰湃吻岸藗鱽淼膗serId必須從ctx.session.user.id拿。t3code一開始我在一個更新資料的mutation里直接把前端userId作為設置項測試時發(fā)現(xiàn)可以任意改別人數(shù)據(jù)后來全部改成了session取值。這個原則要寫進團隊規(guī)范。5.2 代碼組織與團隊協(xié)作方式t3code項目規(guī)模并不大但代碼組織我刻意按照“可擴展”的方式規(guī)劃。tRPC路由器的目錄命名直接對標業(yè)務模塊比如postRouter對應整個帖子模塊頁面組件命名和路由保持一致。這樣加到第三個業(yè)務模塊時只需新開一個router文件改一下root.ts聚合即可完全不影響已有功能。同類型項目協(xié)作時我見過團隊糾結“到底用React Query還是SWR”“用zod還是yup”。實際體驗下來tRPC官方綁定的React Query和zod已經是一套非常順手的組合不要在中途替換。因為zod不僅僅做入?yún)⑿ｒ炈念愋屯茖芰χ苯颖籺RPC用來生成procedure的入?yún)㈩愋蛽Q掉yup就等于放棄了這個核心鏈路的類型安全。5.3 項目上線后我要干什么t3code這個項目上線后我第一件事是注冊了日志監(jiān)控和錯誤上報服務。tRPC的錯誤默認會以TRPCClientError結構被前端捕獲但這些只能看到“用戶視角的錯誤”服務端堆棧對用戶沒有意義需要自動上報到后臺。我接入了錯誤捕獲服務后很快就發(fā)現(xiàn)了一個“評論創(chuàng)建成功但頁面數(shù)據(jù)不刷新”的問題用戶反饋前就已經通過日志定位到了——又是invalidate調用順序寫錯了把這個操作放在了mutate之后立即執(zhí)行但API請求還沒完全落地。按照我的經驗項目上線后的前兩周是最容易暴露問題的階段。那些開發(fā)環(huán)境重現(xiàn)不了、從用戶側看到的偶發(fā)問題90%都是環(huán)境變量缺失、依賴版本不一致、數(shù)據(jù)庫權限不夠這類“基礎配置”問題而不是業(yè)務邏輯問題。所以t3code的部署腳本里我用GitHub Actions把所有代碼質量檢查、Prisma migrate deploy、構建產物串到了一起合并到main分支時自動跑一遍配置錯了會在構建階段就攔下來。5.4 后續(xù)可以擴展的方向t3code現(xiàn)在跑得挺穩(wěn)但我心里有個擴展清單。短期計劃是加上文件上傳圖片存在對象存儲里數(shù)據(jù)庫只保存訪問路徑Prisma的字段類型改成String前端用帶簽名的URL訪問。中期計劃是加一個基于角色的權限管理在session里注入role字段tRPC procedure里加一個requireRole(admin)中間件對評論審核、內容刪除等操作做權限控制。長期計劃是把server端抽成獨立的BFF服務和移動端共享同一套tRPC路由真正做到一套類型定義覆蓋Web和App兩端。這些方向都是t3code現(xiàn)在這個架構天然支持的因為類型安全的底子打好了加功能不再是“粘貼代碼修類型錯誤”而是“寫好業(yè)務邏輯讓類型檢查替你兜底”。這也是我做完這個項目后最大的體會投資在數(shù)據(jù)鏈路的類型安全上比任何測試補充都更能長期受益。最后再分享一個小技巧t3code項目的package.json里我加了一個db:studio的腳本本地開發(fā)時一鍵啟動Prisma Studio可以直接瀏覽和修改數(shù)據(jù)庫數(shù)據(jù)。調試數(shù)據(jù)相關問題時這個工具比寫一堆腳本高效得多。如果你是第一次嘗試T3 Stack組合建議先把整個鏈路跑通一遍——從創(chuàng)建模型、遷移數(shù)據(jù)庫、查詢數(shù)據(jù)到在頁面上渲染出來走完這一步你對這套組合的信心會翻倍。 T3 Stack實戰(zhàn)：打造端到端類型安全的全棧應用
我起項目代號很隨意但工具鏈一點都不隨意。t3code這個項目名來自我去年在團隊內部做技術分享時隨手起的代號——t3取自T3 Stackcode則因為整個項目從數(shù)據(jù)層到界面層全部圍繞類型安全的代碼鏈路展開。說白了t3code就是我基于TypeScript、Next.js、tRPC、Prisma、Tailwind這套組合從零搭起來的一個全棧Web應用示例項目用來驗證“端到端類型安全”到底能在真實業(yè)務里省多少事。如果你正打算選型一套前后端分離但又不愿意維護雙端類型定義的項目或者想看看T3 Stack在實際落地時有哪些坑和細節(jié)這篇就當一次同事間的技術復盤看。我會把項目的設計思路、核心鏈路、實操步驟以及我踩過的真實問題全部鋪開講代碼片段可以直接拿去改。1. 項目整體設計與技術選型1.1 為什么選T3 Stack這套組合先說結論T3 Stack不是框架不是官方發(fā)布的東西它是一套由社區(qū)主導的最佳實踐組合。核心哲學很直白——能不用JavaScript的地方就不用JavaScript全部換TypeScript讓類型從數(shù)據(jù)庫一直灌到瀏覽器里。我在做t3code之前用過常規(guī)的REST API方案寫過GraphQL方案也試過純服務端渲染加少量交互的方案但總會遇到同一個毛病改了后端字段前端要手動同步類型定義漏一次就是線上運行時才發(fā)現(xiàn)Bug。T3 Stack恰好解決了這個痛點。它把Next.js當應用骨架Prisma做數(shù)據(jù)庫映射tRPC替代REST和GraphQLNextAuth做認證Tailwind負責樣式最后用TypeScript把所有環(huán)節(jié)粘起來。從Prisma的model定義出發(fā)類型直接推導到tRPC的返回值再通過React Query的hooks傳到組件props全程你不寫一行手動的interface編輯器都能給你提示字段錯誤。這對一個以“少寫重復代碼”為目標的項目來說幾乎是降維打擊。選它還有一個實際原因社區(qū)生態(tài)足夠成熟。T3相關的關鍵詞在GitHub上能搜出大量模板和討論遇到問題有現(xiàn)成的排查思路不像某些新興框架連文檔都不全。t3code的定位是“生產級示例”所以我更看重穩(wěn)定性和可維護性而不是炫技。1.2 技術棧逐項拆解與分工t3code用到的核心依賴如下模塊選型職責框架Next.js 14App Router模式服務端渲染、路由、API層承載語言TypeScript 5.x全鏈路靜態(tài)類型檢查數(shù)據(jù)庫ORMPrisma 5.x數(shù)據(jù)建模、遷移、查詢RPC層tRPC 10.x前后端類型安全的API調用數(shù)據(jù)請求TanStack Query 5.x緩存的client端狀態(tài)管理認證NextAuth.jsAuth.js登錄會話與OAuth授權樣式Tailwind CSS 3.x原子化CSS與響應式布局這個分工最舒服的地方在于每個工具都只管自己最擅長的事Next.js負責渲染與路由的框架邏輯Prisma不碰業(yè)務邏輯只做數(shù)據(jù)映射tRPC不代替業(yè)務框架只做類型安全的函數(shù)調用Tailwind不管數(shù)據(jù)只負責樣式。層與層之間的邊界非常干凈定位問題的時候能快速縮小范圍。1.3 腳手架初始化與工程規(guī)范t3code初始化用的是Create T3 App的標準命令npm create t3-applatest t3code交互式選項里我按項目需要勾選了Next.js、Tailwind、tRPC、Prisma、NextAuth把ESLint也帶上。初始化完目錄結構已經有了基礎的“三段式”分層src/ app/ // Next.js App Router的頁面與布局 server/ // api路由、auth配置、db實例、tRPC根路由 trpc/ // tRPC的客戶端封裝與server返回類型 prisma/ schema.prisma // 數(shù)據(jù)模型定義這里有個容易忽略的細節(jié)Create T3 App生成的項目默認使用嚴格模式的TypeScript配置noUncheckedIndexedAccess也是開的。這意味著你不能隨便用array[0]而不處理undefined。剛開始會有點煩但適應之后代碼質量確實高了不少很多運行時錯誤在設計期就被堵住了。2. 核心鏈路類型安全的數(shù)據(jù)流設計2.1 Prisma數(shù)據(jù)建模與遷移策略t3code的業(yè)務模型我設計得比較簡單——模擬一個帶用戶系統(tǒng)的內容管理場景有User、Post、Comment三個核心實體。先看最關鍵的Prisma schemamodel User { id String id default(cuid()) name String? email String unique emailVerified DateTime? image String? posts Post[] comments Comment[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Post { id String id default(cuid()) title String content String published Boolean default(false) author User relation(fields: [authorId], references: [id]) authorId String comments Comment[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Comment { id String id default(cuid()) content String post Post relation(fields: [postId], references: [id], onDelete: Cascade) postId String author User relation(fields: [authorId], references: [id]) authorId String createdAt DateTime default(now()) }我選擇cuid()作為主鍵而不是自增整數(shù)主要是考慮到數(shù)據(jù)可能在多個環(huán)境間遷移、合并CUID能避免沖突。值得注意的是外鍵關系一定要明確寫onDelete策略。比如評論關聯(lián)帖子帖子刪除時評論應該一起刪這里就配置了onDelete: Cascade否則數(shù)據(jù)庫層面會限制刪除操作業(yè)務里就要額外寫清理邏輯。遷移我習慣用prisma migrate dev在本地開發(fā)生產環(huán)境則用prisma migrate deploynpx prisma migrate dev --name init_t3code npx prisma migrate deploy2.2 tRPC路由劃分與類型推導機制tRPC的核心思想是后端導出的router類型前端直接就能推斷出來。t3code的tRPC架構是標準的“根路由聚合子路由”模型// src/server/api/root.ts export const appRouter router({ post: postRouter, user: userRouter, comment: commentRouter, }); export type AppRouter typeof appRouter;每個子路由內部再拆procedure// src/server/api/routers/post.ts import { z } from zod; import { createTRPCRouter, protectedProcedure, publicProcedure } from ../trpc; export const postRouter createTRPCRouter({ all: publicProcedure.query(async ({ ctx }) { return ctx.db.post.findMany({ where: { published: true }, orderBy: { createdAt: desc }, include: { author: { select: { name: true, image: true } } }, }); }), byId: publicProcedure .input(z.object({ id: z.string() })) .query(async ({ ctx }) { return ctx.db.post.findUnique({ where: { id: input.id }, include: { comments: { include: { author: true } } }, }); }), create: protectedProcedure .input(z.object({ title: z.string().min(1), content: z.string().min(1) })) .mutation(async ({ ctx, input }) { return ctx.db.post.create({ data: { title: input.title, content: input.content, authorId: ctx.session.user.id }, }); }), });注意這里的publicProcedure和protectedProcedure是區(qū)分權限的關鍵。t3code在createTRPCContext里注入了當前session若用戶未登錄protectedProcedure會直接拋401前端拿到錯誤后就能跳轉登錄頁。這樣的好處是權限控制不再散落在每個API handler里而是通過“中間件”統(tǒng)一治理。2.3 client端React Query的自動生成與緩存tRPC最爽的使用體驗在前端。初始化時通過createTRPCReact創(chuàng)建hooks類型自動從AppRouter推導// src/trpc/react.tsx import { createTRPCReact } from trpc/react-query; export const api createTRPCReactAppRouter();頁面里直接用const { data, refetch } api.post.all.useQuery(); const createPost api.post.create.useMutation({ onSuccess: () { utils.post.all.invalidate(); }, });useMutation的onSuccess里調用invalidate()刪除或創(chuàng)建數(shù)據(jù)后自動觸發(fā)相關查詢的重新拉取。這是React Query最核心的緩存機制幾乎不用手動管理loading狀態(tài)比手工寫fetch然后自己setState要省太多。建議新手重點理解失效invalidate和緩存命中兩個概念這是和傳統(tǒng)fetch方案最大的分水嶺。3. 實操過程與核心環(huán)節(jié)實現(xiàn)3.1 認證模塊NextAuth接入與自定義登錄t3code默認集成了NextAuth但要讓它跑起來有幾個必填環(huán)境變量DATABASE_URLpostgresql://... NEXTAUTH_SECRET生成一串隨機字符串 NEXTAUTH_URLhttp://localhost:3000我強烈建議用openssl rand -base64 32生成NEXTAUTH_SECRET不要自己編一個短字符串否則生產環(huán)境會告警。NextAuth的配置集中在src/server/auth.tsexport const authOptions: NextAuthOptions { providers: [ GitHubProvider({ clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, }), ], callbacks: { session({ session, user }) { return { ...session, user: { ...session.user, id: user.id } }; }, }, };理論上到這里GitHub登錄就能用了但實際落地時還有一個坑NextAuth默認的session類型里沒有user.id需要自己擴展類型聲明。我會在src/types/next-auth.d.ts里寫declare module next-auth { interface Session { user: { id: string; name?: string | null; email?: string | null; image?: string | null; }; } }不補這個類型ctx.session.user.id在tRPC里會直接報類型錯誤。這個細節(jié)教程里很少提到但幾乎所有基于NextAuth tRPC的項目都會遇到。3.2 核心頁面與SSR數(shù)據(jù)加載策略t3code里我寫了三個主要頁面首頁帖子列表、單個帖子詳情、個人中心。每個頁面的數(shù)據(jù)加載策略不一樣這是Next.js App Router模式下需要仔細權衡的點。首頁用服務端組件直接調tRPC是不行的因為App Router的服務端組件不能直接使用基于React Query的tRPC hooks。正確做法是調用tRPC的server端函數(shù)// src/app/page.tsx import { api } from ~/trpc/server; export default async function HomePage() { const posts await api.post.all.query(); return PostList initialPosts{posts} /; }詳情頁則可以在Server Component里通過動態(tài)路由參數(shù)調用api.post.byId.query({ id })這樣首屏HTML直接包含完整數(shù)據(jù)SEO友好不用客戶端再等一個loading。個人中心需要登錄后展示自己的帖子這種情況我選擇“混合策略”外殼用Server Component判斷session內部交互組件用Client Component tRPC query。這個邊界要分清楚Server Component負責首屏靜態(tài)數(shù)據(jù)Client Component負責需要交互的查詢和mutation。3.3 環(huán)境變量管理與多環(huán)境部署t3code用了三個環(huán)境文件來管理不同階段的配置.env.example # 模板提交到倉庫 .env.development # 本地開發(fā) .env.production # 線上部署一個重要的安全習慣.env.example里只寫鍵名和占位符真正的密鑰永遠不要提交到Git倉庫。我在項目根目錄放了.gitignore默認會忽略所有.env*但如果你把.env.example也忽略了隊友拉代碼就會一臉懵。建議做兩件事保留.env.example進倉庫手動在.gitignore里加一行!.env.example。生產部署我用的是Vercel Postgres托管Vercel平臺對Next.js的支持確實省心連接數(shù)據(jù)庫只需要在平臺環(huán)境變量面板里把DATABASE_URL和兩個認證密鑰填上。如果要部署到自建服務器則用Dockerfile構建FROM node:20-alpine AS base RUN npm i -g pnpm WORKDIR /app FROM base AS deps COPY package.json pnpm-lock.yaml ./ RUN pnpm install --frozen-lockfile FROM base AS build COPY --fromdeps /app/node_modules ./node_modules COPY . . RUN pnpm prisma generate pnpm build FROM node:20-alpine AS runner COPY --frombuild /app/.next/standalone ./ COPY --frombuild /app/.next/static ./.next/static CMD [node, server.js]Docker部署時務必注意Prisma的query engine是平臺相關的二進制在alpine鏡像里需要額外安裝openssl兼容層否則跑起來報錯Query engine library for current platform linux-musl could not be found。如果你不想折騰原生依賴直接用Vercel這類托管平臺能省掉這個煩惱。4. 常見問題與排查技巧實錄4.1 tRPC調用報500錯誤但日志空白這是我在t3code開發(fā)中遇到最多的一類問題。tRPC的錯誤處理默認會把具體錯誤信息藏在response里但如果你開了Next.js的production模式日志里可能只顯示一行Error: Internal Server Error看不到stack trace排錯效率極低。排查思路分三步走。先看network響應體的error.data字段tRPC會把錯誤堆棧放在data.stack里。如果響應體也是空的那就去服務端日志里找Prisma的查詢報錯。還有一個高頻原因在Server Component里直接調api.post.all.query()時忘記給context傳入session導致ctx.session為null。解決方法是給createTRPCContext里做空值兜底export const createTRPCContext (opts: CreateNextContextOptions) { const session getServerSession(authOptions); return { db, session: session ?? null }; };然后protectedProcedure內部通過middleware拋錯而不是在context構建階段就崩潰。這樣至少錯誤信息能正確分類為UNAUTHORIZED而不是籠統(tǒng)的500。4.2 Prisma migrate產生歷史分叉多人協(xié)作時如果你本地的_prisma_migrations歷史記錄和主線不一致prisma migrate dev會報“migration history is diverged”。我實操中的快速處理方式是確認數(shù)據(jù)庫當前狀態(tài)沒問題保存現(xiàn)有數(shù)據(jù)后重置遷移記錄npx prisma migrate reset --force --skip-seed npx prisma migrate dev但reset會清空數(shù)據(jù)所以在非本地環(huán)境千萬別直接跑這條命令。更穩(wěn)妥的做法是刪掉本地prisma/migrations目錄里多余的歷史遷移文件只保留與生產一致的基線再重新生成一個合并遷移。另外生產環(huán)境數(shù)據(jù)庫我一般會額外做每日備份保證出問題時能回滾。4.3 Tailwind響應式樣式不生效Tailwind的類名在t3code里偶爾會出現(xiàn)“編譯了但樣式沒生效”的情況。最常見的原因是把動態(tài)拼接的類名寫進了模板字符串比如className{bg-${color}-500}。Tailwind的掃描器在構建時靜態(tài)識別類名字符串動態(tài)拼接的類名會被直接跳過不會生成對應CSS。解決辦法是使用完整的類名映射表const colorClasses { red: bg-red-500 hover:bg-red-600, blue: bg-blue-500 hover:bg-blue-600, }; button className{colorClasses[color]} /另外一個容易踩的坑是App Router里給服務端組件賦值use client組件或者反過來。如果你在layout.tsx里用了一個Client Component包裹內容且這個Client Component沒有匹配好SSR和客戶端渲染條件會出現(xiàn)首屏FOUC閃白。t3code里我把所有“需登錄才顯示”的導航區(qū)塊單獨隔離成Client Component避免把整個layout強行標記成客戶端渲染。4.4 生產環(huán)境首屏接口過慢與緩存優(yōu)化t3code上線內測時發(fā)現(xiàn)帖子列表頁的首屏加載在弱網環(huán)境下需要2秒以上。排查后定位到兩個瓶頸一是首頁query串行請求了作者信息二是沒有做靜態(tài)緩存。優(yōu)化方案是Prisma查詢里用select按需取字段避免include整張關聯(lián)表include: { author: { select: { name: true, image: true }, // 只取需要字段 }, }同時對于“按時間排序的文章列表”這類很少變化的接口我在Next.js里聲明了revalidate 60讓頁面每分鐘增量重新生成一次靜態(tài)結果。tRPC的server調用本身不受影響但Next.js緩存層就能把大部分請求擋住200并發(fā)壓測下響應時間從1.8秒降到了200毫秒左右。注意如果用cookies()或headers()讀取請求上下文Next.js會自動禁用靜態(tài)緩存所以“純公開數(shù)據(jù)”的部分才適合加revalidate。4.5 常見問題速查表現(xiàn)象直接原因快速解法類型報錯Property id does not exist on type Session沒有擴展NextAuth類型聲明添加next-auth.d.ts并覆蓋Session接口Prisma報Environment variable not found: DATABASE_URL環(huán)境變量未加載檢查.env文件位置是否在項目根目錄重新sourcetRPC mutation成功但頁面不更新缺少invalidate操作在mutation的onSuccess里調用相關的invalidate()Tailwind類名顏色不生效動態(tài)拼接類名改成完整類名映射表部署到Docker后Prisma engine報錯alpine缺少平臺依賴用slim鏡像或安裝openssl兼容層NextAuth登錄后session為空NEXTAUTH_SECRET未配置設置32字節(jié)以上的隨機字符串5. 一條龍上線的完整復盤5.1 開發(fā)階段容易忽略的配置細節(jié)如果你準備完整照著t3code的思路復刻有四個配置細節(jié)我建議從一開始就做對。第一tsconfig.json里打開strict和noUncheckedIndexedAccess雖然前期會多寫很多空值判斷但等代碼規(guī)模上來之后這個決定能幫你擋住大量邊界Bug。第二ESLint配置里加上typescript-eslint的推薦規(guī)則t3code的腳手架默認帶了別手滑刪掉。它能在你寫異步邏輯時提示未處理Promise這類錯誤在運行時往往最難定位。第三Prisma的url使用connection pooler還是直連要提前想清楚。我踩過的坑是在Serverless環(huán)境用直連Postgres短連接被數(shù)據(jù)庫拒絕。如果是Vercel Postgres一定要把DATABASE_URL配置成連接池地址否則并發(fā)請求一多就會報連接數(shù)超限。第四所有需要登錄的tRPC mutation入?yún)⒗锒疾灰湃吻岸藗鱽淼膗serId必須從ctx.session.user.id拿。t3code一開始我在一個更新資料的mutation里直接把前端userId作為設置項測試時發(fā)現(xiàn)可以任意改別人數(shù)據(jù)后來全部改成了session取值。這個原則要寫進團隊規(guī)范。5.2 代碼組織與團隊協(xié)作方式t3code項目規(guī)模并不大但代碼組織我刻意按照“可擴展”的方式規(guī)劃。tRPC路由器的目錄命名直接對標業(yè)務模塊比如postRouter對應整個帖子模塊頁面組件命名和路由保持一致。這樣加到第三個業(yè)務模塊時只需新開一個router文件改一下root.ts聚合即可完全不影響已有功能。同類型項目協(xié)作時我見過團隊糾結“到底用React Query還是SWR”“用zod還是yup”。實際體驗下來tRPC官方綁定的React Query和zod已經是一套非常順手的組合不要在中途替換。因為zod不僅僅做入?yún)⑿ｒ炈念愋屯茖芰χ苯颖籺RPC用來生成procedure的入?yún)㈩愋蛽Q掉yup就等于放棄了這個核心鏈路的類型安全。5.3 項目上線后我要干什么t3code這個項目上線后我第一件事是注冊了日志監(jiān)控和錯誤上報服務。tRPC的錯誤默認會以TRPCClientError結構被前端捕獲但這些只能看到“用戶視角的錯誤”服務端堆棧對用戶沒有意義需要自動上報到后臺。我接入了錯誤捕獲服務后很快就發(fā)現(xiàn)了一個“評論創(chuàng)建成功但頁面數(shù)據(jù)不刷新”的問題用戶反饋前就已經通過日志定位到了——又是invalidate調用順序寫錯了把這個操作放在了mutate之后立即執(zhí)行但API請求還沒完全落地。按照我的經驗項目上線后的前兩周是最容易暴露問題的階段。那些開發(fā)環(huán)境重現(xiàn)不了、從用戶側看到的偶發(fā)問題90%都是環(huán)境變量缺失、依賴版本不一致、數(shù)據(jù)庫權限不夠這類“基礎配置”問題而不是業(yè)務邏輯問題。所以t3code的部署腳本里我用GitHub Actions把所有代碼質量檢查、Prisma migrate deploy、構建產物串到了一起合并到main分支時自動跑一遍配置錯了會在構建階段就攔下來。5.4 后續(xù)可以擴展的方向t3code現(xiàn)在跑得挺穩(wěn)但我心里有個擴展清單。短期計劃是加上文件上傳圖片存在對象存儲里數(shù)據(jù)庫只保存訪問路徑Prisma的字段類型改成String前端用帶簽名的URL訪問。中期計劃是加一個基于角色的權限管理在session里注入role字段tRPC procedure里加一個requireRole(admin)中間件對評論審核、內容刪除等操作做權限控制。長期計劃是把server端抽成獨立的BFF服務和移動端共享同一套tRPC路由真正做到一套類型定義覆蓋Web和App兩端。這些方向都是t3code現(xiàn)在這個架構天然支持的因為類型安全的底子打好了加功能不再是“粘貼代碼修類型錯誤”而是“寫好業(yè)務邏輯讓類型檢查替你兜底”。這也是我做完這個項目后最大的體會投資在數(shù)據(jù)鏈路的類型安全上比任何測試補充都更能長期受益。最后再分享一個小技巧t3code項目的package.json里我加了一個db:studio的腳本本地開發(fā)時一鍵啟動Prisma Studio可以直接瀏覽和修改數(shù)據(jù)庫數(shù)據(jù)。調試數(shù)據(jù)相關問題時這個工具比寫一堆腳本高效得多。如果你是第一次嘗試T3 Stack組合建議先把整個鏈路跑通一遍——從創(chuàng)建模型、遷移數(shù)據(jù)庫、查詢數(shù)據(jù)到在頁面上渲染出來走完這一步你對這套組合的信心會翻倍。