headers
标头允许你在给定路径的请求响应中设置自定义 HTTP 标头。
要设置自定义 HTTP 标头,可以在 next.config.js
中使用 headers
键:
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
。
路径匹配
支持路径匹配,例如 /blog/:slug
将匹配 /blog/hello-world
(不支持嵌套路径):
通配符路径匹配
要匹配通配符路径,可以在参数后使用 *
,例如 /blog/:slug*
将匹配 /blog/a/b/c/d/hello-world
:
正则表达式路径匹配
要匹配正则表达式路径,可以将正则表达式包裹在参数后的括号中,例如 /blog/:slug(\\d{1,})
将匹配 /blog/123
但不匹配 /blog/abc
:
以下字符 (
、)
、{
、}
、:
、*
、+
、?
用于正则表达式路径匹配,因此当在 source
中作为非特殊值使用时,必须通过在前面添加 \\
进行转义:
标头、Cookie 和查询匹配
要仅在标头、cookie 或查询值也匹配 has
字段或不匹配 missing
字段时应用标头,可以使用这两个字段。必须同时匹配 source
和所有 has
项,并且所有 missing
项都不匹配,才会应用标头。
has
和 missing
项可以包含以下字段:
type
:String
- 必须是header
、cookie
、host
或query
之一key
:String
- 要匹配的选定类型的键value
:String
或undefined
- 要检查的值,如果未定义则匹配任何值。可以使用类似正则表达式的字符串捕获值的特定部分,例如如果值first-(?<paramName>.*)
用于first-second
,则second
可以在目标中使用:paramName
支持 basePath 的标头
当与标头一起使用 basePath
支持 时,每个 source
会自动添加 basePath
前缀,除非你在标头中添加 basePath: false
:
支持 i18n 的标头
当与标头一起使用 i18n
支持 时,每个 source
会自动添加前缀以处理配置的 locales
,除非你在标头中添加 locale: false
。如果使用 locale: false
,则必须在 source
前添加语言环境才能正确匹配。
Cache-Control
Next.js 为真正不可变的资源设置 Cache-Control
标头为 public, max-age=31536000, immutable
。此设置无法覆盖。这些不可变文件在文件名中包含 SHA 哈希,因此可以安全地无限期缓存。例如,静态图片导入。你无法在 next.config.js
中为这些资源设置 Cache-Control
标头。
但是,你可以为其他响应或数据设置 Cache-Control
标头。
如果需要重新验证已 静态生成 的页面的缓存,可以通过在页面的 getStaticProps
函数中设置 revalidate
属性来实现。
要缓存 API 路由 的响应,可以使用 res.setHeader
:
你也可以在 getServerSideProps
中使用缓存标头(Cache-Control
)来缓存动态响应。例如,使用 stale-while-revalidate
。
选项
CORS
跨源资源共享 (CORS) 是一项安全功能,允许你控制哪些站点可以访问你的资源。你可以设置 Access-Control-Allow-Origin
标头以允许特定来源访问你的 API 端点。
X-DNS-Prefetch-Control
此标头 控制 DNS 预取,允许浏览器主动解析外部链接、图片、CSS、JavaScript 等的域名。此预取在后台执行,因此在需要引用项目时 DNS 更有可能已解析。这减少了用户点击链接时的延迟。
Strict-Transport-Security
此标头 通知浏览器应仅使用 HTTPS 访问,而不是使用 HTTP。使用以下配置,所有当前和未来的子域将使用 HTTPS,max-age
为 2 年。这会阻止访问只能通过 HTTP 提供的页面或子域。
X-Frame-Options
此标头 指示是否应允许站点在 iframe
中显示。这可以防止点击劫持攻击。
此标头已被 CSP 的 frame-ancestors
选项取代,后者在现代浏览器中有更好的支持(有关配置详情,请参阅 内容安全策略)。
权限策略 (Permissions-Policy)
该头部字段 允许您控制浏览器中可以使用哪些功能和 API。它之前的名称是 Feature-Policy
。
X-内容类型选项 (X-Content-Type-Options)
该头部字段 可以防止浏览器在未明确设置 Content-Type
头部时尝试猜测内容类型。这能防止允许用户上传和共享文件的网站遭受 XSS 攻击。
例如,用户尝试下载图片时,文件可能被当作其他 Content-Type
类型(如可执行文件)处理,这可能存在恶意行为。此头部也适用于浏览器扩展的下载。该头部唯一有效的值是 nosniff
。
来源策略 (Referrer-Policy)
该头部字段 控制浏览器在从当前网站(源)导航到另一个网站时包含多少信息。
内容安全策略 (Content-Security-Policy)
详细了解如何为您的应用添加 内容安全策略 (Content Security Policy)。
版本历史
版本 | 变更内容 |
---|---|
v13.3.0 | 新增 missing 。 |
v10.2.0 | 新增 has 。 |
v9.5.0 | 新增头部字段。 |