ES Module Shims 中 CSS 模块的浏览器兼容性问题解析

背景介绍

ES Module Shims 是一个用于在现代浏览器中提供模块加载功能的 polyfill 库，它允许开发者使用最新的 ES 模块特性，同时在旧版浏览器中保持兼容性。其中，CSS 模块和 JSON 模块的支持是该库的重要功能之一。

问题现象

在 Chrome 123 版本中，开发者发现即使浏览器原生支持 CSS 模块，ES Module Shims 仍然会触发 polyfill 逻辑，导致控制台输出"Module error above is polyfilled and can be ignored"的提示信息。这种现象在本地开发环境不会出现，但在生产环境部署后就会显现。

技术分析

1. 语法差异

现代浏览器对 CSS 模块的支持经历了语法变更：

• 早期使用 assert 语法：import sheet from 'style.css' assert { type: 'css' }
• 现在使用 with 语法：import sheet from 'style.css' with { type: 'css' }

ES Module Shims 目前只检测 with 语法的支持情况，而不会回退检测 assert 语法。这意味着即使浏览器支持 assert 语法但不支持 with 语法，也会触发 polyfill。

2. 构建工具影响

使用构建工具（如 esbuild）时，如果配置不当可能会导致以下问题：

• 构建时错误地移除了 with 语法声明
• 导致浏览器无法识别模块类型
• 触发 MIME 类型检查错误："Expected a JavaScript module script but the server responded with a MIME type of 'text/css'"

3. CSP 策略限制

内容安全策略（CSP）的设置也会影响 CSS 模块的正常工作：

• 需要确保 style-src 策略中包含 blob: 来源
• 缺少必要的 CSP 配置会导致模块加载失败

解决方案

1. 正确配置 ES Module Shims

确保正确启用 CSS 模块的 polyfill 功能：

<script type="esms-options">
{
  "polyfillEnable": ["css-modules", "json-modules", "wasm-modules"]
}
</script>

2. 构建工具配置

在使用 esbuild 等构建工具时：

• 确保保留 with 语法声明
• 对于 esbuild，需要正确设置 --supported:import-assertions 参数

3. 完善 CSP 策略

在内容安全策略中添加必要的配置：

Content-Security-Policy: style-src 'self' blob:;

最佳实践建议

1. 统一使用最新的 with 语法导入 CSS 模块
2. 在生产环境部署前，验证 polyfill 是否只在必要情况下触发
3. 检查构建输出，确保模块导入语句没有被错误修改
4. 全面测试本地环境和生产环境的差异，包括 CSP 策略的影响

总结

ES Module Shims 在处理 CSS 模块时，需要开发者注意浏览器语法支持的变化、构建工具的配置以及安全策略的设置。通过正确配置和全面测试，可以确保模块系统在各种环境下都能正常工作，同时避免不必要的 polyfill 带来的性能开销。