2026年9月23日

Nginxでレスポンスヘッダーを追加・変更する方法（add_header）

Webサーバー・Nginx

はじめに

Nginxのadd_headerディレクティブは、サーバーから返すHTTPレスポンスにカスタムヘッダーを追加するための代表的な機能です。セキュリティヘッダー（HSTS、X-Frame-Options、CSPなど）の付与、キャッシュ制御、デバッグ用のカスタムヘッダー付与など、運用上の重要な役割を担います。

しかしadd_headerはスコープごとに継承ルールが特殊で、思った通りに反映されないケースが少なくありません。本記事ではadd_headerの基本的な使い方から、alwaysオプションやmore_set_headersとの違い、よくある落とし穴までを実例とともに解説します。

症状・背景

セキュリティ診断でHSTSやCSPの不足を指摘されたが、設定したはずなのに反映されない
httpブロックで定義したヘッダーがserverブロックで上書きされて消えてしまった
4xx/5xxレスポンスにだけセキュリティヘッダーが付与されない
アップストリームから返るキャッシュヘッダーを書き換えたい

手順・設定方法

ステップ1: 現状のレスポンスヘッダーを確認する

# 現在返却されているヘッダーを確認
curl -I https://example.com/

# 詳細にリクエストとレスポンスの両方を表示
curl -sv https://example.com/ 2>&1 | grep -E '^[<>]'

# 特定のヘッダーだけを抽出
curl -sI https://example.com/ | grep -i 'strict-transport-security'

ステップ2: serverブロックに基本的なセキュリティヘッダーを追加

# 設定ファイルを編集
sudo vi /etc/nginx/conf.d/example.com.conf

# 以下を server { } 内に記述
# add_header Strict-Transport-Security "max-age=63072000; includeSubDomains" always;
# add_header X-Frame-Options "SAMEORIGIN" always;
# add_header X-Content-Type-Options "nosniff" always;
# add_header Referrer-Policy "strict-origin-when-cross-origin" always;

# 構文チェック
sudo nginx -t

ステップ3: 設定を反映してエラーレスポンスでも確認

# Nginxをリロード
sudo systemctl reload nginx

# 200/301/404すべてでヘッダーが付くか確認（alwaysオプションの効果）
curl -sI https://example.com/ | grep -i 'x-frame'
curl -sI https://example.com/notfound | grep -i 'x-frame'

# HTTP/2でも確認
curl -sI --http2 https://example.com/ | grep -i 'strict-transport'

ステップ4: location内でヘッダーを追加する場合の注意

# locationにadd_headerを書くと、上位のadd_headerは継承されない
# そのため必要なヘッダーをすべて再列挙する必要がある

# 例: locationブロックでCache-Controlを追加するときの正しい書き方
# location ~* \.(jpg|png|css|js)$ {
#     add_header Cache-Control "public, max-age=31536000, immutable" always;
#     add_header X-Frame-Options "SAMEORIGIN" always;
#     add_header X-Content-Type-Options "nosniff" always;
# }

sudo nginx -t && sudo systemctl reload nginx

注意事項

add_headerは同一階層に複数記述できますが、下位ブロック（location等）で1つでもadd_headerを書くと上位は継承されません
alwaysオプションを付けないと4xx/5xx応答にはヘッダーが付かないため、セキュリティヘッダーには必須です
アップストリームから既に同名ヘッダーが返っている場合は重複します。上書きしたいときはmore_set_headers（headers-moreモジュール）を使います
CSPなど値にカンマやスペースが含まれる場合はダブルクォートで全体を囲んでください

まとめ

1. add_headerの基本: HTTPレスポンスにカスタムヘッダーを追加する標準ディレクティブ

2. alwaysオプション: エラー応答にもヘッダーを付与するセキュリティ用途に必須のフラグ

3. 継承の罠: 子ブロックに1つでも書くと親のadd_headerが無効化される点に注意

4. 動作確認: curl -Iで常に実際のレスポンスを確認する習慣をつける

5. 上書きが必要な場合: headers-moreモジュールのmore_set_headersを検討する

Post Views: 11