Vite项目中处理CommonJS模块的顶层await问题解析

背景介绍

在Vite 6.0.1版本中，开发者遇到了一个关于CommonJS模块中使用顶层await的构建错误。这个问题在构建过程中表现为Rollup抛出的错误："await isn't allowed in non-async function"。本文将深入分析这个问题的成因，并提供几种可行的解决方案。

问题本质

当Vite项目尝试构建包含顶层await的CommonJS模块时，Rollup的CommonJS插件会将这些模块包装在立即执行函数表达式(IIFE)中。由于IIFE默认不是异步函数，因此其中的await表达式会导致语法错误。

技术细节分析

1. CommonJS与顶层await的兼容性：Node.js原生不支持在CommonJS模块中使用顶层await，这是ECMAScript模块(ESM)特有的特性。

2. Vite 6的变化：Vite 6默认将build.commonjsOptions.strictRequires设置为true，这会导致CommonJS插件使用更严格的IIFE包装方式，从而暴露了顶层await的问题。

3. 开发与生产环境的差异：

   • 开发模式下，Vite使用esbuild进行转换，但esbuild同样不支持CommonJS中的顶层await
   • 生产构建使用Rollup，其CommonJS插件的行为导致了错误

解决方案比较

方案一：调整CommonJS插件配置

通过设置build.commonjsOptions.strictRequires: 'auto'可以解决构建问题：

// vite.config.js
export default {
  build: {
    commonjsOptions: {
      strictRequires: 'auto'
    }
  }
}

优点：简单直接，无需修改模块代码 缺点：可能导致非确定性构建，存在潜在风险

方案二：使用syntheticNamedExports

在Rollup配置中使用syntheticNamedExports选项：

// vite.config.js
export default {
  build: {
    rollupOptions: {
      output: {
        syntheticNamedExports: true
      }
    }
  }
}

优点：避免CommonJS转换问题 缺点：不适用于开发模式，导致环境不一致

方案三：模块导出方式改造

回归到ESM导出方式配合optimizeDeps.needsInterop：

// 模块代码改为ESM导出
export default await runtimeModule

// vite.config.js
export default {
  optimizeDeps: {
    needsInterop: true
  }
}

优点：符合现代模块标准 缺点：需要处理开发和生产环境的差异

最佳实践建议

1. 优先考虑ESM模块：尽可能将共享模块转换为ESM格式，从根本上避免CommonJS的限制。

2. 环境一致性：确保开发和生产环境使用相同的模块处理逻辑，减少潜在问题。

3. 渐进式迁移：对于大型项目，可以逐步将CommonJS模块迁移到ESM。

4. 谨慎使用配置覆盖：如果必须使用strictRequires: 'auto'，应该充分测试构建稳定性。

总结

Vite项目中处理CommonJS模块的顶层await问题需要权衡多种因素。理解底层机制后，开发者可以根据项目实际情况选择最适合的解决方案。随着前端生态向ESM的全面迁移，这类问题将逐渐减少，但在过渡期仍需掌握这些应对技巧。