Next.js构建报错next/document不应在pages/_document外导入如何解决

报错根因 #

该报错是Next.js内置校验规则触发的，检测到项目中除pages/_document.js外的其他文件存在next/document的导入逻辑，即使你已经正确放置了pages/_document.js文件，也多为其他文件误导入、缓存异常、路由模式不匹配导致。

排查解决步骤 #

• 全局检索所有项目文件的next/document导入语句，确认仅在pages/_document.js中存在该导入：
  高频误操作是把next/document下导出的Head组件和next/head的Head组件搞混，普通页面要使用next/head的Head，不能导入next/document的Head
• 确认没有误导入后可先删除项目根目录下的.next缓存文件夹，再重新执行构建命令，避免旧缓存导致的误校验
• 若使用的是Next.js 13及以上版本的App Router模式，next/document仅适配Pages Router的pages/_document.js，App Router下自定义全局结构需使用app/layout.js，不能在app目录下的文件中导入next/document
• 若确认所有导入逻辑都符合规范，可在ESLint配置文件中关闭该校验规则，配置示例：

{
  "extends": "next/core-web-vitals",
  "rules": {
    "@next/next/no-document-import-in-page": "off"
  }
}

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