Next.js 11执行next build && next export时页面预渲染找不到模块报错如何解决

问题产生的常见原因 #

• pages目录结构或命名不符合规范：pages目录没有放在项目根目录、文件名/路径大小写和引用不匹配（Windows开发环境大小写不敏感，构建到Linux环境就会触发校验失败）、动态路由文件名不符合要求，都会导致Next.js识别不到页面模块。
• 自定义Webpack配置冲突：开启Webpack 5后，如果next.config.js里的自定义webpack配置直接覆盖了Next.js默认的页面文件解析规则，会导致构建时找不到对应页面的模块。
• 预渲染阶段存在未处理的运行时错误：页面组件在预渲染阶段调用了window等浏览器端API、接口请求失败没有捕获异常，也会抛出找不到模块的错误。
• 导出配置错误：如果使用静态导出功能，next.config.js里的exportPathMap配置和实际pages下的文件不匹配，或者动态路由没有配置对应的静态生成路径，也会触发该报错。
• pageExtensions配置异常：如果自定义了pageExtensions配置，页面文件后缀不在配置的范围内，会导致Next.js识别不到页面。

对应解决办法 #

• 校验pages目录和文件名：确认pages目录放在项目根目录下，所有页面文件名的大小写和路由引用完全一致，动态路由文件比如[id].js的命名符合规范，没有特殊字符或多余后缀。
• 排查自定义Webpack配置：先临时注释掉next.config.js里的webpack自定义配置，重新构建测试是否恢复正常。如果确认是Webpack配置导致的，要使用追加模式修改配置，不要直接覆盖默认配置，示例如下：

// next.config.js 正确的webpack配置写法
module.exports = {
  webpack: (config) => {
    // 追加配置而不是覆盖原config.resolve.extensions
    config.resolve.extensions.push('.ts', '.tsx')
    return config
  }
}

• 处理预渲染阶段的运行时错误：所有用到浏览器端API的代码都要包裹在typeof window !== 'undefined'的条件判断中，getStaticProps、getServerSideProps内的所有请求都要加try catch捕获异常，返回对应fallback状态。
• 修正静态导出配置：如果使用next export导出静态站点，确认exportPathMap配置和实际页面路径一一对应，动态路由页面需要通过getStaticPaths返回所有需要生成的静态路径。
• 校验pageExtensions配置：如果自定义了pageExtensions，确保所有页面文件的后缀都在配置的扩展名范围内。
• 清除缓存重新构建：执行以下命令清除缓存和依赖，重新安装后构建测试：

rm -rf .next node_modules package-lock.json yarn.lock
npm install
npm run build

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