headersの使い方：リクエストヘッダーをサーバーで読む
headersでアクセス時のヘッダーを読む方法を紹介します。読み取り専用のAPIと、レスポンスヘッダーの設定との違いを学びます。
headersでアクセス時のヘッダーを読む方法を紹介します。読み取り専用のAPIと、レスポンスヘッダーの設定との違いを学びます。
対象環境と役割
App Routerで使う機能
この記事のApp Routerの例はNext.js 15以降の非同期リクエストAPIに合わせた書き方です。Next.js 16ではCache Componentsを有効にしない構成を前提とします。Pages Routerの記事とは配置先・実行場所が異なるため、プロジェクトのルーターとバージョンを先に確認してください。
TypeScriptの例は5.2以降と、利用するNext.jsが対応するNode.jsを前提にします。app/layout.tsx を備えたApp Routerプロジェクトで実行してください。
引数・戻り値・受け渡すデータ
await headers() は読み取り専用のHeaders形式のオブジェクトを返します。get(name) は文字列またはnullです。呼び出し元が送る情報を無条件に信頼しないことが重要です。
コード例を動かす
app/header-demo/page.tsx を作成する
以下はこのファイルとして配置する例です。既存ファイルへ追記する場合は、同じ名前のexportやURLが重複しないように統合してください。
import { headers } from 'next/headers';
export default async function HeaderDemo() {
const incoming = await headers();
const raw = incoming.get('accept-language');
const languageHint = raw?.slice(0, 80) ?? '指定なし';
return <main><h1>言語ヘッダー</h1><p>{languageHint}</p></main>;
}実行結果と処理の順序
ブラウザーからアクセスすると、言語設定に応じたAccept-Languageが表示されます。これはユーザーの希望を示すヒントであり、本人や所在地を証明する情報ではありません。
値の長さを制限し、通常のJSXテキストとして表示しています。ヘッダーの内容をそのままHTMLへ挿入する使い方は避けます。
つまずきやすい点と使い分け
レスポンスへsetするAPIではない
headers() が返すのは受信ヘッダーです。返却するCache-ControlなどはRoute HandlerのResponseや、適切なサーバー設定側で指定します。
転送ヘッダーと認証情報
X-Forwarded-ForやHostを信頼できるかは、前段プロキシが何を上書き・検証するかに依存します。受信したAuthorizationやCookieを外部URLへ丸ごと転送しないようにします。
静的出力で使えるか
この例はリクエストごとのサーバー処理を必要とします。output: 'export' で生成した out を配信するだけのサーバーでは実行できません。Next.jsのサーバー実行環境か別のAPIを用意します。
確認課題と実務への応用
自分で値を変えて確認する
curlの -H でAccept-Languageを変更し、結果を比較します。値の欠落と長い値も試し、表示用途と認証用途の違いを整理してください。
開発サーバーだけでなく、本番用ビルドと公開先でも確認します。URLを直接開く場合と画面内のリンクから遷移する場合、値がない場合と不正な値の場合を分けて試すと、型だけでは防げない入力の問題が見つかります。
公式資料と関連する記事
Googleの優先するニュース提供元にSEの部屋を追加
Googleで、いつも読みたい情報源を選べます。登録可否はGoogleの画面で確認できます。
候補にSEの部屋が表示されない場合は、まだ追加できません。