2026.11.08

網站串接 API 出現 CORS 錯誤？用開發者工具找出失敗的預檢請求

網站 JavaScript 串接 API 時，瀏覽器顯示 CORS 錯誤，但直接開啟 API 網址卻有回應。直接導覽與網頁程式跨來源讀取受到不同限制。CORS 是瀏覽器依 API 回應標頭決定是否允許網頁程式讀取回應的機制，並非 API 身分驗證。

重現並找出預檢或實際請求

先在測試環境以測試帳號及無敏感資料的操作重現，記錄發起頁面的來源（協定、主機、埠）、API 網址、方法及時間。協定或埠不同就可能是不同來源。開啟 Chrome 或 Edge 開發者工具 Network，勾選保留紀錄後重新操作，篩選 API 路徑；檢查是否有先行 OPTIONS，再查看實際 GET 或 POST。不是每個跨來源請求都需要預檢。

選取 OPTIONS，檢查 Request Headers 的 Origin、Access-Control-Request-Method 與可能存在的 Access-Control-Request-Headers，再查看狀態碼與 Response Headers。若 OPTIONS 失敗，瀏覽器可能不會送出後續請求。若預檢成功但實際請求失敗，也要檢查實際回應，包括 401、403 或 500 是否缺少需要的 CORS 標頭。結合代理與伺服器日誌定位原因。

由 API 管理者核對允許範圍

API 伺服器或前方代理需依授權政策回應允許的來源、方法與標頭。比對 Access-Control-Allow-Origin 是否符合來源，預檢回應的允許方法與標頭是否涵蓋請求。若使用 cookie 等憑證，檢查客戶端 credentials 和伺服器 Access-Control-Allow-Credentials；帶憑證的回應不能用萬用來源 * 取代明確來源。動態回傳來源時評估快取的 Vary: Origin。細節見 MDN CORS 文件。

不要停用瀏覽器安全機制，也不要把所有來源、方法與標頭全數開放。CORS 不會阻擋非瀏覽器客戶端呼叫 API，驗證、授權及必要的 CSRF 防護仍須獨立執行。若由第三方管理，提供已遮蔽的來源、方法、時間與錯誤回應，不要傳送 token、cookie 或完整個資。

用具體標頭比對預檢

例如頁面來源是 https://shop.example，準備以 POST 呼叫 https://api.example/orders，並傳送 application/json 與 Authorization。Network 中 OPTIONS 的請求標頭可能如下：

Origin: https://shop.example
Access-Control-Request-Method: POST
Access-Control-Request-Headers: authorization,content-type

若服務管理者確實授權這個來源、方法與標頭，成功的預檢回應可能是 204，並包含：

Access-Control-Allow-Origin: https://shop.example
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: authorization, content-type
Vary: Origin

欄位順序及大小寫可能不同，允許方法也可以包含其他經授權的方法。若回應缺少 POST，或未允許 authorization，瀏覽器會阻擋後續跨來源讀取；403 或 5xx 則應查看處理 OPTIONS 的應用程式、代理或防火牆日誌。預檢成功後仍要選取實際 POST，確認其回應也包含適用的 Access-Control-Allow-Origin。若使用 credentials，實際回應也必須符合憑證相關的 CORS 要求。不要將範例來源直接套用到正式環境。

驗證與回復

記錄原設定，先在測試環境為指定來源調整。重新操作，確認必要的 OPTIONS 與實際請求都成功，且頁面確實讀到預期資料；再測試未授權來源無法以瀏覽器讀取，並確認既有合法來源與登入流程正常。若其他功能失效，回復原規則並比對日誌。Chrome Network 文件說明請求狀態與 Initiator；若故障是 WordPress 編輯器儲存失敗，參考REST API 儲存錯誤排查。