Next.js运行npm run dev报Element type is invalid错误生产环境正常

问题描述 #

运行npm run dev启动Next.js开发服务器时持续出现以下报错：

Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports.
This error happened while generating the page. Any console logs will be displayed in the terminal window.

执行npm run build构建后再运行npm run start启动生产环境服务时，站点可以正常加载，仅开发服务器会触发该错误，项目部署到Vercel平台也完全正常无报错。
已尝试删除.next缓存文件夹、删除node_modules后重新安装所有依赖，问题依旧存在。完整报错信息如下：

Server Error

Error: Element type is invalid: expected a string (for built-in components) or a class/function (for composite components) but got: undefined. You likely forgot to export your component from the file it's defined in, or you might have mixed up default and named imports.
This error happened while generating the page. Any console logs will be displayed in the terminal window.
Call Stack
ReactDOMServerRenderer.render
[project]/node_modules/react-dom/cjs/react-dom-server.node.development.js (4053:17)
ReactDOMServerRenderer.read
[project]/node_modules/react-dom/cjs/react-dom-server.node.development.js (3690:29)
Object.renderToString
[project]/node_modules/react-dom/cjs/react-dom-server.node.development.js (4298:27)
Object.renderPage
[project]/node_modules/next/dist/server/render.js (596:45)
Function.getInitialProps
node_modules/next/dist/pages/_document.js (150:43)
Object.loadGetInitialProps
[project]/node_modules/next/dist/shared/lib/utils.js (69:29)
renderDocument
[project]/node_modules/next/dist/server/render.js (609:48)
Object.renderToHTML
[project]/node_modules/next/dist/server/render.js (647:34)
runMicrotasks
<anonymous>
processTicksAndRejections
internal/process/task_queues.js (97:5)

原因及解决方案 #

• 开发环境专属逻辑的导入错误
  优先排查代码中所有带process.env.NODE_ENV === 'development'的条件分支，这类分支仅在开发环境执行，如果分支内引入的组件存在漏导出、混用默认导出和命名导出的问题，就会仅在开发环境触发报错，生产环境不会执行该分支代码所以无异常。从报错栈可以看到错误触发在_document.js的getInitialProps生命周期，优先检查该文件内的开发环境专属逻辑。
• 循环导入的环境兼容性差异
  Next.js开发环境和生产环境的打包逻辑对循环导入的容错度不同，开发环境下Webpack的模块热重载机制对循环导入的处理更严格，会出现导出的组件为undefined的情况，而生产环境打包时会对循环依赖做自动兼容处理，因此不会报错。可以通过ESLint的import/no-cycle规则检测项目中的循环依赖，调整模块引用逻辑即可修复。
• 动态导入的SSR逻辑差异
  如果使用了next/dynamic做组件懒加载，开发环境下服务端渲染阶段会提前执行模块加载逻辑，如果组件内部依赖仅客户端可用的API（如window、document）没有做兼容，也可能出现开发环境加载组件失败返回undefined的情况，生产环境预渲染时会跳过异常逻辑所以可以正常运行。可以给动态导入配置ssr: false，或者给组件加客户端渲染兜底判断验证。

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