結論先說
- 永遠把
'use client'下沉到最底層的交互葉節點,絕不貼在page.tsx或layout.tsx頂層。在 Next.js App Router 裏,一旦某文件聲明'use client',它直接導入的所有子模組都會被劃入客戶端打包邊界;正確寫法是在服務端頁面取數,把純交互按鈕、彈窗或篩選器拆成小型客戶端組件,必要時通過children插槽組合嵌套。 - 用
import 'server-only'給數據層與密鑰模組加一道構建期防盜門。光靠嘴說「別把數據庫模組導進前端」不夠穩,在lib/db.ts、lib/auth.ts頂部加上server-only,只要 Codex 誤在客戶端組件裏引用了它們,next build就會立刻紅燈攔住。 - 記住兩條容易被 AI 忽略的硬規則:第一,Client Component 同樣會在首屏經歷服務端預渲染(SSR),渲染體裏直接讀
window、localStorage或new Date()必觸發水合報錯;第二,Server Action 本質是可被外部直接請求的 POST 端點,絕對不能以為寫在後端文件裏就天然安全,必須在函數入口獨立校驗登入態、資源歸屬與入參 Schema。 - 切忌只看
next dev綠燈就收工,每輪改動必須跑通npm run typecheck && npm run build。許多 RSC 跨邊界序列化錯誤、非法導入與動態渲染衝突只有在生產構建階段才會完整暴露,配合 Playwright MCP 打開頁面檢查控制檯可把水合告警一網打盡(詳見 /guides/codex-playwright-mcp-browser-debug-frontend-bugs)。 - 全棧 Next.js 頁面涉及服務端取數、客戶端狀態聯動、構建排錯與瀏覽器水合驗收,多輪上下文消耗顯著。國內若缺少外幣卡或原帳號額度緊張,可在本站按需開通 ChatGPT Plus 充值 或高配額 ChatGPT Pro 充值,團隊多人研發可了解 ChatGPT Business 團隊定製。

圖:本站根據 Next.js 官方文檔 與 React 文檔 整理的示意圖
本文根據 Next.js 官方文檔《Server and Client Components》《Server Actions and Mutations》、React 官方文檔《'use client'》及 OpenAI Codex 官方文檔《Custom instructions with AGENTS.md》整理,資料核對於 2026-11-19。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 OpenAI 官方網站。
適用於誰
- 用 Codex 開發 Next.js App Router(14/15/16+)全棧應用,頻繁撞上
useState only works in a Client Component、水合不匹配(Hydration Mismatch)或打包報錯的開發者; - 發現 Codex 為了讓報錯消失,順手在
page.tsx或layout.tsx頂部塞一行'use client',把整棵頁面樹和數據庫依賴全拉進客戶端的工程師; - 希望在團隊倉庫裏用
AGENTS.md和構建檢查徹底守住服務端與客戶端安全邊界的全棧團隊。
一、在 AGENTS.md 立好 App Router 與 RSC 邊界護欄
為了讓 Codex 從第一行代碼就遵守現代 App Router 架構,而不是沿用舊版 Pages Router 習慣到處堆 useEffect 拉接口,建議在倉庫根目錄放入以下 AGENTS.md 規範(通用護欄寫法見 /guides/codex-agents-md-guardrails-stop-deleting-tests):
markdown
# Next.js App Router / RSC 工程約束(AGENTS.md)
## 服務端與客戶端邊界
- `app/**/page.tsx` 與 `app/**/layout.tsx` 預設保持為 Server Components,嚴禁直接添加 `'use client'`。
- 僅在需要事件監聽、React State/Effects 或瀏覽器 API 的最小葉節點組件中聲明 `'use client'`;若客戶端容器需包裹服務端內容,統一通過 `children` Prop 組合傳入。
- 所有含數據庫連接、內部密鑰或簽名邏輯的模組必須在文件首行引入 `import 'server-only'`。
## 數據傳遞與安全校驗
- Server → Client 傳遞的 Props 必須為純可序列化 JSON 結構(嚴禁傳普通回調函數、類實例或未轉換的 ORM Decimal 對象)。
- 所有 Server Actions (`'use server'`) 入口必須重新校驗當前會話身份、資源租戶權限與 Zod 入參校驗。
- 若使用 Next.js 15+,動態路由 `params`、`searchParams` 與 `cookies()` / `headers()` 一律按異步 `await` 讀取。
## 必跑驗證命令
- `npm run typecheck && npm run build`
二、常見 RSC 邊界與水合報錯快速決策
當 next build 報序列化失敗、模組越界,或者瀏覽器控制檯刷出紅字水合警告時,對照以下決策圖可快速讓 Codex 對症下藥:

圖:本站根據 Next.js 官方文檔 與工程排錯經驗整理的示意圖
訂閱與帳號準備提示:重構複雜 App Router 路由樹、拆解客戶端水合報錯並同時跑next build與瀏覽器核驗,會連續佔用較多上下文與工具調用配額(配額規劃見 /guides/codex-status-quota-5h-weekly-plus-pro-api-strategy)。高頻開發全棧 Next.js 項目的工程師可按需選購 ChatGPT Pro 5x iOS 可覆蓋檔 或 ChatGPT Pro 5x 信用卡不可覆蓋檔;新帳號註冊遇到手機驗證步驟可參考 Codex 註冊手機驗證服務。
三、實戰提示詞:先審組件樹邊界,再寫代碼並跑構建驗收
開發帶篩選、分頁和表單提交的新頁面時,先讓 Codex 在 Plan Mode 下畫出服務端與客戶端切分表再動手(規劃模式詳見 /guides/codex-plan-mode-model-verbosity-config-guide):
text
請先在 Plan Mode 下閱讀 AGENTS.md 與現有 app/(dashboard)/ 路由結構,為「團隊帳單明細頁」設計並實現 App Router 頁面:
1. 先輸出「組件邊界拆分表」,列明哪些文件是 Server Component(負責鑑權與服務端取數)、哪些葉節點是 Client Component(僅負責篩選下拉、導出按鈕與彈窗),以及跨邊界傳遞的序列化 Props 類型,經我確認後再落盤;
2. 確認後實現頁面與對應 Server Action(內含會話鑑權、租戶歸屬校驗與 Zod 入參校驗,提交後用 revalidatePath 精準刷新);
3. 嚴禁在首屏客戶端渲染體內直接依賴非確定性本地時間或 window 尺寸導致水合不匹配;
4. 完成後運行 `npm run typecheck && npm run build` 驗證生產構建零報錯,並彙總新增與改動文件清單。
遇到老項目批量遷移或大量類型告警時,也可結合 /guides/codex-batch-fix-typescript-eslint-ruff-errors 中的分模組清零策略,先穩住基礎佈局和公共組件,再逐路由推進。
常見問題
問:為什麼把客戶端側邊欄包住整個後台頁面時,裏面的服務端組件還能保持不進客戶端 Bundle?
答:關鍵在於「導入方向」而不是「渲染嵌套」。只要不是在 'use client' 文件裏直接 import 服務端組件,而是在外層 Server Layout 裏把 <ServerContent /> 作為 children 傳給 <ClientSidebar>{children}</ClientSidebar>,Next.js 就能繼續在服務端渲染 children 並把結果注入插槽,徹底避免整棵子樹被拖進前端 JS 包。
問:明明只需要顯示一條本地格式化時間,為什麼老報 Hydration Mismatch,怎麼優雅解決?
答:服務端節點時區(通常是 UTC)與用戶瀏覽器本地時區往往不同,導致首次 SSR 輸出的文字和客戶端首次水合算出的文字對不上。穩妥方案有兩種:要麼在服務端統一格式化為固定時區或 ISO 展示,要麼把依賴用戶本地時區的小組件拆成獨立客戶端葉節點,在掛載後(或配合受控佔位)渲染本地時間,不要隨意到處貼 suppressHydrationWarning 掩蓋真正的 DOM 結構差異。
問:高頻用 Codex 開發 Next.js 全棧項目和跑構建排錯很耗額度,個人或團隊怎麼開通高配額訂閱、能否開增值稅發票?
答:可前往本站 AI 會員充值總覽 按需選購 ChatGPT Plus 充值、ChatGPT Plus 自助卡密 或更高額度的 ChatGPT Pro 充值,團隊多人研發可了解 ChatGPT Business 團隊定製。支持支付寶、微信支付和 AlipayHK,自助卡密無需提供帳號密碼,並支持開具增值稅發票;實時價格與規格以頁面展示為準,售後執行掉訂閱按剩餘天數折退、封號不在質保範圍規則。
相關教學
- Codex 接入 Playwright MCP 自己打開瀏覽器點頁面、看報錯並自動修前端 Bug
- Codex Plan Mode 與 model_verbosity 設定:先審改動方案再寫代碼
- Codex 寫代碼時愛刪測試或亂改無關文件怎麼辦:5 條 AGENTS.md 硬約束護欄
- 用 Codex 批量排查並修復 TypeScript / ESLint / Python Ruff 靜態檢查報錯
參考資料
- Next.js 官方文檔:Server and Client Components — https://nextjs.org/docs/app/getting-started/server-and-client-components
- React 官方文檔:'use client' directive — https://react.dev/reference/rsc/use-client
- Next.js 官方文檔:Server Actions and Mutations — https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations
- OpenAI Codex 官方文檔:Custom instructions with AGENTS.md — https://learn.chatgpt.com/docs/agent-configuration/agents-md
0 條評論
還沒有評論,來搶沙發~