headers

通过 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 对象数组

头部检查优先于文件系统（包括页面和 /public 文件）。

头部覆盖行为

如果两个头部匹配相同路径并设置相同的头部键，后设置的头部值将覆盖前者。使用以下配置时，路径 /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',
          },
        ],
      },
    ]
  },
}

头部、Cookie 和查询匹配

只有当头部、cookie 或查询值同时匹配 has 字段或不匹配 missing 字段时，才会应用头部。必须同时满足 source 和所有 has 项匹配，且所有 missing 项不匹配才会应用头部。

has 和 missing 项可包含以下字段：

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

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',
          },
        ],
      },
      // 如果源路径、查询和 cookie 都匹配，
      // 将应用 `x-authorized` 头部
      {
        source: '/specific/:path*',
        has: [
          {
            type: 'query',
            key: 'page',
            // 由于提供了值且未使用命名捕获组（如 `(?<page>home)`），
            // page 值将不可用于头部键/值
            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',
          },
        ],
      },
    ]
  },
}

支持 basePath 的头部

当结合 basePath 支持使用头部时，除非在头部设置 basePath: false，否则每个 source 都会自动添加 basePath 前缀：

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,
      },
    ]
  },
}

支持 i18n 的头部

当结合 i18n 支持使用头部时，除非在头部设置 locale: false，否则每个 source 会自动添加语言环境前缀。若使用 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)/(.*) 所以不会像 /:path* 那样匹配顶级 `/` 或 `/fr` 路由
        source: '/(.*)',
        headers: [
          {
            key: 'x-hello',
            value: 'world',
          },
        ],
      },
    ]
  },
}

缓存控制

您不能在 next.config.js 中为页面或资源设置 Cache-Control 头部，因为这些头部在生产环境中会被覆盖以确保响应和静态资源被有效缓存。

了解应用路由的缓存机制。

选项

CORS

跨源资源共享 (CORS) 是一项安全功能，允许您控制哪些站点可以访问您的资源。您可以设置 Access-Control-Allow-Origin 头部以允许特定来源访问您的路由处理器。

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 访问的页面或子域名。

如果您部署到 Vercel，则不需要此头部，除非您在 next.config.js 中声明 headers，否则它会自动添加到所有部署中。

{
  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'
}

内容安全策略

了解如何为应用添加内容安全策略。

版本历史

版本	变更
`v13.3.0`	新增 `missing` 支持。
`v10.2.0`	新增 `has` 支持。
`v9.5.0`	新增 headers 功能。

On this page