CI/CD / DevOps

Next.js 16 Server Actions 跨域請求被拒?反向代理怎麼排查(2026)

表單送出後,Server Actions 回報來源不允許,或請求在經過反向代理後失敗。 最快處理方式:先核對瀏覽器的 Origin、代理轉發後的 Host,以及 Next.js 實際收到的請求;只有確認是合法跨來源呼叫,才按實際入口收窄設定 serverActions.allowedOrigins。它不是通用 CORS 開關,也不應用來掩蓋代理設定錯誤。

本文適合維護經反向代理、網關或多網域入口部署的 Next.js 16 App Router 應用的前端工程師。 負責請求標頭轉發的平台工程師,可沿鏈路比對 Origin 與 Host。 應用安全負責人及發布測試人員,可據此評估允許來源範圍並驗證修復。

先確認拒絕發生在哪一段

不要一看到瀏覽器顯示跨域錯誤,就立刻修改 Next.js 設定。先在開發者工具的 Network 面板找到失敗的 Action 請求,記下請求網址、Request Headers 中的 Origin,以及狀態碼和回應內容;接著在應用程式日誌或代理日誌核實,這筆請求是否抵達 Next.js。

Origin 標頭表示發出請求的來源,包含協定、主機名稱與連接埠,不包含路徑;比對時不能只看網域文字而漏掉協定或連接埠差異。MDN 對 Origin 標頭的定義可作為核對依據。

觀察到的狀況 優先判斷 下一步
代理日誌沒有該請求,或代理直接回應拒絕 請求未到達應用,可能由網關、路由或安全規則攔截 查代理路由、存取規則及上游連線結果
請求抵達 Next.js,回應指向來源驗證失敗 Origin 與應用辨識的 Host/轉發主機可能不一致 脫敏記錄相關標頭,對照實際入口與代理規則
請求抵達應用,但回應是 Action 執行錯誤 可能是應用邏輯、驗證或授權問題 依 Action 日誌及回應內容排查,不要先放寬來源
瀏覽器顯示 CORS 訊息,但應用端沒有相同拒絕紀錄 可能是瀏覽器跨來源政策或代理回應標頭問題 分開檢查瀏覽器錯誤、代理回應與應用日誌

Server Actions 的來源校驗、一般 CORS、代理層攔截和 Action 內部錯誤是不同問題。官方安全說明指出,Server Actions 會比對請求來源與主機資訊,並提供額外允許來源的設定;這不代表所有瀏覽器跨域錯誤都由這項校驗造成。官方 Server Actions 安全說明

留存證據時先脫敏:不要直接分享 Cookie、Authorization、表單內容或個人資料。除排查所需的 Origin、Host、X-Forwarded-Host、狀態碼與時間資訊外,其餘敏感標頭應遮蔽。

讓瀏覽器呼叫方核對頁面與提交目標

先對照使用者開啟的頁面網址與 Action 請求網址,確認兩者的協定、主機名稱和連接埠是否一致。常見差異包括頁面以 HTTPS 載入、提交卻導向 HTTP;使用者從公開網域進入,表單卻送到內部主機;或預覽環境沿用正式環境的 Action 網址。

請分別記錄本機、預覽與正式環境的頁面來源和請求目標,不要只以「程式碼相同」推定入口相同。網域切換、協定終止或前端環境變數,可能令瀏覽器送出的 Origin 與應用收到的主機資訊不一致。Next.js 的資料修改文件說明了 Server Actions 的呼叫流程;排查時可先確認失敗請求是否為預期的 Action 呼叫,再沿請求鏈追蹤。官方資料修改與呼叫流程

可用一份精簡紀錄保存脫敏證據:

  • 頁面網址與 Action 請求網址;保留協定、主機和連接埠。
  • 瀏覽器送出的 Origin,以及請求回應狀態。
  • 預覽與正式環境的入口差異,以及失敗是否只在其中一處出現。
  • 對照成功與失敗請求,不保留 Cookie、權杖或表單機密資料。

若錯誤只在正式環境出現,應將正式入口的請求標頭與預覽環境逐項比較,而不是先假定是快取失效或客戶端狀態遺失。這兩者與來源校驗並非同一類故障。

由代理與平台維護者還原 Host 傳遞

按代理鏈逐層檢查進站 Host、轉發時保留或改寫的標頭,以及 Next.js 最終收到的值。若前方有多層代理,每一層都要確認是否傳遞必要標頭;只看瀏覽器端 Origin,無法判斷 Next.js 實際拿到甚麼主機資訊。

X-Forwarded-Host 用來表示原始請求的 Host 資訊,代理如何設定與轉送它,必須配合實際拓撲確認。MDN 對 X-Forwarded-Host 的說明可用來核對標頭用途;自我託管的 Next.js 部署,也應參考官方反向代理與自我託管指引。HTTP 規範則將閘道描述為接收、轉送請求的中介角色,因此代理層回應與應用回應必須分開辨識。HTTP 語義規範中的閘道說明

比較項目 直接連線 經反向代理或網關
請求入口 瀏覽器直接連到應用入口 瀏覽器先連到代理,再由代理轉送
Host 核對 比對瀏覽器目標與應用收到的 Host 逐層檢查 Host 是否被改寫、丟失或改成內部名稱
轉發標頭 通常沒有中間代理加入的轉發資訊 檢查 X-Forwarded-Host 等標頭是否存在且值符合拓撲
最小重現 用同一頁面與 Action 測試直連 使用相同程式及請求,改經正式代理入口
診斷方向 若直連也失敗,檢查應用端來源與程式邏輯 若只有代理路徑失敗,先定位轉發差異

比較直連與代理入口時,盡量使用相同的頁面、Action 與測試資料,並保留兩條路徑上的脫敏標頭和回應。若直連正常、代理路徑失敗,這是代理鏈路需要優先調查的證據,不足以直接推論 Next.js 快取或 React 客戶端狀態有問題。

不要把內部 Host 當成預期來源:代理後端可能使用內部位址,但瀏覽器看到的是公開入口。應先確認 Next.js 透過實際標頭辨識到哪個主機,不要因內部網址出現在日誌,就把它直接加入允許清單。

依實際入口評估 allowedOrigins

只有在確認合法的瀏覽器來源與 Next.js 所辨識的主機確有差異,且代理轉發設定已核實後,才考慮 serverActions.allowedOrigins。官方設定文件將它定義為 Server Actions 的額外允許來源設定,並提供配置範例;實際語義與可用設定應以正在使用的 Next.js 版本文件為準。Server Actions 官方設定說明

例如,若部署確認某個公開來源確實需要被允許,可依官方文件所示的設定位置放入已驗證的來源值:

// next.config.js
module.exports = {
  experimental: {
    serverActions: {
      allowedOrigins: ['app.example.com'],
    },
  },
}

上述網域僅是格式示例,不代表任何特定部署應使用它。正式設定前要先依實際版本文件確認參數位置,並以脫敏請求紀錄判斷應加入哪個來源;不能因為「有代理」就固定填代理網域,也不能把 allowedOrigins 當作任意放行所有跨來源請求的開關。

釐清安全邊界時,也要區分來源校驗與使用者授權:允許某個來源不等於該使用者有權執行 Action,Action 仍需依資料與操作檢查身分和權限。這一點與官方的認證與授權指引一致。

由發布測試人員驗證修復範圍

配置調整完成後,不要只以一次成功提交作為驗收。應同時測試預期來源是否正常,以及非預期來源是否仍被拒絕,並重複檢查預覽與正式環境使用不同入口時的結果。

  • [ ] 記錄修復前後的 Origin、Host、X-Forwarded-Host 及回應狀態,移除 Cookie、權杖與個人資料。
  • [ ] 確認預期網域的 Server Actions 可以完成呼叫,且應用日誌顯示請求抵達預期服務。
  • [ ] 從非預期來源測試拒絕結果,確認沒有因萬用字元或代理規則而擴大信任範圍。
  • [ ] 分別驗證預覽與正式入口,檢查協定、網域切換及代理轉發是否符合預期。
  • [ ] 將代理前後的標頭差異、測試入口及回應結果留作回歸證據。

此處理方式能避免把單次成功誤當成安全驗收,也讓團隊在之後更新 Next.js 或代理設定時,能重用同一組請求鏈路證據重新核對。

常見問題

正式環境才出錯,是否代表 Next.js 快取失效?
不一定。先看請求是否抵達應用及來源校驗結果,再比對正式環境的 Origin、Host 和代理標頭。快取問題可能造成其他資料呈現差異,但不能取代來源校驗的鏈路證據。

加入 allowedOrigins 後還是被拒,該查甚麼?
確認設定是否放在目前 Next.js 版本支援的位置、設定值是否符合實際來源,以及部署後是否載入新設定;同時重新核對代理轉發後的 Host 與轉發標頭。若請求根本沒有到達應用,應先查代理或網關回應。

Origin 和 Host 不一致時,應直接允許其中一方嗎?
不應直接放行。先找出哪一層造成差異:公開入口、代理轉發,或應用端讀取到的主機資訊。修正錯誤轉發後再測試;只有合法來源仍需與應用主機不同時,才加入最小範圍的額外允許來源。

這類拒絕和一般 CORS 錯誤有甚麼不同?
Server Actions 的來源校驗發生在應用請求處理流程中;一般 CORS 則涉及瀏覽器對跨來源請求及回應的處理。兩者可能出現在同一條請求鏈上,但錯誤來源和修復位置不同,因此要結合瀏覽器錯誤、代理回應及應用日誌判斷。

如果目前靠本機瀏覽器加上共用預覽環境排查,常見限制是入口標頭不易重現、測試資料彼此干擾,且無法清楚分辨瀏覽器端與代理端的變化;租用 KuzCloud 的 Mac,可作為獨立開發與瀏覽器驗證環境,協助比對不同入口的請求結果,但不能取代正式伺服器上的代理配置及安全驗收。若團隊需要額外測試設備,可先查看 KuzCloud 的雲端 Mac 環境資訊,並透過使用支援說明確認適用方式。

為部署排查準備一台專屬遠端 Mac

透過 KuzCloud 租用實體 Mac mini M4,使用 SSH 或 VNC 遠端連線,檢查應用程式與反向代理之間的請求標頭。

享有完整 root 權限,可依照團隊需求安裝工具、調整環境,並驗證部署設定。