在 ServBay 中使用 cURL

cURL 是一款功能強大的命令列工具及程式庫，廣泛用於透過各種協議（如 HTTP、HTTPS、FTP 等）傳輸資料。對於網頁開發來說，cURL 是不可或缺的好幫手，尤其適合發送 HTTP 請求、呼叫 API、下載或上傳檔案、測試服務連線等各類作業。

ServBay 作為專為開發者設計的本地網頁開發環境，已內建最新版 cURL 工具，無須另行安裝。也就是說，你可以直接在 ServBay 提供的終端機環境下使用 curl 指令，便捷完成多元網路互動與測試。

本文將詳盡說明如何在 ServBay 環境下運用 cURL，並提供常見實用範例及進階技巧。

安裝與設定

安裝 cURL

ServBay 安裝時已隨附 cURL 工具，無須額外安裝。開發者可於 ServBay 的終端機中直接使用 curl 指令。

若要確認 cURL 是否可用以及版本資訊，可在 ServBay 的終端機輸入以下指令：

curl --version

執行後會顯示 cURL 的版本資訊、支援的協議及功能清單，確認 cURL 已準備就緒。

設定 cURL

對一般日常應用而言，cURL 無需特別設定即可使用。其行為可透過豐富的命令列參數細緻控制，滿足各種資料傳輸需求。

基本使用範例

cURL 提供了眾多命令列選項，可因應不同資料傳輸任務。以下為部分常見範例，說明如何利用 cURL 執行各式網頁開發操作：

傳送 HTTP GET 請求

發送 GET 請求為 cURL 最常見的用途之一，用來從指定 URL 獲取資源。

curl -X GET https://api.servbay.demo/data

實際上，GET 為預設方法，可簡化為：

curl https://api.servbay.demo/data

傳送 HTTP POST 請求

POST 請求常用於向伺服器提交資料，例如表單或 JSON 有效負載。可搭配 -d（或 --data）選項指定傳送資料內容。

curl -X POST -d "param1=value1&param2=value2" https://api.servbay.demo/data

下載檔案

使用 cURL 下載檔案非常方便。-O 選項會自動以遠端檔名儲存到目前目錄。

curl -O https://servbay.demo/file.zip

若需自訂檔案名稱，可用 -o 選項：

curl -o local_filename.zip https://servbay.demo/file.zip

上傳檔案

cURL 也能輕鬆模擬檔案上傳。以 -F（或 --form）指定待上傳檔案，格式通常為 name=@/path/to/file。

curl -X POST -F "file=@/Applications/ServBay/www/servbay.demo/upload/document.pdf" https://api.servbay.demo/upload

請將 /Applications/ServBay/www/servbay.demo/upload/document.pdf 替換為實際欲上傳的檔案路徑。

進階應用技巧

除了基本操作外，cURL 還提供許多進階選項，靈活應對各種網路需求。

設定 HTTP 標頭資訊

透過 -H（或 --header）選項可自定請求 HTTP 標頭。這功能於傳送特定內容型態（如 JSON）、帶入認證資訊（如 API 金鑰或 Bearer token）時尤其實用。

curl -H "Content-Type: application/json" -H "Authorization: Bearer your_token_here" https://api.servbay.demo/data

處理 JSON 資料

在現代 API 開發中，JSON 為主流資料格式。cURL 可輕鬆應對 JSON 的發送與接收。

傳送 JSON 資料

送出 JSON 時，請將 Content-Type 設為 application/json，並以 -d 傳送 JSON 字串。

curl -X POST -H "Content-Type: application/json" -d '{"key1":"value1", "key2":"value2"}' https://api.servbay.demo/data

取得並解析 JSON 回應（搭配 jq）

cURL 取得的回應為純文字。若欲更便利地檢視與解析 JSON，可結合命令列 JSON 處理器 jq 使用。

curl -s https://api.servbay.demo/data | jq .

注意： jq 並非 ServBay 內建工具，需自行安裝。若你有使用 Homebrew，可用 brew install jq 安裝。-s 選項讓 cURL 靜默執行（不顯示進度或錯誤），僅將回應主體管線傳給 jq。更多資訊請參閱 jq 官方網站。

處理 Cookies

cURL 能儲存與傳送 Cookies，對測試需會話管理的網頁應用特別重要。

將 Cookies 儲存至檔案

以 -c（或 --cookie-jar）選項可將伺服器於回應時設定的 Cookies 儲存到指定檔案。

curl -c cookies.txt https://servbay.demo

使用 Cookies 檔案

用 -b（或 --cookie）選項可於後續請求中載入並傳送指定檔案中的 Cookies。

curl -b cookies.txt https://servbay.demo/profile

使用代理伺服器

如需透過代理訪問網路，可以 -x（或 --proxy）指定代理伺服器位址。

curl -x http://proxy.servbay.demo:8080 https://api.servbay.demo/data

限制傳輸頻寬

以 --limit-rate 選項可限制資料傳輸速度，單位為每秒位元組，可加 k、m、g 作單位。適合模擬網路頻寬受限或避免佔用過多資源情境。

curl --limit-rate 100K https://servbay.demo/largefile.zip -O

斷點續傳

下載大型檔案時，cURL 支援斷點續傳。這可用 -C - 選項，它會自動偵測已下載部份並從斷點繼續。

curl -C - -O https://servbay.demo/largefile.zip

驗證 SSL 憑證

預設情況下，cURL 會驗證 HTTPS 連線的 SSL 憑證。如需指定特定 CA 憑證檔以驗證，可用 --cacert 選項。

curl --cacert /path/to/custom_ca.crt https://secure.servbay.demo

若你的 ServBay 已設定 HTTPS 站點，且使用 ServBay 提供的根憑證（ServBay User CA 或 ServBay Public CA）簽發，請採用 ServBay 安裝目錄下 etc/ssl 的 CA 憑證檔。請參閱 ServBay SSL/HTTPS 文件了解檔案路徑細節。

警告： 部分測試場景會用 --insecure（或 -k）參數忽略 SSL 驗證錯誤。強烈不建議於生產環境或傳輸敏感資訊時啟用，因此會關閉重要安全檢查。

curl --insecure https://secure.servbay.demo

常見問題集 (FAQ)

1. 在 ServBay 終端機輸入 curl 指令時出現找不到命令訊息

• 原因：通常是終端機環境未正確設定 ServBay 的執行檔路徑。
• 解決辦法：請確認 ServBay 環境變數已經正確設置。若問題仍在，請打開 ServBay 「設定」>「命令列工具」，分別為zsh及bash進行路徑設置，並重新開啟終端機。

2. 發送請求時出現連線錯誤或逾時

• 原因：可能因目標伺服器不可達、網路連線問題、防火牆阻擋或 URL 錯誤所致。
• 解決辦法：
  • 檢查輸入的 URL 是否正確無誤。
  • 確保網路正常通暢。
  • 若訪問為本地 ServBay 站台（例如 servbay.demo），請確保 ServBay 執行中，且相關 Web 伺服器（如 Caddy/Nginx）已啟動。
  • 檢查防火牆或安全軟體是否阻擋 cURL 的連線。
  • 對於 HTTPS，檢查 SSL 憑證是否有效（詳見上方 SSL 驗證說明）。

3. 下載或上傳檔案失敗

• 原因：可能因檔案路徑錯誤、權限不足、伺服器不支援該操作或伺服端錯誤等。
• 解決辦法：
  • 確認命令中的檔案路徑存在且正確。
  • 確保 ServBay 執行或終端用戶具備檔案讀寫權限。
  • 若上傳至本地 ServBay，請檢查伺服器設定是否允許上傳，且目標資料夾存在且可寫。
  • 檢查 cURL 的錯誤訊息，以獲得更明確的失敗原因。

4. SSL 憑證驗證失敗

• 原因：可能為目標站點憑證無效、過期、網域不符、鏈不完整，或 cURL 無法找到/信任該憑證所簽發的 CA 根憑證。
• 解決辦法：
  • 檢查目標站點憑證是否有效可靠。
  • 若訪問本地 ServBay 並採用 ServBay 提供的 CA 發行憑證，請依本文或 ServBay SSL 文件，搭配 --cacert 指定 CA 憑證檔案路徑。
  • 僅於測試且無敏感資料時，才可暫用 --insecure 選項略過驗證（不建議用於生產環境）。

小結

cURL 是兼具強大與彈性的命令列工具，對網頁開發者來說幾乎不可或缺。依靠 ServBay 內建的 cURL，你可於本地開發環境輕鬆執行各類資料傳輸與網路測試，無論基礎 HTTP 請求、進階 API 呼叫或檔案處理皆能勝任。學會 cURL 的基本與進階用法，將大幅提升你的開發效率與除錯能力。