# Headers
Examples
Headers
Version History| Version | Changes |
| :--- | :--- |
| v10.2.0| has added. |
| v9.5.0| Headers added. |
头允许您为传入请求路径设置自定义HTTP头。
To set custom HTTP headers you can use the headerskey in 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',
},
],
},
]
},
}
headersis an async function that expects an array to be returned holding objects with sourceand headersproperties:
sourceis the incoming request path pattern.headersis an array of header objects with thekeyandvalueproperties.basePath:falseorundefined- if false the basePath won't be included when matching, can be used for external rewrites only.locale:falseorundefined- whether the locale should not be included when matching.hasis an array ofhas objectswith thetype,keyandvalueproperties.
Headers are checked before the filesystem which includes pages and /publicfiles.
# Header Overriding Behavior
If two headers match the same path and set the same header key, the last header key will override the first. Using the below headers, the path /hellowill result in the header x-hellobeing worlddue to the last header value set being world.
module.exports = {
async headers() {
return [
{
source: '/:path*',
headers: [
{
key: 'x-hello',
value: 'there',
},
],
},
{
source: '/hello',
headers: [
{
key: 'x-hello',
value: 'world',
},
],
},
]
},
}
# Path Matching
Path matches are allowed, for example /blog/:slugwill match /blog/hello-world(no nested paths):
module.exports = {
async headers() {
return [
{
source: '/blog/:slug',
headers: [
{
key: 'x-slug',
value: ':slug', // Matched parameters can be used in the value
},
{
key: 'x-slug-:slug', // Matched parameters can be used in the key
value: 'my other custom header value',
},
],
},
]
},
}
# Wildcard Path Matching
To match a wildcard path you can use *after a parameter, for example /blog/:slug*will match /blog/a/b/c/d/hello-world:
module.exports = {
async headers() {
return [
{
source: '/blog/:slug*',
headers: [
{
key: 'x-slug',
value: ':slug*', // Matched parameters can be used in the value
},
{
key: 'x-slug-:slug*', // Matched parameters can be used in the key
value: 'my other custom header value',
},
],
},
]
},
}
# Regex Path Matching
To match a regex path you can wrap the regex in parenthesis after a parameter, for example /blog/:slug(\\d{1,})will match /blog/123but not /blog/abc:
module.exports = {
async headers() {
return [
{
source: '/blog/:post(\\d{1,})',
headers: [
{
key: 'x-post',
value: ':post',
},
],
},
]
},
}
The following characters (, ), {, }, :, *, +, ?are used for regex path matching, so when used in the sourceas non-special values they must be escaped by adding \\before them:
module.exports = {
async headers() {
return [
{
// this will match `/english(default)/something` being requested
source: '/english\\(default\\)/:slug',
headers: [
{
key: 'x-header',
value: 'value',
},
],
},
]
},
}
# Header, Cookie, and Query Matching
To only apply a header when either header, cookie, or query values also match the hasfield can be used. Both the sourceand all hasitems must match for the header to be applied.
hasitems have the following fields:
type:String- must be eitherheader,cookie,host, orquery.key:String- the key from the selected type to match against.value:Stringorundefined- the value to check for, if undefined any value will match. A regex like string can be used to capture a specific part of the value, e.g. if the valuefirst-(?<paramName>.*)is used forfirst-secondthensecondwill be usable in the destination with:paramName.
module.exports = {
async headers() {
return [
// if the header `x-add-header` is present,
// the `x-another-header` header will be applied
{
source: '/:path*',
has: [
{
type: 'header',
key: 'x-add-header',
},
],
headers: [
{
key: 'x-another-header',
value: 'hello',
},
],
},
// if the source, query, and cookie are matched,
// the `x-authorized` header will be applied
{
source: '/specific/:path*',
has: [
{
type: 'query',
key: 'page',
// the page value will not be available in the
// header key/values since value is provided and
// doesn't use a named capture group e.g. (?<page>home)
value: 'home',
},
{
type: 'cookie',
key: 'authorized',
value: 'true',
},
],
headers: [
{
key: 'x-authorized',
value: ':authorized',
},
],
},
// if the header `x-authorized` is present and
// contains a matching value, the `x-another-header` will be applied
{
source: '/:path*',
has: [
{
type: 'header',
key: 'x-authorized',
value: '(?<authorized>yes|true)',
},
],
headers: [
{
key: 'x-another-header',
value: ':authorized',
},
],
},
// if the host is `example.com`,
// this header will be applied
{
source: '/:path*',
has: [
{
type: 'host',
value: 'example.com',
},
],
headers: [
{
key: 'x-another-header',
value: ':authorized',
},
],
},
]
},
}
# Headers with basePath support
When leveraging basePath support with headers each sourceis automatically prefixed with the basePathunless you add basePath: falseto the header:
module.exports = {
basePath: '/docs',
async headers() {
return [
{
source: '/with-basePath', // becomes /docs/with-basePath
headers: [
{
key: 'x-hello',
value: 'world',
},
],
},
{
source: '/without-basePath', // is not modified since basePath: false is set
headers: [
{
key: 'x-hello',
value: 'world',
},
],
basePath: false,
},
]
},
}
# Headers with i18n support
When leveraging i18n support with headers each sourceis automatically prefixed to handle the configured localesunless you add locale: falseto the header. If locale: falseis used you must prefix the sourcewith a locale for it to be matched correctly.
module.exports = {
i18n: {
locales: ['en', 'fr', 'de'],
defaultLocale: 'en',
},
async headers() {
return [
{
source: '/with-locale', // automatically handles all locales
headers: [
{
key: 'x-hello',
value: 'world',
},
],
},
{
// does not handle locales automatically since locale: false is set
source: '/nl/with-locale-manual',
locale: false,
headers: [
{
key: 'x-hello',
value: 'world',
},
],
},
{
// this matches '/' since `en` is the defaultLocale
source: '/en',
locale: false,
headers: [
{
key: 'x-hello',
value: 'world',
},
],
},
{
// this gets converted to /(en|fr|de)/(.*) so will not match the top-level
// `/` or `/fr` routes like /:path* would
source: '/(.*)',
headers: [
{
key: 'x-hello',
value: 'world',
},
],
},
]
},
}
# Cache-Control
Cache-Control headers set in next.config.js will be overwritten in production to ensure that static assets can be cached effectively. If you need to revalidate the cache of a page that has been statically generated , you can do so by setting revalidatein the page's getStaticProps function.
# Related
For more information, we recommend the following sections:
Security HeadersImprove the security of your Next.js application by add HTTP response headers.