headers

headers 函式允許您從伺服器元件 (Server Component) 讀取 HTTP 傳入請求的標頭。

`headers()`

此 API 延伸自 Web Headers API。它是唯讀的，意味著您無法 set / delete 傳出請求的標頭。

import { headers } from 'next/headers'

export default function Page() {
  const headersList = headers()
  const referer = headersList.get('referer')

  return <div>Referer: {referer}</div>
}

須知事項:

headers() 是一個**動態函式 (Dynamic Function)，其返回值無法預先得知。在佈局或頁面中使用它，將會在請求時將路由轉為動態渲染 (dynamic rendering)**。

API 參考

const headersList = headers()

參數

headers 不接受任何參數。

返回值

headers 返回一個唯讀的 Web Headers 物件。

Headers.entries(): 返回一個 iterator，允許遍歷此物件中包含的所有鍵/值對。
Headers.forEach(): 對此 Headers 物件中的每個鍵/值對執行一次提供的函式。
Headers.get(): 返回一個 String 序列，包含 Headers 物件中指定名稱標頭的所有值。
Headers.has(): 返回一個布林值，表示 Headers 物件是否包含特定標頭。
Headers.keys(): 返回一個 iterator，允許遍歷此物件中包含的所有鍵。
Headers.values(): 返回一個 iterator，允許遍歷此物件中包含的所有值。

範例

與資料獲取一起使用

headers() 可以與 Suspense 資料獲取 (Suspense for Data Fetching) 結合使用。

app/page.js

import { Suspense } from 'react'
import { headers } from 'next/headers'

async function User() {
  const authorization = headers().get('authorization')
  const res = await fetch('...', {
    headers: { authorization }, // 轉發 authorization 標頭
  })
  const user = await res.json()

  return <h1>{user.name}</h1>
}

export default function Page() {
  return (
    <Suspense fallback={null}>
      <User />
    </Suspense>
  )
}

IP 位址

headers() 可用於取得客戶端的 IP 位址。

app/page.js

import { Suspense } from 'react'
import { headers } from 'next/headers'

function IP() {
  const FALLBACK_IP_ADDRESS = '0.0.0.0'
  const forwardedFor = headers().get('x-forwarded-for')

  if (forwardedFor) {
    return forwardedFor.split(',')[0] ?? FALLBACK_IP_ADDRESS
  }

  return headers().get('x-real-ip') ?? FALLBACK_IP_ADDRESS
}

export default function Page() {
  return (
    <Suspense fallback={null}>
      <IP />
    </Suspense>
  )
}

除了 x-forwarded-for 之外，headers() 還可以讀取：

x-real-ip
x-forwarded-host
x-forwarded-port
x-forwarded-proto

版本歷史

版本	變更
`v13.0.0`	引入 `headers`。

On this page