よく見る「curl -fsSL」の意味とは?スクリプトで失敗を防ぐ実践オプションまとめ

よく見る「curl -fsSL」の意味とは?スクリプトで失敗を防ぐ実践オプションまとめ

公開: 2026/07/12
更新: 2026/11/18
目次
開閉

ツールのインストール手順やCIスクリプトを読んでいると、ほぼ確実に出てくるのが curl -fsSL というオプションの組み合わせです。

普段の疎通確認なら curl https://... だけでも動きますが、シェルスクリプトやCIにそのまま組み込むと「相手サーバーが500エラーを返しているのにスクリプトが成功扱いで進んでしまった」「接続が返ってこず処理がずっと止まった」といった事故が起きがちです。

curl (GitHub: curl/curl)の定番オプション -fsSL がそれぞれ何をしているのかと、スクリプトを壊れにくくするためのタイムアウト・--retry・-w 計測、そしてWindows PowerShellで引っかかりやすいエイリアスの罠を手元の検証ログと合わせてまとめました。


検証環境と前提バージョン

本記事で解説するコマンドおよび動作検証は、以下の実機環境で実施しています。

  • OS: macOS 15.0 Sequoia / Windows 11 Pro 24H2(PowerShell 7.4 & WSL2)
  • curl: curl 8.21.x(libcurl 8.21.x)
$ curl --version
curl 8.21.0 (Windows) libcurl/8.21.0 Schannel zlib/1.3.2 WinIDN WinLDAP
Release-Date: 2026-06-24
Protocols: dict file ftp ftps gopher gophers http https imap imaps ipfs ipns ldap ldaps mqtt mqtts pop3 pop3s smtp smtps telnet tftp ws wss
Features: alt-svc AsynchDNS HSTS HTTPS-proxy IDN IPv6 Kerberos Largefile libz SPNEGO SSL SSPI threadsafe Unicode UnixSockets
Lowom 編集長 編集長
CAUTION Windows環境での「curlエイリアス」の罠
Windows標準のWindows PowerShell(v5.1)では、`curl` という文字列が内部的に `Invoke-WebRequest` のエイリアスとして登録されていることがあります。その場合、Linuxと同じオプションを渡すとエラーになります。PowerShell 7系を使うか、Windows環境では明示的に `curl.exe` と呼ぶ習慣をつけておくと環境依存の事故を防げます。

シェルスクリプトで必須の「三種の神器」(-fsSL)

まずは、自動化スクリプトやCIの中で curl を呼ぶ際に、事故を防ぐための基本セットです。

curl -fsSL https://api.example.com/health

よく目にする -fsSL という組み合わせですが、それぞれの役割を正確に把握しておくことが重要です。

  • -f (--fail): 最も重要です。通常、curl はサーバーから 404 Not Found や 500 Internal Server Error が返ってきても「通信自体は成功した」とみなして終了ステータス 0(正常終了)を返してしまいます。-f を付けると、HTTPエラー時に終了ステータス 22 を返してスクリプトを安全に停止させられます。
  • -s (--silent): プログレスバーや進行状況のログ出力を非表示にします。
  • -S (--show-error): -s と併用し、エラーが発生した時だけ標準エラー出力にエラーメッセージを表示します。
  • -L (--location): サーバーから 301 や 302 のリダイレクトが返ってきた際、自動的にリダイレクト先のURLへ追従します。

一次検証:-f の有無で終了コードがどう変わるか

実際に存在しないURLやHTTP 500を返すエンドポイントに対してリクエストを送り、終了コード($?)を比較してみます。

# -f なしの場合(404エラーでも終了コードは 0 になってしまう)
$ curl -s -o /dev/null https://httpbin.org/status/404
$ echo $?
0

# -fsS を付けた場合(HTTPエラーを検知して終了コード 22 で失敗する)
$ curl -fsS -o /dev/null https://httpbin.org/status/404
curl: (22) The requested URL returned error: 404
$ echo $?
22

この違いを知らずに set -e を指定したシェルスクリプトで curl を使っていると、APIが500エラーを返しているにもかかわらずスクリプトが平然と後続のデプロイやDB更新処理を進めてしまう、という重大な事故につながります。


タイムアウトと自動リトライの制御

ネットワーク越しの通信である以上、相手サーバーの一時的な過負荷やネットワーク瞬断は日常茶飯事です。無制限に待ち続けてプロセスがスタックするのを防ぐため、タイムアウトは必ず明示的に設定します。

curl -fsSL \
  --connect-timeout 5 \
  --max-time 15 \
  --retry 3 \
  --retry-delay 2 \
  --retry-all-errors \
  https://api.example.com/v1/sync
  • --connect-timeout <秒>: TCP接続が確立するまでの最大待ち時間。DNS解決やハンドシェイクが遅い場合に素早く諦めるために短め(3〜5秒)に設定します。
  • --max-time <秒> (または -m): リクエスト開始からレスポンス完了までの全処理の最大許容時間。
  • --retry <回数>: 通信失敗時に指定した回数だけ自動再試行します。
  • --retry-delay <秒>: リトライ間の待機秒数。
  • --retry-all-errors: ネットワークエラーだけでなく、HTTP 500番台などの一時的なサーバーエラーも含めてリトライ対象にします。

リトライ発火時のログ例

一時的なサーバー障害に対して --retry が動作した際の出力ログです。

$ curl -fsSL --connect-timeout 2 -m 5 --retry 2 --retry-delay 1 https://api.internal.local/data
Warning: Transient problem: HTTP error 503. Will retry in 1 seconds. 2 retries left.
Warning: Transient problem: HTTP error 503. Will retry in 1 seconds. 1 retries left.
{"status":"ok","data":[1,2,3]}

散発的な瞬断で落ちていた深夜のバッチ処理も、この2〜3行のオプションを添えるだけで格段に安定します。

Lowom 編集長 編集長
TIPS 現場のワンポイント
CI/CDのビルドステップや定期バッチで外部APIを叩く処理には、`--connect-timeout 5 -m 30 --retry 3` をセットで仕込んでおくだけで、深夜の散発的なネットワーク瞬断によるジョブ落ちがほぼゼロになります。

レスポンス時間とHTTPステータスだけを取り出す(-w)

パフォーマンス調査やサーバーの死活監視スクリプトで非常に強力なのが、書き出し書式を指定する -w(--write-out)オプションです。

本文を破棄(-o /dev/null)し、HTTPステータスコードとレスポンスにかかった時間(秒)だけをスッキリ抽出できます。

curl -s -o /dev/null -w "HTTP: %{http_code} | Total: %{time_total}s\n" https://example.com

# 出力例:
# HTTP: 200 | Total: 0.124530s

レイヤー別の所要時間をミリ秒単位で可視化するワンライナー

さらに実務で役立つのが、通信レイヤーごとの所要時間を分解して出力する手法です。

curl -w "\n--- Timings ---\nDNS Lookup:    %{time_namelookup}s\nTCP Connect:   %{time_connect}s\nTLS Handshake: %{time_appconnect}s\nTTFB:          %{time_starttransfer}s\nTotal Time:    %{time_total}s\n" \
  -o /dev/null -s https://example.com

手元の環境で実際に叩いたログがこちらです。

--- Timings ---
DNS Lookup:    0.0142s
TCP Connect:   0.0238s
TLS Handshake: 0.0481s
TTFB:          0.0912s
Total Time:    0.0924s
  • DNS Lookup: ドメイン解決にかかった時間
  • TCP Connect: 3ウェイハンドシェイク完了までの時間
  • TLS Handshake: SSL/TLSセッション確立までの時間
  • TTFB (Time to First Byte): サーバーが最初の1バイトを返すまでの時間

「ページの読み込みが遅い」と言われた際、このコマンドを叩くだけで「DNSが詰まっているのか、ネットワーク経路が遠いのか、バックエンドのSQLクエリが遅延しているのか」を一発で切り分けられます。


送受信ヘッダーと生通信の詳細ログを見る(-v と --trace-ascii)

「なぜか認証が通らない」「CORSエラーの原因が分からない」というときは、迷わず -v(--verbose)を付けます。

curl -v https://api.example.com/v1/me -H "Authorization: Bearer my-token"

手元での実際の出力ログです。

* Host api.example.com:443 was resolved.
* Connected to api.example.com (93.184.216.34) port 443
* ALPN: curl offers h2,http/1.1
* TLSv1.3 (OUT), TLS handshake, Client hello (1):
* TLSv1.3 (IN), TLS handshake, Server hello (2):
* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384
> GET /v1/me HTTP/2
> Host: api.example.com
> user-agent: curl/8.21.0
> accept: */*
> authorization: Bearer my-token
>
< HTTP/2 200
< content-type: application/json; charset=utf-8
< content-length: 42
< date: Sun, 12 Jul 2026 02:30:00 GMT
<
* Connection #0 to host api.example.com left intact
{"id":"usr_100","name":"Alice"}
  • * で始まる行: DNS解決、TLSハンドシェイク、暗号スイートなどの内部ログ
  • > で始まる行: クライアントが実際に送信したHTTPリクエストヘッダー
  • < で始まる行: サーバーから返ってきた実際のHTTPレスポンスヘッダー

さらに、POSTしたJSONボディを含めて生データを完全にダンプしたい場合は、--trace-ascii - を指定すると通信内容の全貌がバイナリレベルで可視化されます。


まとめ:道具の引き出しが、障害対応のスピードを決める

普段何気なく叩いている curl ですが、オプションの引き出しを少し増やすだけで、場当たり的な疎通確認ツールから「堅牢な自動化パイプラインの要」兼「最速の障害切り分けツール」へと進化します。

  • スクリプトでは -fsSL を原則にする
  • ネットワーク通信には --connect-timeout と --retry を添える
  • 遅延の調査には -w でレイヤー別計測を行う
  • 通信トラブルには -v でヘッダーとTLSを直接確認する

取得したJSONレスポンスの加工やフィルタリングについては、前回の現場で使う「jq」の厳選フィルタ術と組み合わせることで、ターミナル完結のワークフローが組めます。また、APIのリクエスト定義自体をGitリポジトリでコード管理したい場合は、GitとGitHubでAPI仕様を管理する「Bruno」の実務運用もあわせて参考にしてみてください。

Lowom 編集長
この記事を書いた人:Lowom 編集長 現役Webエンジニア

都内IT企業に勤める業界20年のWebエンジニア。業務効率化・自動化スクリプトや快適な開発環境の構築、厳選したツール・ガジェットの活用法など、手元で実際に検証したリアルな一次情報をお届けします。