看得懂貼上的 curl,查 API 就會快很多

從文件或瀏覽器開發者工具複製來的 curl 指令,通常長這樣:

curl -X POST 'https://api.example.com/v1/items?limit=10' \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Alice","tags":["a","b"]}'

看得懂之後其實很單純,但有幾處選項組合會改變行為,不知道就會遇到「同一段指令在這裡卻不能用」。

curl 選項清單(依用途)

這是最常遇到的選項,依功能分組。若要查看您的 curl 版本支援的全部內容,請執行 curl --help all(完整清單)、curl --help category(分類清單)或 man curl(詳細說明)。

建立請求

選項 意義
-X, --request 設定 HTTP 方法(GET / POST / PUT / DELETE)
-H, --header 加入請求標頭;可重複使用
-A, --user-agent 設定 User-Agent 標頭
-e, --referer 設定 Referer 標頭
-b, --cookie 傳送 Cookie
-c, --cookie-jar 把收到的 Cookie 存到檔案
-u, --user Basic 驗證(user:password)
-G, --get 把 -d 的資料放進 URL 查詢字串,而不是主體

傳送資料

選項 意義
-d, --data 傳送請求主體。隱含 POST
--data-raw 與 -d 相同,但不把開頭的 @ 當成檔名
--data-binary 原樣傳送資料並保留換行(檔案、二進位)
--data-urlencode 傳送前先對值做百分比編碼
-F, --form 以 multipart/form-data 傳送(檔案上傳)
-T, --upload-file 上傳檔案(在 HTTP 上就是 PUT)
--json 傳送 JSON,並一併設定 Content-Type 與 Accept(curl 7.82+)

處理回應

選項 意義
-o, --output 把回應寫入檔案
-O, --remote-name 以 URL 中的檔名儲存
-i, --include 在輸出中包含回應標頭
-I, --head 送出 HEAD,只顯示標頭
-D, --dump-header 把回應標頭寫入檔案
-w, --write-out 結束時輸出 %{http_code} 之類的資訊
-r, --range 要求位元組範圍(例如 0-99)
-C - 接續下載到一半的檔案
--compressed 要求壓縮傳輸(gzip 等)

輸出與錯誤

選項 意義
-s, --silent 隱藏進度顯示
-S, --show-error 搭配 -s 時,仍然顯示錯誤
-v, --verbose 顯示完整的往返內容,包括請求標頭
-f, --fail 遇到 HTTP 400 以上時,不輸出主體並以代碼 22 結束
-#, --progress-bar 以進度列顯示進度

連線、逾時與重新導向

選項 意義
-L, --location 跟隨重新導向(3xx)
--max-redirs 最多跟隨幾次重新導向
--connect-timeout 等待連線的秒數
-m, --max-time 整體最長秒數;超過就中止傳輸
--retry 遇到暫時性錯誤時的重試次數
-x, --proxy 透過代理伺服器連線
--resolve 把主機名稱解析成指定的 IP(host:port:address),不必更動 DNS 就能測試新伺服器
-4, -6 只使用 IPv4 / IPv6
-g, --globoff 不展開 URL 中的 [] 與 {}

TLS(HTTPS)

選項 意義
-k, --insecure 略過伺服器憑證驗證
--cacert 用來驗證的 CA 憑證檔
-E, --cert / --key 用戶端憑證與私鑰

-X POST 多半可以省略

只要加上 -d,curl 就會自動變成 POST。下面兩行是一樣的:

curl -X POST https://api.example.com/items -d '{"a":1}'
curl https://api.example.com/items -d '{"a":1}'

麻煩的是反過來的情況。-X GET 搭配 -d 會產生帶有主體的 GET 請求,某些 Proxy 與伺服器會忽略或拒絕,是「本機可以、正式環境失敗」的經典原因。

另外 -d 寫多次會用 & 串起來。對表單送出很方便,對 JSON 則是災難:

# 與預期不同:送出的是 {"a":1}&{"b":2}
curl -d '{"a":1}' -d '{"b":2}' https://api.example.com/items

-d 開頭的 @ 會變成讀取檔案

當傳給 -d 的值以 @ 開頭時,curl 會讀取該檔案並送出其內容:

curl -d @payload.json https://api.example.com/items   # 送出檔案內容

很方便,但把帳號或信箱原樣傳入就會出事:

# 本意:送出字串 "@alice"
# 實際:curl 去找 ./alice 這個檔案,找不到就報錯
curl -d '@alice' https://api.example.com/items

要原樣送出含 @ 的值,請用 --data-raw,它不會對 @ 做特殊處理。

Content-Type 不會自動變成 JSON

使用 -d 時,若未特別指定,curl 會送出 Content-Type: application/x-www-form-urlencoded。以為在送 JSON 卻忘了標頭,伺服器就會解析失敗:

curl -H 'Content-Type: application/json' \
     -d '{"name":"Alice"}' https://api.example.com/items

curl 7.82 之後有 --json,會同時設定 Content-Type: application/json 與 Accept: application/json。但舊環境沒有這個選項,要分享的指令還是明確寫出標頭比較保險。

引號用法是最大的出錯來源

寫法 行為
'...'(單引號) 原樣傳遞內部的 $ 與 "。送 JSON 用這個
"..."(雙引號) Shell 會展開 $變數

JSON 本身含有雙引號,所以外層要用單引號:

# 正確
curl -d '{"name":"Alice"}' https://api.example.com/items

# Shell 會把內層引號剝掉,主體就壞了
curl -d "{"name":"Alice"}" https://api.example.com/items

若需要從環境變數帶入權杖,就刻意混用兩者:

curl -H "Authorization: Bearer $TOKEN" \
     -d '{"name":"Alice"}' https://api.example.com/items

Windows 命令提示字元不會解析單引號,而 PowerShell 中的 curl 有可能是 Invoke-WebRequest 的別名。請明確呼叫 curl.exe,或改在 WSL、Git Bash 執行。

該用哪個資料選項

-d 系列的差異,在於送出前會轉換什麼。

選項 轉換 最適合
-d 以 @ 開頭的值會讀取檔案;檔案中的換行會被移除 表單、簡短的 JSON
--data-raw @ 沒有特殊意義 原樣傳送含有 @ 的字串
--data-binary 原樣傳送,包含換行 換行很重要的檔案、二進位資料
--data-urlencode 對值做百分比編碼 表單值與查詢中的非 ASCII 文字或符號
-F 以 multipart/form-data 傳送 檔案上傳

要讀取檔案請用 -d @payload.json,要讀取標準輸入請用 -d @-。若 JSON 檔需要保留換行,或要傳二進位資料,請用 --data-binary @file。

逾時與重試

在指令碼中執行 curl 時,請設定時間限制,讓它絕不會無限等待:

curl --connect-timeout 5 --max-time 30 --retry 3 https://api.example.com/items
  • --connect-timeout:等待連線的秒數
  • -m, --max-time:整個傳輸的秒數。下載大型檔案時請多給一些
  • --retry:遇到逾時或某些 HTTP 錯誤(429、502、503、504 等)時重試的次數

預設情況下,curl 即使伺服器回傳 404 或 500,結束代碼也是 0。要在指令碼中偵測失敗,請加上 -f:

curl -fsS https://api.example.com/health || echo "failed"

只想取得狀態碼時,請用 -w:

curl -s -o /dev/null -w '%{http_code}\n' https://example.com/

在 Windows 上,請以 NUL 取代 /dev/null。-w 也支援 %{time_total}(總秒數)等變數。

常見的結束代碼

這是在指令碼中檢查 $? 時的參考(完整清單請見 man curl 的 “EXIT CODES”)。

代碼 意義
0 成功
6 無法解析主機
7 連線失敗
22 HTTP 400 以上(搭配 -f)
28 逾時
35 TLS 交握失敗
60 無法驗證伺服器憑證

在 Windows 上使用 curl.exe

Windows 10(1803 版)以後內建 curl.exe。選項與 Linux、macOS 相同,但寫指令的方式取決於 shell。

項目 命令提示字元(cmd) PowerShell
呼叫方式 curl / curl.exe 請寫成 curl.exe(curl 可能是 Invoke-WebRequest 的別名)
引號 只能用雙引號(單引號無效) 單引號、雙引號都行,但內層的 " 可能被吃掉
換行接續 ^ 反引號 `

在 cmd 中,請以 \" 跳脫 JSON 內的雙引號:

curl.exe -X POST -H "Content-Type: application/json" -d "{\"name\":\"Alice\"}" https://api.example.com/items

PowerShell 也很容易弄壞 JSON 的引號,最可靠的做法是把 JSON 放進檔案,再以 -d @body.json 傳入:

curl.exe -X POST -H "Content-Type: application/json" -d "@body.json" https://api.example.com/items

拿不準時,請在 WSL 或 Git Bash 中執行指令,那裡單引號有效,本文的範例也能直接使用。

URL 含 & 時要用引號括起來

直接貼上含多個參數的 URL,Shell 會把 & 解讀成「放到背景執行」,指令就被截斷了:

# 壞掉:只送出 limit=10
curl https://api.example.com/items?limit=10&offset=20

# 正確
curl 'https://api.example.com/items?limit=10&offset=20'

含空白或非 ASCII 字元的值需要百分比編碼。可以用 URL 編碼/解碼 確認,或交給 curl 以 -G 搭配 --data-urlencode 安全地組出查詢字串:

curl -G https://api.example.com/search --data-urlencode 'q=台北 101'

兩個不該隨手加上的選項

-k / --insecure 會關閉憑證驗證。在本機測試自簽憑證時有其用途,但為了消除錯誤而加上、然後就這樣被分享或帶進正式環境,是最典型的事故。 憑證問題應該在憑證那端解決。

-L / --location 會追蹤重新導向。很方便,但 POST 被導向時,方法與主體的處理可能改變;需要固定行為時,可用 --post301、--post302、--post303 明確指定。

把讀懂的 curl 直接變成程式碼

把讀懂的 curl 搬進應用程式時,手動抄寫標頭與主體很容易出錯。貼進 cURL 轉換器,就能轉成 JavaScript、Python、Go 等語言的請求程式碼,引號對應與標頭拆解都由工具處理。

要格式化或檢查要送出的 JSON,可用 JSON 格式化工具;想看查詢字串的內容,可用 URL 參數轉 JSON。這些都在瀏覽器內完成,即使貼上含權杖的指令也不會傳送到外部。

總結

  • 加了 -d 就自動是 POST;-X GET 搭配 -d 會變成不好處理的「帶主體的 GET」
  • -d 的值以 @ 開頭會讀取檔案,要當字串送就用 --data-raw
  • 只用 -d 是表單格式;送 JSON 要明確給標頭,或使用 --json(curl 7.82+)
  • 送 JSON 時外層用單引號,只有需要展開變數的地方才用雙引號
  • URL 含 & 要用引號括住;值的編碼交給 -G --data-urlencode 最安全
  • -k 不是拿來消除錯誤的工具,-L 可能改變 POST 的行為

常見問題

如何列出所有 curl 選項?

執行 curl --help all 可看到所有選項,執行 curl --help category 可看到分類。man curl 有完整說明。在 Windows 上請用 curl.exe --help all。上面「curl 選項清單(依用途)」的表格涵蓋了您最常用的選項。

curl 與 curl.exe 有什麼差別?

在 Windows PowerShell 中,curl 可能是 Invoke-WebRequest 的別名,選項並不相同。請寫成 curl.exe 來呼叫真正的 curl。在命令提示字元中,兩種名稱都會執行 curl.exe。

curl 遇到 404 結束代碼也是 0,能讓它失敗嗎?

加上 -f(--fail):遇到 HTTP 400 以上時,curl 不會輸出主體,並以代碼 22 結束。這對在指令碼中偵測失敗很有用。請搭配 --connect-timeout 與 --max-time,避免卡住。

一定要寫 -X POST 嗎?

通常不用,加上 -d 或 -F 時就會自動成為 POST。不過寫出來能表達意圖,在要分享的指令中仍有價值。該避免的是 -X GET 搭配 -d,那會變成帶主體的 GET,部分伺服器與 Proxy 會忽略或拒絕。

-d 和 --data-raw 差在哪裡?

只差在開頭 @ 的處理。-d 會把 @ 後面的字串當成檔名並送出檔案內容,--data-raw 則原樣送出字串。要送出本來就含 @ 的資料(例如電子郵件),請用 --data-raw。

我送了 JSON,伺服器卻無法解析

使用 -d 時預設的 Content-Type 是 application/x-www-form-urlencoded,所以需要加上 -H 'Content-Type: application/json'。curl 7.82 之後可用 --json 一併設定標頭。

指令在 Windows 上不能執行

命令提示字元不解析單引號,PowerShell 的 curl 也可能是 Invoke-WebRequest 的別名。請明確呼叫 curl.exe,或改用 WSL、Git Bash 等會解析單引號的 Shell。

貼上含權杖的指令安全嗎?

cURL 轉換器 完全在瀏覽器內處理,貼上的內容不會被傳送。但轉換後的程式碼仍含有權杖,建議在提交程式碼前先改成環境變數。