标头

Headers 允许你在给定路径上为传入请求的响应设置自定义 HTTP 标头。

要设置自定义 HTTP 标头，你可以在 next.config.js 中使用 headers 键：

next.config.js

module.exports = {
  async 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，只能用于外部重写。
locale：false 或 undefined - 是否在匹配时不包含区域设置。
has 是一个具有 type、key 和 value 属性的 has 对象数组。
missing 是一个具有 type、key 和 value 属性的 missing 对象数组。

Headers 会在文件系统（包括页面和 /public 文件）之前进行检查。

如果两个 headers 匹配相同的路径并设置相同的标头键，则最后一个标头键将覆盖第一个。使用以下 headers，路径 /hello 将导致标头 x-hello 为 world，因为最后设置的标头值是 world。

next.config.js

module.exports = {
  async headers() {
    return [
      {
        source: '/:path*',
        headers: [
          {
            key: 'x-hello',
            value: 'there',
          },
        ],
      },
      {
        source: '/hello',
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
      },
    ]
  },
}

路径匹配

允许路径匹配，例如 /blog/:slug 将匹配 /blog/hello-world（不包括嵌套路径）：

next.config.js

module.exports = {
  async headers() {
    return [
      {
        source: '/blog/:slug',
        headers: [
          {
            key: 'x-slug',
            value: ':slug', // 匹配的参数可以在值中使用
          },
          {
            key: 'x-slug-:slug', // 匹配的参数可以在键中使用
            value: 'my other custom header value',
          },
        ],
      },
    ]
  },
}

通配符路径匹配

要匹配通配符路径，你可以在参数后使用 *，例如 /blog/:slug* 将匹配 /blog/a/b/c/d/hello-world：

next.config.js

module.exports = {
  async headers() {
    return [
      {
        source: '/blog/:slug*',
        headers: [
          {
            key: 'x-slug',
            value: ':slug*', // 匹配的参数可以在值中使用
          },
          {
            key: 'x-slug-:slug*', // 匹配的参数可以在键中使用
            value: 'my other custom header value',
          },
        ],
      },
    ]
  },
}

正则表达式路径匹配

要匹配正则表达式路径，你可以在参数后用括号包裹正则表达式，例如 /blog/:slug(\\d{1,}) 将匹配 /blog/123 但不匹配 /blog/abc：

next.config.js

module.exports = {
  async headers() {
    return [
      {
        source: '/blog/:post(\\d{1,})',
        headers: [
          {
            key: 'x-post',
            value: ':post',
          },
        ],
      },
    ]
  },
}

以下字符 (、)、{、}、:、*、+、? 用于正则表达式路径匹配，因此当在 source 中作为非特殊值使用时，必须通过在它们前面添加 \\ 来转义：

next.config.js

module.exports = {
  async headers() {
    return [
      {
        // 这将匹配请求 `/english(default)/something`
        source: '/english\\(default\\)/:slug',
        headers: [
          {
            key: 'x-header',
            value: 'value',
          },
        ],
      },
    ]
  },
}

Header、Cookie 和 Query 匹配

要仅在 header、cookie 或 query 值也匹配 has 字段或不匹配 missing 字段时应用标头，可以使用这些字段。source 和所有 has 项必须匹配，且所有 missing 项必须不匹配，才能应用标头。

has 和 missing 项可以具有以下字段：

type：String - 必须是 header、cookie、host 或 query 之一。
key：String - 要匹配的所选类型的键。
value：String 或 undefined - 要检查的值，如果为 undefined，则任何值都将匹配。可以使用类似正则表达式的字符串来捕获值的特定部分，例如，如果值 first-(?<paramName>.*) 用于 first-second，则 second 将可在目标中使用 :paramName。

next.config.js

module.exports = {
  async headers() {
    return [
      // 如果存在标头 `x-add-header`，
      // 将应用 `x-another-header` 标头
      {
        source: '/:path*',
        has: [
          {
            type: 'header',
            key: 'x-add-header',
          },
        ],
        headers: [
          {
            key: 'x-another-header',
            value: 'hello',
          },
        ],
      },
      // 如果不存在标头 `x-no-header`，
      // 将应用 `x-another-header` 标头
      {
        source: '/:path*',
        missing: [
          {
            type: 'header',
            key: 'x-no-header',
          },
        ],
        headers: [
          {
            key: 'x-another-header',
            value: 'hello',
          },
        ],
      },
      // 如果 source、query 和 cookie 都匹配，
      // 将应用 `x-authorized` 标头
      {
        source: '/specific/:path*',
        has: [
          {
            type: 'query',
            key: 'page',
            // page 值将不可用于
            // 标头键/值，因为提供了值且
            // 不使用命名捕获组，例如 (?<page>home)
            value: 'home',
          },
          {
            type: 'cookie',
            key: 'authorized',
            value: 'true',
          },
        ],
        headers: [
          {
            key: 'x-authorized',
            value: ':authorized',
          },
        ],
      },
      // 如果存在标头 `x-authorized` 且
      // 包含匹配的值，将应用 `x-another-header`
      {
        source: '/:path*',
        has: [
          {
            type: 'header',
            key: 'x-authorized',
            value: '(?<authorized>yes|true)',
          },
        ],
        headers: [
          {
            key: 'x-another-header',
            value: ':authorized',
          },
        ],
      },
      // 如果主机是 `example.com`，
      // 将应用此标头
      {
        source: '/:path*',
        has: [
          {
            type: 'host',
            value: 'example.com',
          },
        ],
        headers: [
          {
            key: 'x-another-header',
            value: ':authorized',
          },
        ],
      },
    ]
  },
}

Headers 的 basePath 支持

当在 headers 中使用 basePath 支持时，每个 source 都会自动添加 basePath 前缀，除非你在 header 中添加 basePath: false：

next.config.js

module.exports = {
  basePath: '/docs',
 
  async 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,
      },
    ]
  },
}

Headers 的 i18n 支持

当在 headers 中使用 i18n 支持时，每个 source 都会自动添加前缀以处理配置的 locales，除非你在 header 中添加 locale: false。如果使用 locale: false，你必须为 source 添加区域设置前缀才能正确匹配。

next.config.js

module.exports = {
  i18n: {
    locales: ['en', 'fr', 'de'],
    defaultLocale: 'en',
  },
 
  async headers() {
    return [
      {
        source: '/with-locale', // 自动处理所有区域设置
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
      },
      {
        // 不会自动处理区域设置，因为设置了 locale: false
        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)/(.*)，因此不会匹配顶级
        // `/` 或 `/fr` 路由，就像 /:path* 会匹配的那样
        source: '/(.*)',
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
      },
    ]
  },
}

Cache-Control

Next.js 为真正不可变的资产设置 Cache-Control 标头为 public, max-age=31536000, immutable。它不能被覆盖。这些不可变文件的文件名中包含 SHA 哈希，因此可以安全地无限期缓存。例如，静态图片导入。你不能在 next.config.js 中为这些资产设置 Cache-Control 标头。

但是，你可以为其他响应或数据设置 Cache-Control 标头。

如果你需要重新验证已静态生成的页面的缓存，可以通过在页面的 getStaticProps 函数中设置 revalidate 属性来实现。

要缓存来自 API Route 的响应，你可以使用 res.setHeader：

pages/api/hello.ts

TypeScript

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!' })
}

你还可以在 getServerSideProps 中使用缓存标头（Cache-Control）来缓存动态响应。例如，使用 stale-while-revalidate。

pages/index.tsx

TypeScript

import { GetStaticProps, GetStaticPaths, GetServerSideProps } from 'next'
 
// 此值在 10 秒内被认为是新鲜的（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

选项

CORS

跨源资源共享（CORS）是一项安全功能，允许你控制哪些站点可以访问你的资源。你可以设置 Access-Control-Allow-Origin 标头以允许特定源访问你的API 端点。

async headers() {
    return [
      {
        source: "/api/:path*",
        headers: [
          {
            key: "Access-Control-Allow-Origin",
            value: "*", // 设置你的源
          },
          {
            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。使用以下配置，所有当前和未来的子域将在 2 年的 max-age 期间使用 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。