自訂文件

自訂 Document 可用來更新渲染頁面時使用的 <html> 和 <body> 標籤。

要覆寫預設的 Document，請按照以下方式建立 pages/_document 檔案：

import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

須知事項

_document 僅在伺服器端渲染，因此無法在此檔案中使用像是 onClick 這樣的事件處理器。

頁面要正確渲染必須包含 <Html>、<Head />、<Main /> 和 <NextScript />。

注意事項

_document 中使用的 <Head /> 元件與 next/head 不同。此處的 <Head /> 元件應僅用於所有頁面共用的 <head> 程式碼。對於其他情況（例如 <title> 標籤），建議在頁面或元件中使用 next/head。
<Main /> 之外的 React 元件不會被瀏覽器初始化。請勿在此處添加應用程式邏輯或自訂 CSS（如 styled-jsx）。如果需要在所有頁面中共享元件（例如選單或工具列），請參閱版面配置。
Document 目前不支援 Next.js 的資料獲取方法，例如 getStaticProps 或 getServerSideProps。

自訂 `renderPage`

自訂 renderPage 屬於進階用法，僅在需要支援伺服器端渲染的函式庫（如 CSS-in-JS）時使用。內建的 styled-jsx 支援不需要此設定。

我們不建議使用此模式。 相反地，請考慮逐步採用 App Router，它能更輕鬆地為頁面和版面配置獲取資料。

import Document, {
  Html,
  Head,
  Main,
  NextScript,
  DocumentContext,
  DocumentInitialProps,
} from 'next/document'

class MyDocument extends Document {
  static async getInitialProps(
    ctx: DocumentContext
  ): Promise<DocumentInitialProps> {
    const originalRenderPage = ctx.renderPage

    // 同步執行 React 渲染邏輯
    ctx.renderPage = () =>
      originalRenderPage({
        // 用於包裝整個 React 樹
        enhanceApp: (App) => App,
        // 用於按頁面包裝
        enhanceComponent: (Component) => Component,
      })

    // 執行父層的 `getInitialProps`，現在包含自訂的 `renderPage`
    const initialProps = await Document.getInitialProps(ctx)

    return initialProps
  }

  render() {
    return (
      <Html lang="en">
        <Head />
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    )
  }
}

export default MyDocument

須知事項

_document 中的 getInitialProps 不會在客戶端轉換時呼叫。

_document 的 ctx 物件等同於 getInitialProps 接收的物件，並增加了 renderPage 屬性。

注意事項

自訂 renderPage

On this page

自訂 `renderPage`