CI/CD / DevOps

Next.js Server Actions 部署到 Cloudflare Workers 前,先驗收什麼?2026

Next.js Server Actions 的設定文件指出,框架會比較請求的 Origin 與 Host 或 X-Forwarded-Host,並提供 allowedOrigins 設定。這項明確的信任邊界,代表部署到 Cloudflare Workers 前不能只確認「Server Actions 支援」:適配路徑、代理標頭、動作授權、執行環境與回滾證據都通過,才建議放行;有關鍵項目無法驗證,就先暫緩,而不是靠未經驗證的自訂中介軟體補洞。

負責新建或遷移邊緣部署的工程師,可用本文核對功能與執行環境相容性。
應用安全負責人,可用它檢查來源驗證與動作級授權是否被部署設定削弱。
發布負責人,可依清單記錄證據、指定阻斷條件與回滾責任。

先確認新建與遷移採用的適配路徑

Cloudflare 的 Next.js Workers 部署指南列出其 Next.js 部署方式與相關適配資訊。這些資訊描述的是特定路徑,不等於每個 Next.js 專案都能原樣移植,也不代表平台支援就自動完成安全驗收。正式採用前,應重新核對文件列出的目前建議、功能狀態與專案所需功能。

部署情境 先核對的項目 放行前證據
新建 Next.js 專案 依目前官方指南選定部署適配器;檢查建置指令、環境變數、伺服器功能及依賴套件是否符合該路徑 目標環境成功建置與部署;代表性頁面和 Server Actions 通過驗證
遷移既有專案 盤點既有路由、Server Actions、套件、Node.js API 依賴、表單及上傳流程;逐項對照適配器支援情況 舊功能對照結果、相容性缺口處理方式,以及可回復的已驗收版本

新建專案較容易按目標環境設計流程,但仍要驗證每個實際使用的功能。既有專案的風險則多半藏在依賴或假設中:本機能建置,不代表部署適配器支援相同 API;成功部署,也不代表登入、資料讀寫或背景工作符合預期。

如果專案指定使用 React 19.2,版本名稱本身不能取代功能測試。React 文件將 Server Functions 描述為可由用戶端觸發的伺服器端函式,因此應把每個 Server Action 視為必須單獨檢查的服務入口,而不是只在頁面載入時才會執行的內部程式碼。React Server Functions 說明

逐跳驗證代理與自訂網域的來源信任

Origin、Host 與 X-Forwarded-Host 不是只需在應用程式碼裡看一眼的欄位;真正的驗收對象,是瀏覽器、邊緣平台、代理與應用之間實際採用的值。若代理保留外部傳入的轉發標頭,或應用信任不受控制的主機名稱,設定看似正確,請求抵達動作時仍可能使用錯誤的信任資訊。

  • [ ] 在瀏覽器入口、邊緣平台與應用層記錄同一筆受控測試請求的 Origin、Host、X-Forwarded-Host,確認各層值如何傳遞或改寫。
  • [ ] 由代理明確設定可信的轉發標頭;確認外部客戶端不能透過自行附加標頭,影響應用判斷來源的主機名稱。
  • [ ] 分別測試同源、異源、缺少 Origin、格式異常及不在允許清單的來源,保存應用實際收到的標頭與拒絕結果。
  • [ ] 檢查 allowedOrigins,只保留業務確實需要信任的來源;自訂網域、預覽網域與正式網域應按各自用途確認,不要用過寬的通配設定掩蓋差異。
  • [ ] 若設定變更後結果不一致,先查明代理覆寫規則與執行環境,而不是假設所有 Workers 都會丟失 Host 或 Origin。

Next.js 曾在官方安全公告中記錄與 Origin: null 相關的 CSRF 問題;這是需要納入安全回歸的歷史案例,不能據此推論 Cloudflare Workers 普遍會丟失標頭,也不能將所有邊緣部署判定為受影響。Next.js 官方安全公告 CSRF 防護應結合框架設定與實際信任邊界測試;需要評估其他防護控制時,可參考 OWASP CSRF 防護指南。

把敏感 Server Actions 拆成授權驗收項目

來源檢查不等於使用者授權。即使請求來自預期網域,動作仍須在伺服器端確認使用者身分、角色、資源歸屬及租戶範圍。Next.js 的身分驗證與授權指南可作為設計參照;實際驗收則應以專案的資料模型和權限規則為準。

對每個會變更資金、帳號、權限或租戶資料的動作,逐項勾選:

  • [ ] 使用者未登入時,動作會拒絕請求,且不產生任何資料變更。
  • [ ] 已登入但角色不足時,服務端會拒絕操作;不能只依賴介面隱藏按鈕。
  • [ ] 使用者嘗試操作不屬於自己的資源時,伺服器會依資料庫中的歸屬關係再次檢查。
  • [ ] 跨租戶讀取或修改會被拒絕;測試結果能證明沒有洩漏資料或留下部分副作用。
  • [ ] 權限驗證放在每個動作能實際執行的服務端路徑上,不依靠前一頁的路由保護或用戶端狀態。

測試時應使用受控帳號與測試資料,記錄操作前後狀態、拒絕結果與應用記錄。若拒絕回應雖然正確,資料仍已改動,該項不能算通過。React 的 Server Functions 說明也提醒開發者將這類入口當作伺服器端可呼叫功能處理,而非預設其只能由預期的頁面流程觸發。

核對表單、上傳與執行時依賴

表單提交、檔案上傳及較大的請求本文,必須放回實際選定的部署路徑驗證。Cloudflare 的 Workers 平台限制文件列出平台限制;Node.js 相容性文件則說明相關執行時 API 支援資訊。兩份文件都應按專案依賴逐項核對,不能把某一功能或適配路徑的表現推廣成所有部署方式皆相同。

  • [ ] 以正式表單流程測試資料驗證、錯誤回應及重複提交處理,確認動作完成前不會留下不完整狀態。
  • [ ] 對上傳流程核對請求大小、本文讀取方式、儲存介面及失敗處理;只採用官方文件對目前平台及所選路徑的描述,不自行套用其他環境的限制值。
  • [ ] 搜尋動作與相依套件使用的 Node.js API,將實際執行到的功能在目標環境驗證;建置成功不等於執行時一定相容。
  • [ ] 確認部署所需環境變數與秘密資料在目標環境可用,並驗證未設定或設定錯誤時的失敗方式。
  • [ ] 將不能支援或無法驗證的功能列為待處理項目;若功能是上線必要條件,應先更換設計或部署路徑,不應以未測試的替代行為放行。

獨立常見問題

部署前的驗收範圍
確認適配器與框架版本、建置流程、動作呼叫、標頭傳遞、動作授權、上傳與執行時依賴,並記錄目標環境測試結果。若專案中有不可替代的功能無法在選定路徑驗證,就應把它列為阻斷項,而不是根據文件中「支援 Next.js」直接推定通過。

平台支援與上線批准的差異
平台支援說明特定部署路徑具備相應能力;上線批准還需要證明應用本身的安全控制與業務功能已在該路徑正常運作。尤其是敏感動作、租戶隔離與代理標頭,必須以應用的實際設定和測試結果判斷,不能由平台支援聲明代替。

代理後的來源驗證
應在實際請求路徑觀察各層收到的來源及主機標頭,再測試同源、異源與異常輸入的處理結果。若代理沒有覆寫外部提供的轉發標頭,應先修正信任邊界;若 allowedOrigins 包含不必要來源,也應先縮小範圍,再重新驗收。

身分與權限驗收
每個敏感動作都應在服務端驗證登入狀態、角色、資源歸屬與租戶範圍,並以未登入、低權限及跨租戶資料進行拒絕測試。測試不只要看畫面或回應碼,還要確認資料沒有被讀取或修改,並留下可供發布審核的證據。

執行升級回歸與故障回滾演練

框架、適配器或代理設定變更後,應在與正式環境設定一致、但授權範圍受控的環境重做驗收。只有在目標鏈路能重現的測試結果,才適合作為發布依據。

  • [ ] 重跑同源、異源、缺少來源標頭及異常來源標頭測試,確認變更前後的處理差異。
  • [ ] 重跑動作級權限拒絕測試,確認未登入、低權限、跨租戶請求都沒有副作用。
  • [ ] 保存應用記錄、邊緣觀測結果、建置版本、部署設定及測試結論,讓審核者能將證據對應到本次版本。
  • [ ] 演練部署失敗與安全檢查異常時的回復流程,確認負責人能找到已驗收版本並完成復原。
  • [ ] 確認回復後重新執行關鍵安全測試;不能把「能回到舊版」當作已證明舊版仍符合目前設定。

依阻斷條件決定是否放行

發布審核的判斷應建立在可核對的證據上,而非對邊緣平台行為的推測。特別是社群對標頭處理或 CSRF 繞過的說法,若未獲官方文件證實,也無法在受控環境重現,就不應當成 Cloudflare Workers 普遍受影響的事實;但與之相關、尚未驗證的控制仍應列入待查項目。

只有在所選適配路徑與框架版本已核實、代理來源信任清楚、敏感動作授權測試通過、必要執行時功能已驗證,而且回滾證據完整時,才建議放行。任何必要功能無法驗證、外部標頭可能改變應用判斷,或權限拒絕仍有副作用,都應記錄負責人、復測條件與證據要求,完成後再重新審核。

為受控測試選擇合適環境

如果現有方案是本機開發機或一般 CI 伺服器,它們可能無法完整呈現正式瀏覽器與邊緣代理之間的請求行為,環境設定也可能與正式發布鏈路不同;若需要驗證 Apple 平台瀏覽器行為,非 Mac 環境另有平台差異。租用雲端 Mac 可用於特定 Apple 平台測試或遠端測試工作,但不能代替 Cloudflare Workers 目標環境中的標頭、授權與回滾驗收。

因此,若本次驗收重點是 Workers 的實際部署鏈路,應優先在受控的目標環境測試;只有確實需要 Apple 平台時,才評估 KuzCloud 雲端 Mac 是否合適。可先查看 KuzCloud 服務說明與使用說明,再依測試需求決定是否租用;若長期固定負載或需要實體介面,則應另外比較自購設備等方案。

為發布驗收備妥專屬遠端 Mac

KuzCloud 提供 Apple Silicon M4 實體專屬主機,可作為團隊遠端開發、建置與發布前回歸測試環境。

透過 SSH 或 VNC 連線,並享有完整 root 權限,方便依團隊流程安裝工具與執行驗收工作。