curl 指令教學：HTTP 狀態、Redirect、TLS 與 API 排錯

curl 是 VPS、網站與 API 排錯最實用的基礎指令之一。瀏覽器只告訴你「打不開」，curl 可以進一步顯示 HTTP 狀態碼、Redirect、回應標頭、TLS 連線與每個階段花費的時間，幫你判斷問題是在 DNS、CDN、Nginx、應用程式還是上游 API。

你會學到什麼

安裝並確認 curl 可用。
只看 Header、追蹤 Redirect 或只輸出狀態碼。
判斷 301、403、404、429、502、504 的方向。
DNS 尚未切換時，用 --resolve 指定測試 IP。
查看連線、TLS 與首位元組時間。
避免把 API Token 留在 shell history 或日誌裡。

開始前先確認

你知道要測試的完整 URL，包含 http:// 或 https://。
如果是正式 API，不要把真實密碼、Token 或客戶資料貼到共用終端機。
如果站點有 CDN，記得「測 CDN 網址」與「測 Origin」是兩件不同的事。

安裝 curl

Ubuntu / Debian：

sudo apt update
sudo apt install curl ca-certificates
curl --version

ca-certificates 提供常見 CA 憑證，缺少時可能造成 HTTPS 驗證失敗。

最先做的三個 curl 檢查

只看回應 Header：

curl -I https://example.com/

追蹤 301、302 等 Redirect：

curl -IL https://example.com/

只輸出最終 HTTP 狀態碼：

curl -sS -L -o /dev/null -w "%{http_code}\n" https://example.com/

這三個指令通常已經能回答：網址是否可連、是否一直跳轉、最終落在哪個狀態碼。

常見 HTTP 狀態碼怎麼判斷

狀態碼	常見方向
`200`	伺服器有正常回應，但仍要確認內容是不是正確頁面
`301` / `302`	檢查 Redirect 目的地與是否形成循環
`401`	API 或頁面需要認證
`403`	權限、WAF、CDN、IP 限制或應用規則拒絕
`404`	路由、檔案、反向代理路徑或部署版本不符
`429`	觸發 rate limit，先降低頻率再查限制規則
`500`	應用程式內部錯誤，查看應用日誌
`502`	Nginx / CDN 找不到正常上游，先查程序與 port
`504`	上游回應太慢或 timeout，查應用效能與依賴服務

如果是 502 或 504，不要只反覆 reload Nginx。先確認應用是否真的在內部 port 回應：

curl -i http://127.0.0.1:3000/
sudo ss -lntp | grep :3000

接著查看 Linux 服務與日誌排查或 Nginx 反向代理教學。

查看完整連線與 TLS 過程

curl -vI https://example.com/

-v 會顯示 DNS 結果、連線 IP、TLS 協商與送出的 Header。輸出可能包含 Cookie、Authorization 或內部主機資訊，貼到工單或公開討論前要先遮蔽敏感內容。

遇到憑證錯誤時，不要把 -k 當成修復方式。-k 只是略過驗證，適合短暫確認「是否只有憑證驗證失敗」，正式監控與正式請求仍應使用有效憑證。

DNS 還沒切換，怎麼直接測新主機

假設網域是 app.example.com，新主機 IP 是文件示例位址 203.0.113.10：

curl -I --resolve app.example.com:443:203.0.113.10 https://app.example.com/

--resolve 只影響這次 curl，不會修改系統 DNS。它同時保留正確 Host 與 TLS SNI，因此很適合搬站或切換前測試新 Origin。

如果這個指令成功、一般網址失敗，問題多半在 DNS、CDN 或前端代理；如果兩者都失敗，就要往新主機的 Nginx、應用服務與防火牆查。

看哪個階段最慢

curl -sS -o /dev/null \
  -w 'dns=%{time_namelookup}s connect=%{time_connect}s tls=%{time_appconnect}s first_byte=%{time_starttransfer}s total=%{time_total}s\n' \
  https://example.com/

判斷方向：

dns 高：檢查 DNS resolver 與網域設定。
connect 高：檢查路由、防火牆與主機連線。
tls 高：檢查 TLS 終端、CDN 與網路延遲。
first_byte 高：常見是應用程式、資料庫或上游 API 慢。
total 高但 first_byte 正常：可能是下載內容太大或傳輸慢。

設定 timeout，避免指令一直卡住

curl --connect-timeout 5 --max-time 15 -sS -I https://example.com/

--connect-timeout 限制建立連線的時間；--max-time 限制整個操作時間。監控腳本一定要設合理 timeout，否則單一失敗目標可能把整批檢查卡住。

測試 JSON API

GET 請求：

curl -sS -H 'Accept: application/json' https://api.example.com/health

POST 測試資料：

curl -sS -X POST \
  -H 'Content-Type: application/json' \
  --data '{"message":"test"}' \
  https://api.example.com/messages

需要認證時，不要把真實 Token 寫進文章、Git 或公開工單。即使放在指令參數，也可能留在 shell history 或短暫出現在程序列表；正式環境應使用權限受控的設定檔、秘密管理工具或應用程式既有的認證機制。

curl 成功，瀏覽器卻失敗

常見原因：

瀏覽器快取了舊的 Redirect 或 DNS。
頁面 HTML 成功，但 JavaScript、CSS 或 API 請求失敗。
CORS、Cookie、CSP 只在瀏覽器環境生效。
curl 沒帶瀏覽器的 Header、登入狀態或 IPv6 路徑。

可以先檢查特定靜態資源與 API，不要只測首頁：

curl -I https://example.com/app.js
curl -i https://example.com/api/health

常見失誤

只看 200，沒確認回傳的是不是錯誤頁或登入頁。
忘記加 -L，把正常 Redirect 當成故障。
長期使用 -k 掩蓋憑證問題。
把帶 Token 的 verbose 輸出直接貼到公開場合。
有 CDN 時只測其中一層，沒有分開測 Origin。

下一步

DNS 與網域問題：DNS 故障排除
CDN 與 Origin 問題：Cloudflare 設定教學
程序與 CPU 問題：Linux 程序管理教學
應用需要正式上線：Nginx 反向代理 Node.js 教學