headers

Üstbilgiler, belirli bir yolda gelen bir isteğe yanıt olarak özel HTTP üstbilgileri ayarlamanıza olanak tanır.

Özel HTTP başlıkları ayarlamak için next.config.js adresindeki headers anahtarını kullanabilirsiniz:

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 ve headers özelliklerine sahip nesneleri içeren bir dizinin döndürülmesini bekleyen bir asenkron işlevdir:

Sayfaları ve /public dosyalarını içeren dosya sisteminden önce başlıklar kontrol edilir.

Header Overriding Behavior

İki başlık aynı yolla eşleşir ve aynı başlık anahtarını ayarlarsa, son başlık anahtarı ilkini geçersiz kılar. Aşağıdaki başlıkları kullanarak, /hello yolu x-hello başlığının world olmasıyla sonuçlanacaktır, çünkü son başlık değeri world olarak ayarlanmıştır.

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

Path Matching

Yol eşleşmelerine izin verilir, örneğin /blog/:slug, /blog/hello-world ile eşleşir (iç içe geçmiş yollar yoktur):

next.config.js
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

Bir joker karakter yolunu eşleştirmek için bir parametreden sonra * kullanabilirsiniz; örneğin /blog/:slug*, /blog/a/b/c/d/hello-world ile eşleşecektir:

next.config.js
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

Bir regex yolunu eşleştirmek için regex'i bir parametreden sonra parantez içine alabilirsiniz; örneğin /blog/:slug(\\d{1,}), /blog/123 ile eşleşir ancak /blog/abc ile eşleşmez:

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

Aşağıdaki karakterler (, ), {, }, :, *, +, ? regex yol eşleştirmesi için kullanılır, bu nedenle source içinde özel olmayan değerler olarak kullanıldıklarında önlerine \\ eklenerek kaçılmalıdır:

next.config.js
module.exports = {
  async headers() {
    return [
      {
        // this will match `/english(default)/something` being requested
        source: '/english\\(default\\)/:slug',
        headers: [
          {
            key: 'x-header',
            value: 'value',
          },
        ],
      },
    ]
  },
}

Yalnızca başlık, çerez veya sorgu değerleri de has alanıyla eşleştiğinde veya missing alanıyla eşleşmediğinde bir başlık uygulamak için kullanılabilir. Başlığın uygulanabilmesi için hem source hem de tüm has öğelerinin eşleşmesi ve tüm missing öğelerinin eşleşmemesi gerekir.

has ve missing öğeleri aşağıdaki alanlara sahip olabilir:

next.config.js
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 header `x-no-header` is not present,
      // the `x-another-header` header will be applied
      {
        source: '/:path*',
        missing: [
          {
            type: 'header',
            key: 'x-no-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

Başlıklarla basePath desteğinden yararlanırken, başlığa basePath: false eklemediğiniz sürece her source 'un önüne otomatik olarak basePath eklenir:

next.config.js
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

Başlıklarla i18n desteğinden yararlanırken, başlığa locale: false eklemediğiniz sürece her source yapılandırılmış locales 'yi işlemek için otomatik olarak öneklenir. Eğer locale: false kullanılıyorsa, doğru bir şekilde eşleşmesi için source 'un önüne bir yerel ayar eklemelisiniz.

next.config.js
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

Yanıtların ve statik varlıkların etkili bir şekilde önbelleğe alınmasını sağlamak için üretimde bu başlıkların üzerine yazılacağından, sayfalar veya varlıklar için next.config.js adresinde Cache-Control başlıklarını ayarlayamazsınız.

App Router ile önbelleğe alma hakkında daha fazla bilgi edinin.

Options

X-DNS-Prefetch-Control

Bu başlık, tarayıcıların harici bağlantılar, resimler, CSS, JavaScript ve daha fazlası üzerinde proaktif olarak alan adı çözümlemesi gerçekleştirmesine olanak tanıyan DNS ön getirmeyi kontrol eder. Bu ön getirme arka planda gerçekleştirilir, böylece DNS 'un başvurulan öğelere ihtiyaç duyulduğunda çözülmüş olma olasılığı daha yüksektir. Bu, kullanıcı bir bağlantıya tıkladığında gecikmeyi azaltır.

{
  key: 'X-DNS-Prefetch-Control',
  value: 'on'
}

Strict-Transport-Security

Bu başlık tarayıcılara HTTP yerine yalnızca HTTPS kullanılarak erişilmesi gerektiğini bildirir. Aşağıdaki yapılandırmayı kullanarak, mevcut ve gelecekteki tüm alt alan adları 2 yıl boyunca max-age HTTPS kullanacaktır. Bu, yalnızca HTTP üzerinden sunulabilen sayfalara veya alt alan adlarına erişimi engeller.

Vercel adresine dağıtım yapıyorsanız, next.config.js adresinizde headers adresini bildirmediğiniz sürece tüm dağıtımlara otomatik olarak eklendiğinden bu başlık gerekli değildir.

{
  key: 'Strict-Transport-Security',
  value: 'max-age=63072000; includeSubDomains; preload'
}

X-Frame-Options

Bu başlık sitenin bir iframe içinde görüntülenmesine izin verilip verilmeyeceğini gösterir. Bu, clickjacking saldırılarına karşı önlem alabilir.

Bu başlık, CSP'nin modern tarayıcılarda daha iyi desteğe sahip olan frame-ancestors seçeneği ile değiştirilmiştir.

{
  key: 'X-Frame-Options',
  value: 'SAMEORIGIN'
}

Permissions-Policy

Bu başlık tarayıcıda hangi özelliklerin ve API'lerin kullanılabileceğini kontrol etmenizi sağlar. Daha önce Feature-Policy olarak adlandırılmıştı.

{
  key: 'Permissions-Policy',
  value: 'camera=(), microphone=(), geolocation=(), browsing-topics=()'
}

X-Content-Type-Options

Bu başlığı, Content-Type başlığı açıkça ayarlanmamışsa tarayıcının içerik türünü tahmin etmeye çalışmasını engeller. Bu, kullanıcıların dosya yüklemesine ve paylaşmasına izin veren web siteleri için XSS istismarlarını önleyebilir.

Örneğin, bir kullanıcı bir resim indirmeye çalışırken, bu resmin kötü amaçlı olabilecek bir çalıştırılabilir dosya gibi farklı bir Content-Type olarak ele alınması. Bu başlık tarayıcı uzantılarının indirilmesi için de geçerlidir. Bu başlık için tek geçerli değer nosniff'dur.

{
  key: 'X-Content-Type-Options',
  value: 'nosniff'
}

Referrer-Policy

Bu başlık tarayıcının mevcut web sitesinden (kaynak) diğerine geçerken ne kadar bilgi içereceğini kontrol eder.

{
  key: 'Referrer-Policy',
  value: 'origin-when-cross-origin'
}

Content-Security-Policy

Uygulamanıza İçerik Güvenliği İlkesi ekleme hakkında daha fazla bilgi edinin.

Version History

VersionChanges
v13.3.0missing added.
v10.2.0has added.
v9.5.0Headers added.