headers
headers 函数的 API 参考。
headers 是一个异步函数,允许你从 Server Component 读取传入的 HTTP 请求头。
app/page.tsx
import { headers } from 'next/headers'
export default async function Page() {
const headersList = await headers()
const userAgent = headersList.get('user-agent')
}app/page.js
import { headers } from 'next/headers'
export default async function Page() {
const headersList = await headers()
const userAgent = headersList.get('user-agent')
}参考#
参数#
headers 不接受任何参数。
返回值#
headers 返回一个只读的 Web Headers 对象。
Headers.entries():返回一个iterator,用于遍历此对象中包含的所有键/值对。Headers.forEach():对此Headers对象中的每个键/值对执行一次提供的函数。Headers.get():返回一个String序列,包含Headers对象中给定名称的请求头的所有值。Headers.has():返回一个布尔值,指示Headers对象是否包含某个请求头。Headers.keys():返回一个iterator,用于遍历此对象中包含的键/值对的所有键。Headers.values():返回一个iterator,用于遍历此对象中包含的键/值对的所有值。
小知识#
headers是一个异步函数,返回 promise。你必须使用async/await或 React 的use函数。- 在 14 及更早版本中,
headers是同步函数。为了帮助向后兼容,在 Next.js 15 中你仍可以同步访问它,但此行为将来会被弃用。
- 在 14 及更早版本中,
- 由于
headers是只读的,你无法set或delete传出的请求头。 headers是一个请求时 API,其返回值无法提前得知。在路由中使用它会使该路由选择动态渲染。- 使用 Cache Components 时,在
<Suspense>边界之外调用headers()会阻止该路由被预渲染。请参阅 Next.js 在预渲染期间遇到运行时数据了解修复选项。
示例#
使用 Authorization 请求头#
app/page.js
import { headers } from 'next/headers'
export default async function Page() {
const authorization = (await headers()).get('authorization')
const res = await fetch('...', {
headers: { authorization }, // 转发 authorization 请求头
})
const user = await res.json()
return <h1>{user.name}</h1>
}版本历史#
| 版本 | 变更 |
|---|---|
v15.0.0-RC | headers 现在是异步函数。可使用 codemod。 |
v13.0.0 | 引入 headers。 |