headers
为你的 Next.js 应用添加自定义 HTTP 标头。
Headers 允许你针对给定路径,为传入请求的响应设置自定义 HTTP 头。
要设置自定义 HTTP 头,可以使用 next.config.js 中的 headers 键:
module.exports = {
headers() {
return [
{
source: '/about',
headers: [
{
key: 'x-custom-header',
value: 'my custom header value',
},
{
key: 'x-another-custom-header',
value: 'my other custom header value',
},
],
},
]
},
}headers 可以定义为同步或异步函数。它应返回(或解析为)一个由对象组成的数组,这些对象具有 source 和 headers 属性:
source是传入请求的路径模式。headers是响应头对象组成的数组,具有key和value属性。basePath:false或undefined- 如果为 false,匹配时将不包含 basePath,只能用于外部 rewrites。locale:false或undefined- 匹配时是否不应包含 locale。has是由 has 对象组成的数组,具有type、key和value属性。missing是由 missing 对象组成的数组,具有type、key和value属性。
Headers 会在文件系统(包括页面和 /public 文件)之前被检查。
Header 覆盖行为#
如果两个 header 匹配同一路径并设置了相同的 header key,则最后一个 header key 会覆盖第一个。使用下面的 headers 时,路径 /hello 的 header x-hello 将为 world,因为最后设置的 header 值是 world。
module.exports = {
headers() {
return [
{
source: '/:path*',
headers: [
{
key: 'x-hello',
value: 'there',
},
],
},
{
source: '/hello',
headers: [
{
key: 'x-hello',
value: 'world',
},
],
},
]
},
}路径匹配#
允许路径匹配,例如 /blog/:slug 将匹配 /blog/first-post(不匹配嵌套路径):
module.exports = {
headers() {
return [
{
source: '/blog/:slug',
headers: [
{
key: 'x-slug',
value: ':slug', // 匹配的参数可用于 value 中
},
{
key: 'x-slug-:slug', // 匹配的参数可用于 key 中
value: 'my other custom header value',
},
],
},
]
},
}模式 /blog/:slug 匹配 /blog/first-post 和 /blog/post-1,但不匹配像 /blog/a/b 这样的嵌套路径。模式锚定在开头,因此 /blog/:slug 不会匹配 /archive/blog/first-post。
你可以在参数上使用修饰符:*(零个或多个)、+(一个或多个)、?(零个或一个)。例如,/blog/:slug* 匹配 /blog、/blog/a 和 /blog/a/b/c。
有关更多细节,请阅读 path-to-regexp 文档。
通配符路径匹配#
要匹配通配符路径,可以在参数后使用 *,例如 /blog/:slug* 将匹配 /blog/a/b/c/d/hello-world:
module.exports = {
headers() {
return [
{
source: '/blog/:slug*',
headers: [
{
key: 'x-slug',
value: ':slug*', // 匹配的参数可用于 value 中
},
{
key: 'x-slug-:slug*', // 匹配的参数可用于 key 中
value: 'my other custom header value',
},
],
},
]
},
}正则路径匹配#
要匹配正则路径,可以在参数后将正则表达式包裹在括号中,例如 /blog/:slug(\\d{1,}) 将匹配 /blog/123,但不匹配 /blog/abc:
module.exports = {
headers() {
return [
{
source: '/blog/:post(\\d{1,})',
headers: [
{
key: 'x-post',
value: ':post',
},
],
},
]
},
}以下字符 (、)、{、}、:、*、+、? 用于正则路径匹配,因此当它们在 source 中作为非特殊值使用时,必须通过在它们前面添加 \\ 进行转义:
module.exports = {
headers() {
return [
{
// 这将匹配被请求的 `/english(default)/something`
source: '/english\\(default\\)/:slug',
headers: [
{
key: 'x-header',
value: 'value',
},
],
},
]
},
}Header、Cookie 和 Query 匹配#
要仅在 header、cookie 或 query 值也匹配时应用 header,可以使用 has 字段,或使用 missing 字段要求不匹配。要使 header 生效,source 和所有 has 项都必须匹配,并且所有 missing 项都必须不匹配。
has 和 missing 项可以具有以下字段:
type:String- 必须是header、cookie、host或query之一。key:String- 从所选类型中要匹配的 key。value:String或undefined- 要检查的值,如果为 undefined,则任何值都会匹配。可以使用类似正则的字符串来捕获值的特定部分,例如,如果对first-second使用值first-(?<paramName>.*),则second可在目标中通过:paramName使用。
module.exports = {
headers() {
return [
// 如果存在 header `x-add-header`,
// 则会应用 `x-another-header` header
{
source: '/:path*',
has: [
{
type: 'header',
key: 'x-add-header',
},
],
headers: [
{
key: 'x-another-header',
value: 'hello',
},
],
},
// 如果不存在 header `x-no-header`,
// 则会应用 `x-another-header` header
{
source: '/:path*',
missing: [
{
type: 'header',
key: 'x-no-header',
},
],
headers: [
{
key: 'x-another-header',
value: 'hello',
},
],
},
// 如果 source、query 和 cookie 都匹配,
// 则会应用 `x-authorized` header
{
source: '/specific/:path*',
has: [
{
type: 'query',
key: 'page',
// page 的值在 header 的 key/value 中将不可用,
// 因为提供了 value 且没有使用命名捕获组,
// 例如 (?<page>home)
value: 'home',
},
{
type: 'cookie',
key: 'authorized',
value: 'true',
},
],
headers: [
{
key: 'x-authorized',
value: ':authorized',
},
],
},
// 如果存在 header `x-authorized` 且
// 包含匹配的值,则会应用 `x-another-header`
{
source: '/:path*',
has: [
{
type: 'header',
key: 'x-authorized',
value: '(?<authorized>yes|true)',
},
],
headers: [
{
key: 'x-another-header',
value: ':authorized',
},
],
},
// 如果 host 为 `example.com`,
// 则会应用此 header
{
source: '/:path*',
has: [
{
type: 'host',
value: 'example.com',
},
],
headers: [
{
key: 'x-another-header',
value: ':authorized',
},
],
},
]
},
}支持 basePath 的 Headers#
在 headers 中利用 basePath 支持时,每个 source 都会自动加上 basePath 前缀,除非你为该 header 添加 basePath: false:
module.exports = {
basePath: '/docs',
headers() {
return [
{
source: '/with-basePath', // 变为 /docs/with-basePath
headers: [
{
key: 'x-hello',
value: 'world',
},
],
},
{
source: '/without-basePath', // 由于设置了 basePath: false,不会被修改
headers: [
{
key: 'x-hello',
value: 'world',
},
],
basePath: false,
},
]
},
}支持 i18n 的 Headers#
在 headers 中利用 i18n 支持时,每个 source 都会自动加上前缀以处理配置的 locales,除非你为该 header 添加 locale: false。如果使用了 locale: false,你必须为 source 加上 locale 前缀,才能正确匹配。
在 headers 中利用 i18n 支持时,每个 source 都会自动加上前缀以处理配置的 locales,除非你为该 header 添加 locale: false。如果使用了 locale: false,你必须为 source 加上 locale 前缀,才能正确匹配。
module.exports = {
i18n: {
locales: ['en', 'fr', 'de'],
defaultLocale: 'en',
},
headers() {
return [
{
source: '/with-locale', // 自动处理所有 locale
headers: [
{
key: 'x-hello',
value: 'world',
},
],
},
{
// 由于设置了 locale: false,不会自动处理 locale
source: '/nl/with-locale-manual',
locale: false,
headers: [
{
key: 'x-hello',
value: 'world',
},
],
},
{
// 这匹配 '/',因为 `en` 是 defaultLocale
source: '/en',
locale: false,
headers: [
{
key: 'x-hello',
value: 'world',
},
],
},
{
// 这会被转换为 /(en|fr|de)/(.*),因此不会像 /:path* 那样
// 匹配顶层 `/` 或 `/fr` 路由
source: '/(.*)',
headers: [
{
key: 'x-hello',
value: 'world',
},
],
},
]
},
}Cache-Control#
Next.js 会为真正不可变的资源设置 public, max-age=31536000, immutable 的 Cache-Control 头。它无法被覆盖。这些不可变文件的文件名中包含 SHA 哈希,因此可以安全地无限期缓存。例如静态图片导入。你无法在 next.config.js 中为这些资源设置 Cache-Control 头。
不过,你可以为其他响应或数据设置 Cache-Control 头。
了解更多关于 App Router 中缓存的信息。
如果你需要重新验证已静态生成页面的缓存,可以通过在页面的 getStaticProps 函数中设置 revalidate prop 来实现。
要缓存来自 API Route 的响应,可以使用 res.setHeader:
import type { NextApiRequest, NextApiResponse } from 'next'
type ResponseData = {
message: string
}
export default function handler(
req: NextApiRequest,
res: NextApiResponse<ResponseData>
) {
res.setHeader('Cache-Control', 's-maxage=86400')
res.status(200).json({ message: 'Hello from Next.js!' })
}export default function handler(req, res) {
res.setHeader('Cache-Control', 's-maxage=86400')
res.status(200).json({ message: 'Hello from Next.js!' })
}你还可以在 getServerSideProps 中使用缓存头(Cache-Control)来缓存动态响应。例如,使用 stale-while-revalidate。
import { GetStaticProps, GetStaticPaths, GetServerSideProps } from 'next'
// 此值在十秒内被视为新鲜(s-maxage=10)。
// 如果在接下来的 10 秒内重复请求,之前缓存的值仍然是新鲜的。
// 如果在 59 秒之前重复请求,缓存的值将是旧的但仍会渲染(stale-while-revalidate=59)。
//
// 在后台,会发出重新验证请求,用新鲜的值填充缓存。
// 如果你刷新页面,就会看到新值。
export const getServerSideProps = (async (context) => {
context.res.setHeader(
'Cache-Control',
'public, s-maxage=10, stale-while-revalidate=59'
)
return {
props: {},
}
}) satisfies GetServerSideProps// 此值在十秒内被视为新鲜(s-maxage=10)。
// 如果在接下来的 10 秒内重复请求,之前缓存的值仍然是新鲜的。
// 如果在 59 秒之前重复请求,缓存的值将是旧的但仍会渲染(stale-while-revalidate=59)。
//
// 在后台,会发出重新验证请求,用新鲜的值填充缓存。
// 如果你刷新页面,就会看到新值。
export async function getServerSideProps({ req, res }) {
res.setHeader(
'Cache-Control',
'public, s-maxage=10, stale-while-revalidate=59'
)
return {
props: {},
}
}选项#
CORS#
跨源资源共享(CORS)是一项安全特性,可让你控制哪些站点可以访问你的资源。你可以设置 Access-Control-Allow-Origin 头,以允许特定来源访问你的 API EndpointsRoute Handlers。
headers() {
return [
{
source: "/api/:path*",
headers: [
{
key: "Access-Control-Allow-Origin",
value: "*", // 设置你的 origin
},
{
key: "Access-Control-Allow-Methods",
value: "GET, POST, PUT, DELETE, OPTIONS",
},
{
key: "Access-Control-Allow-Headers",
value: "Content-Type, Authorization",
},
],
},
];
},X-DNS-Prefetch-Control#
此头控制 DNS 预取,允许浏览器主动对外部链接、图片、CSS、JavaScript 等执行域名解析。这种预取在后台执行,因此当被引用的项目被需要时,DNS 更有可能已经被解析。这减少了用户点击链接时的延迟。
{
key: 'X-DNS-Prefetch-Control',
value: 'on'
}Strict-Transport-Security#
此头告知浏览器只应通过 HTTPS 访问,而不是使用 HTTP。使用下面的配置,所有当前和未来的子域名都将在 max-age 为 2 年的时间内使用 HTTPS。这会阻止通过仅支持 HTTP 提供的页面或子域名的访问。
{
key: 'Strict-Transport-Security',
value: 'max-age=63072000; includeSubDomains; preload'
}X-Frame-Options#
此头指示是否允许网站显示在 iframe 中。这可以防止点击劫持攻击。
此头已被 CSP 的 frame-ancestors 选项取代,后者在现代浏览器中有更好的支持(配置详情请参阅内容安全策略)。
{
key: 'X-Frame-Options',
value: 'SAMEORIGIN'
}Permissions-Policy#
此头允许你控制浏览器中可以使用哪些特性和 API。它以前名为 Feature-Policy。
{
key: 'Permissions-Policy',
value: 'camera=(), microphone=(), geolocation=(), browsing-topics=()'
}X-Content-Type-Options#
此头可阻止浏览器在未显式设置 Content-Type 头时尝试猜测内容类型。这可以防止允许用户上传和共享文件的网站遭受 XSS 攻击。
例如,用户试图下载图片,但它被当作不同的 Content-Type(如可执行文件)处理,这可能是恶意的。此头也适用于下载浏览器扩展。此头唯一有效的值是 nosniff。
{
key: 'X-Content-Type-Options',
value: 'nosniff'
}Referrer-Policy#
此头控制浏览器从当前网站(来源)导航到另一个网站时包含多少信息。
{
key: 'Referrer-Policy',
value: 'origin-when-cross-origin'
}Content-Security-Policy#
了解更多关于为应用添加内容安全策略的信息。
版本历史#
| 版本 | 变更 |
|---|---|
v13.3.0 | 新增 missing。 |
v10.2.0 | 新增 has。 |
v9.5.0 | 新增 Headers。 |