NextJS 11/Webpack 5 ESM模式下文件夹聚合导出失效如何解决

问题根因 #

这是Node 14+ 原生ESM规范与Webpack 5严格校验共同导致的问题：

• ESM规范中export * from './module'仅会转发目标模块的命名导出，不会自动转发default默认导出
• 低版本Node、旧版Webpack/NextJS对该场景做了兼容兜底，升级后兼容逻辑被移除，就会出现导出为undefined的报错
• TypeScript编译阶段不会校验实际运行时的导出链路完整性，所以开发阶段无报错

可行解决方案 #

方案1：统一使用命名导出（最推荐，符合ESM规范） #

直接修改组件文件的导出方式，放弃default导出，改为命名导出：

// ./elements/markdownRenderer.ts 调整导出写法
export const MarkdownRenderer = () => {
  // 原有组件逻辑
}

之后两层聚合导出都不需要修改，可正常使用：

// ./elements/index.ts
export * from './markdownRenderer'

// ./lib/index.ts
export * from './elements'

业务侧导入逻辑保持不变即可。

方案2：保留default导出，补充默认导出的转发规则 #

如果不想修改原有组件的default导出写法，只需要在子文件夹的聚合导出文件中单独补充default导出的转发：

// ./elements/index.ts
// 转发所有命名导出
export * from './markdownRenderer'
// 单独将默认导出转为命名导出转发
export { default as MarkdownRenderer } from './markdownRenderer'

上层lib的聚合导出依旧可以使用export * from './elements'，无需其他修改。

方案3：修改NextJS配置兼容旧写法 #

如果不想调整任何导出代码，可以通过修改NextJS配置放宽ESM校验规则实现兼容：

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    esmExternals: 'loose' // 开启ESM宽松兼容模式
  },
  webpack: (config) => {
    config.resolve.fullySpecified = false
    return config
  }
}

module.exports = nextConfig

如果项目根目录的package.json没有"type": "module"字段，也可以补充该字段，让Node统一按ESM规范处理项目内的所有.js/.ts文件，避免混合模块规范导致的异常。

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