主题
自定义文件
¥Custom Document
自定义 Document 可以更新用于渲染 页面 的 <html> 和 <body> 标签。
¥A custom Document can update the <html> and <body> tags used to render a Page.
要覆盖默认的 Document，请创建文件 pages/_document，如下所示：
¥To override the default Document, create the file pages/_document as shown below:
tsx
import { Html, Head, Main, NextScript } from 'next/document'
export default function Document() {
return (
<Html lang="en">
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
)
}jsx
import { Html, Head, Main, NextScript } from 'next/document'
export default function Document() {
return (
<Html lang="en">
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
)
}需要了解：
¥Good to know:
_document仅在服务器上渲染，因此不能在该文件中使用像onClick这样的事件处理程序。¥
_documentis only rendered on the server, so event handlers likeonClickcannot be used in this file.页面正确渲染需要
<Html>、<Head />、<Main />和<NextScript />。¥
<Html>,<Head />,<Main />and<NextScript />are required for the page to be properly rendered.
注意事项
¥Caveats
_document中使用的<Head />组件与next/head不同。此处使用的<Head />组件只能用于所有页面通用的任何<head>代码。对于所有其他情况，例如<title>标签，我们建议在你的页面或组件中使用next/head。¥The
<Head />component used in_documentis not the same asnext/head. The<Head />component used here should only be used for any<head>code that is common for all pages. For all other cases, such as<title>tags, we recommend usingnext/headin your pages or components.<Main />之外的 React 组件不会被浏览器初始化。不要在此处添加应用逻辑或自定义 CSS（如styled-jsx）。如果你需要在所有页面中共享组件（例如菜单或工具栏），请阅读 布局。¥React components outside of
<Main />will not be initialized by the browser. Do not add application logic here or custom CSS (likestyled-jsx). If you need shared components in all your pages (like a menu or a toolbar), read Layouts instead.Document目前不支持 Next.js 数据获取方法，如getStaticProps或getServerSideProps。¥
Documentcurrently does not support Next.js Data Fetching methods likegetStaticPropsorgetServerSideProps.
自定义 renderPage
¥Customizing renderPage
自定义 renderPage 是高级的，只有像 CSS-in-JS 这样的库才需要支持服务器端渲染。内置 styled-jsx 支持不需要这样做。
¥Customizing renderPage is advanced and only needed for libraries like CSS-in-JS to support server-side rendering. This is not needed for built-in styled-jsx support.
我们不建议使用此模式。相反，请将 逐步采用 视为应用路由，它允许你更轻松地获取 页面和布局 的数据。
¥We do not recommend using this pattern. Instead, consider incrementally adopting the App Router, which allows you to more easily fetch data for pages and layouts.
tsx
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
// Run the React rendering logic synchronously
ctx.renderPage = () =>
originalRenderPage({
// Useful for wrapping the whole react tree
enhanceApp: (App) => App,
// Useful for wrapping in a per-page basis
enhanceComponent: (Component) => Component,
})
// Run the parent `getInitialProps`, it now includes the custom `renderPage`
const initialProps = await Document.getInitialProps(ctx)
return initialProps
}
render() {
return (
<Html lang="en">
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
)
}
}
export default MyDocumentjsx
import Document, { Html, Head, Main, NextScript } from 'next/document'
class MyDocument extends Document {
static async getInitialProps(ctx) {
const originalRenderPage = ctx.renderPage
// Run the React rendering logic synchronously
ctx.renderPage = () =>
originalRenderPage({
// Useful for wrapping the whole react tree
enhanceApp: (App) => App,
// Useful for wrapping in a per-page basis
enhanceComponent: (Component) => Component,
})
// Run the parent `getInitialProps`, it now includes the custom `renderPage`
const initialProps = await Document.getInitialProps(ctx)
return initialProps
}
render() {
return (
<Html lang="en">
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
)
}
}
export default MyDocument需要了解：
¥Good to know:
在客户端转换期间不会调用
_document中的getInitialProps。¥
getInitialPropsin_documentis not called during client-side transitions.
_document的ctx对象相当于getInitialProps中收到的对象，并添加了renderPage。¥The
ctxobject for_documentis equivalent to the one received ingetInitialProps, with the addition ofrenderPage.