Version | Changes |
---|---|
v10.2.0 | has が追加される。 |
v9.5.0 | ヘッダーが追加される。 |
ヘッダーでは、受け取るリクエストパスに対して独自の HTTP ヘッダーを設定できます。
独自の HTTP ヘッダーを設定するためには、 next.config.js
の headers
キーを使用します:
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
or undefined
- if false the basePath won't be included when matching, can be used for external rewrites only.locale
: false
or undefined
- whether the locale should not be included when matching.has
is an array of has objects with the type
, key
and value
properties.Headers are checked before the filesystem which includes pages and /public
files.
2 つのヘッダーが同じパスにマッチし、同じヘッダーキーが設定されていた場合、最後のヘッダーキーが最初のヘッダーキーを上書きします。以下のヘッダーを使うと、パス /hello
は最後のヘッダーの値が world
であるため、ヘッダー x-hello
の値は world
となります。
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
とマッチします (ネストされているパスはありません):
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
とマッチします:
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
とはマッチしません:
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 source
as 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',
},
],
},
]
},
}
To only apply a header when either header, cookie, or query values also match the has
field can be used. Both the source
and all has
items must match for the header to be applied.
has
items have the following fields:
type
: String
- must be either header
, cookie
, host
, or query
.key
: String
- the key from the selected type to match against.value
: String
or undefined
- 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 value first-(?<paramName>.*)
is used for first-second
then second
will 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',
},
],
},
]
},
}
ヘッダーで basePath
サポートを利用する際は、ヘッダーに basePath: false
を追加しない限り、各 source
に対して自動的に basePath
がプレフィックスとして付与されます:
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,
},
]
},
}
When leveraging i18n
support with headers each source
is automatically prefixed to handle the configured locales
unless you add locale: false
to the header. If locale: false
is used you must prefix the source
with 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 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 revalidate
in the page's getStaticProps
function.
For more information, we recommend the following sections: