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 是一個 has 物件陣列，具有 type、key 和 value 屬性。
missing 是一個 missing 物件陣列，具有 type、key 和 value 屬性。

標頭會在檔案系統（包含頁面和 /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', // 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',
          },
        ],
      },
    ]
  },
}

萬用字元路徑匹配

若要匹配萬用字元路徑，您可以在參數後使用 *，例如 /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*', // 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',
          },
        ],
      },
    ]
  },
}

正則表達式路徑匹配

若要匹配正則表達式路徑，您可以將正則表達式包在參數後的括號中，例如 /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 [
      {
        // this will match `/english(default)/something` being requested
        source: '/english\\(default\\)/:slug',
        headers: [
          {
            key: 'x-header',
            value: 'value',
          },
        ],
      },
    ]
  },
}

若要僅在標頭、Cookie 或查詢值也匹配 has 字段，或不匹配 missing 字段時才應用標頭，可以使用 has 字段或 missing 字段。source 和所有 has 項目都必須匹配，並且所有 missing 項目都必須不匹配，標頭才會被應用。

has 和 missing 項目可以具有以下字段

type：String - 必須是 header、cookie、host 或 query 之一。
key：String - 要匹配的選定類型中的鍵。
value：String 或 undefined - 要檢查的值，如果為 undefined，則任何值都將匹配。可以使用類似正則表達式的字串來捕獲值的特定部分，例如，如果 first-(?<paramName>.*) 值用於 first-second，則 second 將可與 :paramName 一起在目的地中使用。

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

支援 basePath 的標頭

當利用 basePath 支援標頭時，除非您在標頭中添加 basePath: false，否則每個 source 都會自動加上 basePath 前綴。

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

支援 i18n 的標頭

當利用 i18n 支援標頭時，除非您在標頭中添加 locale: false，否則每個 source 都會自動加上前綴以處理已設定的 locales。如果使用 locale: false，您必須在 source 前面加上語系，才能正確匹配。

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

Next.js 為真正不可變的資源設定 Cache-Control 標頭為 public, max-age=31536000, immutable。它無法被覆寫。這些不可變的檔案在檔案名稱中包含 SHA 雜湊值，因此可以安全地無限期快取。例如，靜態圖片匯入。您無法在 next.config.js 中為這些資源設定 Cache-Control 標頭。

但是，您可以為其他響應或資料設定 Cache-Control 標頭。

深入了解使用 App Router 的快取。

選項

CORS

跨來源資源共享 (CORS) 是一項安全功能，可讓您控制哪些網站可以訪問您的資源。您可以設定 Access-Control-Allow-Origin 標頭，以允許特定來源訪問您的資源路由處理器.

async headers() {
    return [
      {
        source: "/api/:path*",
        headers: [
          {
            key: "Access-Control-Allow-Origin",
            value: "*", // Set your origin
          },
          {
            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。使用以下設定，所有目前和未來的子網域將使用 HTTPS，max-age 為 2 年。這會阻止訪問只能透過 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'
}

Content-Security-Policy

深入了解將內容安全策略添加到您的應用程式。

版本歷史

版本	變更
`v13.3.0`	新增 `missing`。
`v10.2.0`	新增 `has`。
`v9.5.0`	新增標頭。