json-render 生成 UI 出錯怎麼辦？2026 React 排障指南

json-render 生成 UI 出錯時，最有效的做法是按「生成協議—Schema 校驗—元件目錄—串流狀態—業務權限」分層排查，而不是單純重試模型；只要結果無法安全渲染，就回退到結構化文字或固定元件，不執行未登記的元件與動作。這套方法適合元件白名單、JSON Schema 與串流 UI 狀態都由團隊維護的 React 應用。

正在把 json-render Demo 推向真實 React 應用的前端開發者，應先留下完整故障證據。需要管理 LLM-to-UI 協議、權限與回滾流程的 AI 應用工程師，以及準備讓雲端 Agent 自動產生、測試和發布 UI 的平台團隊，也能用這份流程建立驗收基準。

先把畫面症狀對應到故障層

「畫面壞了」不是足夠的診斷資訊。排障開始時，至少要同時保存原始模型輸出、解析後的 UI spec、最後一個成功狀態、瀏覽器的 React 錯誤，以及伺服器回傳的驗證結果。只截取最終畫面，往往會把生成錯誤誤判成 CSS 或 React 生命周期問題。

可見症狀	優先檢查位置	常見根因	首選恢復方式
整頁空白或初始化失敗	生成協議、JSON 解析	JSON 被截斷、頂層結構錯誤、回應混入說明文字	拒絕渲染，回退固定頁面並保留原始輸入
只有部分元件出現	元件目錄、props 映射	未註冊元件、版本不一致、巢狀資料路徑錯誤	未知節點轉結構化文字，重新載入目錄
Schema 驗證失敗	JSON Schema	必填屬性缺失、型別錯誤、陣列項目結構不符	嚴格驗證後修補格式，否則重新生成
按鈕或表單沒有反應	動作映射、事件授權	action 名稱不存在、handler 未注入、權限被拒絕	顯示可讀錯誤，禁止自動重試寫入
內容顯示但超出資料範圍	伺服器授權	模型產生了合法 JSON，卻要求不屬於使用者的資料	丟棄結果，重新做身份、範圍與參數檢查

官方文件確認 json-render 是以 JSON spec、預先定義元件及 React 渲染為核心；這代表故障不應只在 React 元件內找。先判斷 spec 是否成立，再判斷元件是否可用，最後才檢查視覺層，會比不斷刷新頁面更容易定位責任邊界。json-render 官方文件

先驗證協議，再處理 React JSON Schema

json-render Schema 校驗失敗時，應把「能被 JSON 解析」與「符合渲染契約」分開。前者只代表字串可以轉成物件，後者還要求頂層結構、欄位型別、巢狀節點和必填屬性全部符合定義。JSON Schema 的物件規則可用 properties、required 等約束描述；團隊應把這些規則放在伺服器端和測試流程，而不是只靠前端 TypeScript 型別。JSON Schema 物件驗證規則

可依以下順序驗證：

• 先確認回應是否為完整 JSON；若模型在結尾被截斷，不要嘗試從半個字串猜出完整按鈕或動作。
• 再檢查 spec 的頂層型別、節點識別碼、children 結構和元件名稱。
• 接著檢查 props 是否符合型別，尤其是布林值、陣列、數值與日期字串。
• 最後檢查 required 欄位、可接受的列舉值，以及是否混入未登記的 action 或任意程式碼。

修復方式可分成三類。嚴格拒絕適合付款、寫入資料或外部 API 呼叫；格式自動修補只適合補逗號、正規化欄位或移除無害的未知展示欄位；重新生成則適合模型遺漏結構但能提供明確錯誤路徑的情況。自動修補不能繞過授權、資料範圍或危險屬性檢查，否則「修好 JSON」可能只是把風險藏起來。

對齊元件目錄與白名單

json-render 元件無法渲染時，先不要把問題歸咎於模型能力。模型輸出的名稱必須和前端註冊目錄完全一致，props 的命名與型別也要有穩定映射；元件註冊文件示例同樣把元件名稱和 props 結構視為渲染契約的一部分。元件註冊與 props 結構說明

排查時可逐項勾選：

• [ ] 輸出中的 component 名稱存在於目前部署版本的白名單。
• [ ] 同名元件沒有因產品區域或套件版本而指向不同實作。
• [ ] props 已從外部資料映射成元件預期的型別。
• [ ] onClick、submit 或其他事件只接受登記過的 action ID。
• [ ] HTML、JavaScript、任意 URL、內嵌腳本等危險屬性不會直接進入渲染器。
• [ ] 未知元件有明確的文字降級，而不是呼叫 eval 或動態載入程式碼。

元件版本升級後最容易出現「名稱仍然存在，但 props 已變更」的情況。應把元件目錄版本、Schema 版本和 UI spec 版本一起記錄；若三者不一致，先回退至最後一個相容目錄，不要讓模型自行猜測新欄位。

為串流狀態建立可恢復邊界

json-render 支援以 JSONL patch 逐步更新 UI spec，但串流「抵達」不等於狀態「可套用」。官方串流說明應與客戶端的狀態機一起閱讀，因為中途斷線、重複事件和順序變動都可能讓畫面停在半成品。json-render 串流模式說明

LLM-to-UI 排障時，至少記錄補丁序號、前置版本、路徑、操作內容、接收時間和套用結果。若使用 JSON Patch，標準定義了 add、remove、replace、move、copy、test 六種操作，因此不能把每一行 JSONL 都當成「整頁替換」；路徑和操作語意必須先驗證。JSON Patch 標準資料

客戶端可採用以下狀態策略：

• 序號連續、前置版本吻合：套用補丁，但先把結果放入暫存 spec。
• 收到重複補丁：以事件識別碼或版本號做冪等判斷，避免按鈕和列表被重複加入。
• 序號跳躍或路徑不存在：暫停互動，重新拉取完整 spec。
• 串流中斷：顯示載入中或結構化文字，不讓尚未完成的表單觸發動作。
• 收到結束訊號：對完整 spec 再做一次 Schema、白名單與權限驗證，通過後才切換為可操作狀態。

若傳輸採用 Server-sent events，事件格式、連線關閉和重連行為也要納入測試；MDN 的 SSE 說明可作為瀏覽器端事件處理的基礎參考。MDN Server-sent events 說明

把展示權限與動作權限分開

合法 JSON 不代表合法操作。展示卡片、輸入元件和會寫入資料或呼叫外部服務的 action，應使用不同授權層級。模型即使產生了符合 Schema 的 delete、publish 或外部請求參數，伺服器仍須重新確認目前使用者身份、資料範圍、資源狀態和動作參數。

這裡至少有三個隱性成本：

• 前端白名單只能限制瀏覽器願意渲染什麼，不能取代伺服器授權。
• UI spec 可能被重播、竄改或從舊版本重送，因此不能把客戶端狀態當作可信來源。
• 自動重試對讀取通常較安全，對寫入、付款、刪除和外部呼叫則可能造成重複副作用。

授權失敗時，畫面應清楚顯示「需要確認」或「無權限」，不要把錯誤轉成模型再次嘗試。OWASP 的授權控制建議也強調，權限判斷應在每個受保護操作的伺服器端執行，而不是只依賴介面隱藏按鈕。OWASP 授權控制建議

用條件分支決定降級，而不是盲目修復

當團隊需要決定「修補、重試還是回退」時，可使用以下條件清單：

• 若 JSON 可解析、Schema 通過、元件與 props 都在白名單內，則進入最後的權限驗證。
• 若只有格式錯誤，且修補不會改變資料、權限或 action 語意，則可在伺服器端修補並記錄修補前後結果。
• 若出現未知元件但內容可轉為文字，則回退結構化文字，不執行該元件。
• 若補丁缺序、路徑不一致或串流中斷，則停止互動並重新拉取完整 spec。
• 若 action 涉及寫入、外部呼叫或超出資料範圍，則轉人工確認；不得因 Schema 合法而自動執行。
• 若同一輸入連續失敗，則保留原始輸入、模型版本、spec 和錯誤路徑，讓工程師重現；不要無限重試。
• 若固定模板能完整承載核心任務，則優先使用固定元件；只有在無法安全表達時，才降級為結構化文字。

排障完成後，回歸測試至少應覆蓋完整 JSON、截斷 JSON、缺少 required 欄位、未知元件、錯誤 props 型別、重複補丁、亂序補丁、串流中斷、未授權 action 和資料越界。每筆記錄保存原始輸出、解析結果、渲染錯誤、降級動作、Schema 版本、元件目錄版本及最終狀態，才可能把一次事故變成下一次部署的測試案例。

常見問題

FAQ 已將四類長尾故障拆成可獨立處理的答案；若團隊把這些答案直接轉成測試案例，便能避免只驗證「頁面最後有沒有出來」。

將一次錯誤變成可回歸的測試

json-render 不是萬能頁面生成器，而是一條需要協議、元件目錄、狀態管理和授權共同守住邊界的渲染鏈。建議每次事故都建立一張「原始輸出—解析結果—渲染錯誤—降級動作」記錄表，並把觸發輸入固定下來；這比只按重新生成更能找出真正的故障層。

若目前方案直接在本機或臨時雲端環境測試，常見問題是 React 版本與元件目錄不一致、權限環境難以重現，以及串流中斷後沒有穩定的回滾環境。對需要短期重現、跨環境驗證或讓雲端 Agent 執行建置的團隊，使用 Zutcloud 的 Mac 遠端環境可減少自行維護硬體、清理測試環境和等待本機資源的成本；不過長期固定重負載、需要實體周邊或必須完全掌控硬體的團隊，仍應評估自購 Mac。若只是臨時建立 React 回歸環境，可參考 Mac 遠端租用方案；遇到連線、帳戶或環境問題時，再從 Zutcloud 幫助中心查找處理方式。

FAQ

json-render 的 Schema 驗證失敗時，應該先修補還是重新生成？

先保留原始輸出，使用嚴格 JSON Schema 驗證找出缺少的必填欄位、錯誤型別與截斷位置。若修補只涉及格式且不改變權限或動作語意，可以在伺服器端修補；涉及未知欄位、權限範圍或動作參數時，應拒絕結果並重新生成或回退固定模板。

json-render 的元件已註冊，為什麼畫面仍然無法渲染？

先比對模型輸出的元件名稱、props 型別與目前前端元件目錄，不要只確認是否存在同名 React 元件。常見原因包括版本不一致、巢狀路徑映射錯誤、事件處理器未注入，以及元件被安全白名單排除。未知元件應顯示結構化文字，而不是執行任意程式碼。

LLM-to-UI 的 JSONL 串流補丁亂序，怎樣才能判斷是連線還是狀態問題？

在客戶端記錄補丁序號、JSON Pointer 路徑、抵達時間與目前 spec 雜湊值，並在應用前檢查前置版本是否吻合。若序號跳躍，先暫停渲染並重新拉取完整 spec；若只是重複補丁，應做到冪等處理。連線中斷時不可把半成品 UI 當成可操作畫面。

AI 生成 UI 要怎樣安全降級到固定元件？

可按錯誤類型設計三條路徑：Schema 或結構錯誤回退固定模板，未知元件轉成結構化文字，涉及寫入或外部呼叫的動作失敗則停在人工確認。固定元件仍須通過伺服器端授權與資料範圍檢查，不能因為 UI 已經降級就跳過安全驗證。

延伸閱讀

• 從 Function Calling 與工具執行邊界，理解動作失敗的排查方法
• 以規格驅動開發建立 React 功能的驗收與回歸測試流程
• 多個 AI Agent 並行工作流：拆解任務、隔離環境並降低整合衝突