headers

headers 函数允许你从服务器组件中读取 HTTP 传入请求头。

`headers()`

这个 API 扩展了 Web Headers API。它是只读的,意味着你不能 set / delete 传出请求头。

app/page.tsx

import { headers } from "next/headers";
 
export default function Page() {
  const headersList = headers();
  const referer = headersList.get("referer");
 
  return <div>Referer: {referer}</div>;
}

app/page.js

import { headers } from "next/headers";
 
export default function Page() {
  const headersList = headers();
  const referer = headersList.get("referer");
 
  return <div>Referer: {referer}</div>;
}

值得注意的是:

headers() 是一个**动态函数,其返回值无法提前知道。在布局或页面中使用它会使路由在请求时进入动态渲染**。

API 参考

const headersList = headers();

参数

headers 不接受任何参数。

返回值

headers 返回一个只读的 Web Headers 对象。

Headers.entries(): 返回一个 iterator,允许遍历此对象中包含的所有键/值对。
Headers.forEach(): 对 Headers 对象中的每个键/值对执行提供的函数一次。
Headers.get(): 返回 Headers 对象中给定名称的头的所有值的 String 序列。
Headers.has(): 返回一个布尔值,说明 Headers 对象是否包含某个头。
Headers.keys(): 返回一个 iterator,允许遍历此对象中包含的所有键/值对的键。
Headers.values(): 返回一个 iterator,允许遍历此对象中包含的所有键/值对的值。

示例

与数据获取一起使用

headers() 可以与数据获取的 Suspense 结合使用。

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`。