為 ServBay 上的網站設定 CORS（跨域資源共享）

在現代 Web 開發中，前端應用（通常運行於一個網域下）時常需要存取後端 API 或其他服務（可能運行在不同網域或埠號）。出於安全考量，瀏覽器的同源策略預設會阻擋這類跨域請求。跨域資源共享（CORS）是一項標準機制，讓伺服器聲明哪些來源能存取其資源，進而實現安全的跨域互動。

本文將引導你如何在 ServBay 本地 Web 開發環境中，經由 ServBay 的圖形化介面，輕鬆為你的網站啟用並設定 CORS。

什麼是 CORS？

跨域資源共享 (CORS) 是一種基於 HTTP 標頭的機制，允許伺服器指示除了自身來源（網域、協定或埠）以外，哪些來源被允許加載資源。當網頁嘗試從不同於自身來源的地址發送請求時，瀏覽器會啟用「跨域 HTTP 請求」，而根據同源策略，這類請求預設會被瀏覽器阻擋。CORS 提供一個讓伺服器與瀏覽器溝通、協商跨域請求安全性的標準方式。

為什麼開發者需要設定 CORS？

當你開發前後端分離的應用（例如前端在 app.servbay.demo，後端 API 在 api.servbay.demo），或前端需存取第三方 API 時，瀏覽器會因同源策略而阻擋這些跨域請求。配置 CORS 就是在伺服器端告知瀏覽器，哪些前端來源允許訪問資源，藉此解決同源政策造成的請求失敗問題。

理解 CORS 的關鍵 HTTP 回應標頭

當伺服器回應跨域請求時，會帶上一些特殊的 Access-Control-* HTTP 回應標頭。客戶端瀏覽器收到這些標頭後，會據此決定是否允許該跨域請求成功。以下為 ServBay 可設定的主要 CORS 參數（也就是這些 HTTP 標頭）：

1. Access-Control-Allow-Origin

   • 作用：這是最核心的 CORS 標頭，指定哪些來源（單一/多個網域）可以訪問資源。
   • 取值：
     • *：允許來自任意來源的請求。**重要說明：**此方式雖然便利，但在正式環境下不建議使用，因為等同任何網站都能讀取你的資源，存在潛在安全風險。
     • https://servbay.demo：僅允許來自 https://servbay.demo 這個來源的請求。
     • https://servbay.demo https://api.servbay.demo：允許多個指定來源的請求，彼此以空格分隔。
   • 注意： 如請求需攜帶 Cookie 或 HTTP 驗證資訊（即設定 Access-Control-Allow-Credentials: true），則 Access-Control-Allow-Origin 絕不可設為 *，必須明確指定來源。

2. Access-Control-Allow-Methods

   • 作用：指定允許跨域請求所能使用的 HTTP 方法（如 GET, POST, PUT, DELETE, OPTIONS 等）。
   • 取值： 例：GET, POST, PUT, DELETE, OPTIONS，多個方法以逗號分隔。
   • 注意： 若為「非簡單請求」（如帶 PUT、DELETE、自訂請求標頭等），瀏覽器會先發送 OPTIONS「預檢請求」（Preflight Request）。伺服器必須回應並帶上 Access-Control-Allow-Methods 等標頭，告知瀏覽器實際允許哪些 HTTP 方法，因此建議設定時包含 OPTIONS。

3. Access-Control-Allow-Headers

   • 作用：指定允許跨域請求額外攜帶哪些自訂 HTTP 請求標頭。
   • 取值： 例：Content-Type, Authorization, X-Requested-With，多個標頭以逗號分隔。
   • 注意： 若請求另帶預設以外標頭（如 Accept, Accept-Language, Content-Language, 預設 Content-Type 為 application/x-www-form-urlencoded, multipart/form-data, text/plain 以外），瀏覽器會先發出預檢請求，你必須明確列出允許的自訂標頭。

4. Access-Control-Allow-Credentials

   • 作用：指示是否允許跨域請求攜帶用戶憑證，例如 Cookie、用戶端 SSL 憑證或 HTTP 驗證資訊。
   • 取值： true 或 false。
   • 注意： 如設為 true，如先前所述，Access-Control-Allow-Origin 必須指定明確來源，不可使用萬用符號 *。同時，客戶端（如 JS 代碼）也需在發請求時設置對應標記（例如 xhr.withCredentials = true 或 fetch(url, { credentials: 'include' })）。

如何在 ServBay 啟用並設定 CORS

ServBay 提供直觀的圖形化介面，讓你可為每個網站獨立設定 CORS。具體步驟如下：

1. 啟動 ServBay 並進入網站列表：
   開啟 ServBay 程式，在主介面左側導覽列，點選「網站」。你將看到 ServBay 中所有本地網站清單。

2. 選取需要設定 CORS 的網站：
   於網站列表尋找你想啟用及設定 CORS 的目標網站，點擊其名稱進入詳細配置畫面。

3. 找到並啟用 CORS 設定：
   在網站設定頁的中央區域，往下捲動尋找「CORS」區塊。ServBay 預設關閉 CORS，請點擊該段右側的開關，切換到「開啟」狀態。啟用後，控制項會變成可編輯。

4. 設定 Access-Control-Allow-Origin：
   於「Access-Control-Allow-Origin」輸入框輸入你要允許訪問此網站資源的一個或多個來源。多個來源請以空格分隔。如：https://frontend.servbay.demo https://anotherapp.servbay.demo。正式環境請避免設定為 *。

5. 設定 Access-Control-Allow-Methods：
   於「Access-Control-Allow-Methods」輸入框輸入允許的 HTTP 方法，多個以逗號分隔。如：GET, POST, PUT, DELETE, OPTIONS。請確實包含應用會用到的所有方法，以及 OPTIONS 以支援預檢請求。

6. 設定 Access-Control-Allow-Headers：
   於「Access-Control-Allow-Headers」輸入框列出允許攜帶的自訂請求標頭，多個以逗號分隔。如：Content-Type, Authorization, X-Custom-Header。僅需列出實際會用到的自訂標頭即可。

7. 設定 Access-Control-Allow-Credentials（可選）：
   如需允許跨域請求攜帶 Cookie 或 HTTP 驗證資訊，請點選「Allow-Credentials」旁的滑動開關打開。再次提醒： 此時第 4 步的 Access-Control-Allow-Origin 絕不可設為 *。

8. 儲存設定：
   所有設定完成後，請務必點選頁面右下角的「保存」按鈕使設定生效。ServBay 會自動更新底層 Web 伺服器（如 Caddy、Nginx）配置，無須手動重啟服務。

設定範例

下方圖片展示如何在 ServBay 為名為「ServBay Demo Website」的網站設定 CORS：

根據上述設定：

• Access-Control-Allow-Origin：https://frontend.servbay.demo https://api.servbay.demo
• Access-Control-Allow-Methods：GET, POST, PUT, DELETE, OPTIONS
• Access-Control-Allow-Headers：Content-Type, Authorization
• Allow-Credentials：已啟用 (true)

這代表只有來自 https://frontend.servbay.demo 及 https://api.servbay.demo 這兩個來源的請求才被允許存取「ServBay Demo Website」資源。這些請求可使用 GET、POST、PUT、DELETE、OPTIONS 方法，且允許攜帶 Content-Type 與 Authorization 標頭，也可傳遞 Cookie 等憑證資訊。

注意事項與最佳實踐

• 安全性優先： 在開發、測試時可以使用 Access-Control-Allow-Origin: * 以圖方便，但部署到正式環境時，請務必限制僅允許實際需要存取的來源，提高資料安全性。
• 預檢請求： 理解預檢請求（OPTIONS 方法）的工作原理，有助於排查 CORS 問題。請確認伺服器（經由 ServBay 設定）正確回應預檢所需標頭。
• 瀏覽器快取： 瀏覽器可能會快取 CORS 策略，如更改設定後遇到問題，可嘗試清理瀏覽器快取或使用無痕模式測試。
• 應用層 CORS：某些 Web 框架或函式庫（如 Laravel、Express.js、Spring Boot 等）可於應用程式層級自訂 CORS。ServBay 的 CORS 設定是在 Web 伺服器層（Caddy/Nginx），一般給予較高優先權。遇到複雜場景，建議同時檢查伺服器與程式碼層的 CORS 配置是否一致。
• 除錯工具： 善用瀏覽器開發者工具（通常按 F12 開啟）中的「網路（Network）」標籤，查看跨域請求與回應標頭，有助診斷 CORS 設定是否生效，以及哪個步驟發生問題。

常見問題解答（FAQ）

Q: 我已經依照步驟設定 CORS，為什麼跨域請求還是失敗？

A: 請依下列步驟檢查：

1. 檢查瀏覽器控制台及網路標籤： 瀏覽器常會於控制台顯示 CORS 錯誤訊息，並於網路標籤詳列請求與回應所有標頭。確認回應是否包含正確的 Access-Control-Allow-Origin、Access-Control-Allow-Methods、Access-Control-Allow-Headers，及其內容是否與前端請求吻合。
2. 核對來源地址： 確認 Access-Control-Allow-Origin 裡面的來源（協定、網域、埠號）與實際前端請求所使用的完全一致。
3. 檢查方法與標頭： 確保 Access-Control-Allow-Methods 列有你所用的 HTTP 方法，Access-Control-Allow-Headers 有所有自訂請求標頭。
4. 憑證問題： 若需攜帶 Cookie、驗證資訊等，請確定 ServBay 設定已開啟 Allow-Credentials，且 Access-Control-Allow-Origin 非 *。同時，客戶端也需設置傳送憑證（如 withCredentials = true）。
5. 預檢請求： 對於非簡單請求，需檢查瀏覽器是否有發出 OPTIONS 預檢，以及伺服器回應裡有無正確 CORS 標頭。
6. ServBay 儲存： 設定後請務必點擊 ServBay 的「保存」按鈕讓設定生效。

Q: 能否為所有網站設定全域 CORS 策略？

A: ServBay 的 CORS 設定是網站獨立，可提供更高彈性與安全性。目前 ServBay 介面不提供全域 CORS 設定。若多個網站需用類似策略，請分別設定。

Q: ServBay 如何實現 CORS 配置？

A: ServBay 底層採用 Caddy 或 Nginx 作為 Web 伺服器。你於 ServBay 介面設定的 CORS，會被自動轉換為對應 Caddyfile 或 Nginx 設定指令。ServBay 負責管理這些配置檔並自動使設定即時生效，無須手動編輯。

小結

透過 ServBay 直覺易用的圖形介面，你可輕鬆幫本地開發環境中的網站啟用、設定 CORS，有效解決跨域存取問題。理解並正確設定 Access-Control-Allow-Origin、Access-Control-Allow-Methods、Access-Control-Allow-Headers 和 Access-Control-Allow-Credentials 等關鍵標頭，是確保跨域請求安全流暢的關鍵。遵循本指引與注意事項，將有助你更高效安全地進行本地 Web 開發。