如何正确覆写Next.js中_document.tsx的Head类调整渲染顺序

不需要修改Next.js源码或者打补丁，直接在项目自定义_document.tsx中继承内置Head基类重写渲染逻辑即可，这是侵入性最低、维护成本最小的实现方式。

具体实现步骤 #

• 找到项目下的pages/_document.tsx文件，不存在就新建该文件。引入Next.js导出的Head基类，注意不要直接使用Next.js默认封装好的成品Head组件。
• 编写自定义Head子类，继承React组件能力，复用内置Head的上下文获取逻辑，重写render方法时将{children}和{head}的渲染位置互换，同时保留所有Next.js内置的依赖逻辑，避免hydration异常。
• 在自定义Document组件中，用你写的CustomHead替换原本默认的Head组件即可。

参考实现代码 #

import Document, {
  Html,
  Main,
  NextScript,
  Head as BaseHead,
  HeadProps
} from 'next/document'
import React, { Component } from 'react'

class CustomHead extends Component<HeadProps> {
  // 复用内置Head的上下文类型，保证能拿到Next.js内部收集的head数据、配置项
  static contextType = BaseHead.contextType
  context!: React.ContextType<typeof BaseHead.contextType>

  render() {
    const { head, optimizeFonts } = this.context
    return (
      <head {...BaseHead.getHeadHTMLProps(this.props)}>
        {/* 先渲染用户自定义传入的children，再渲染Next.js自动收集的head内容，实现顺序互换 */}
        {this.props.children}

        {/* 核心标记不能删，否则客户端hydration时会出现头部标签重复、计数不匹配报错 */}
        <meta
          name="next-head-count"
          content={React.Children.count(head || []).toString()}
        />

        {head}

        {/* 保留内置字体优化逻辑 */}
        {optimizeFonts && <meta name="next-font-preconnect" />}
      </head>
    )
  }
}

export default function MyDocument() {
  return (
    <Html lang="zh-CN">
      <CustomHead>
        {/* 此处写原本要放在Head里的自定义标签，比如全局meta、title、全局script等 */}
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
      </CustomHead>
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

注意事项 #

• 重写逻辑时必须保留next-head-count元标签、字体预连接逻辑、head属性透传方法，否则会出现hydration失败、头部标签重复注入、字体优化失效等问题。
• 升级Next.js大版本后，需要对照对应版本内置_document.tsx中Head的实现逻辑，核对上下文返回值、依赖的内部方法是否有变更，同步调整自定义Head的代码即可，该部分调整工作量极小。
• 不推荐使用patch-package修改node_modules源码、fork Next.js仓库等方案，这类方案维护成本更高，也容易在版本升级时出现不可预期的问题。
• 该方案仅适用于Pages Router架构的Next.js项目，App Router架构没有_document.tsx入口，不适用该调整逻辑。

内容的提问来源于stack exchange，提问作者lolafkok