本文提到的工具
邊閱讀邊在瀏覽器中開啟工具,立即試試整個流程。
看得懂貼上的 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 轉換器 完全在瀏覽器內處理,貼上的內容不會被傳送。但轉換後的程式碼仍含有權杖,建議在提交程式碼前先改成環境變數。
