Sponsor
ntab.devntab.dev 提升效率的新标签页组件
点击查看
Menu

自定义文档

自定义 Document 可以更新用于渲染页面<html><body> 标签。

要覆盖默认的 Document,请按如下所示创建 pages/_document 文件:

pages/_document.tsx
TypeScript
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 数据获取方法,如 getStaticPropsgetServerSideProps

自定义 renderPage

自定义 renderPage 是高级用法,仅在需要像 CSS-in-JS 这样的库支持服务器端渲染时使用。对于内置的 styled-jsx 支持,这是不需要的。

**我们不建议使用这种模式。**相反,考虑渐进式采用 App Router,它可以更轻松地为页面和布局获取数据。

pages/_document.tsx
TypeScript
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 在客户端转换期间不会被调用。
  • _documentctx 对象等同于在 getInitialProps 中接收的对象,另外还有 renderPage