Next.js 中使用 Pigment CSS 与 ESM 模块的兼容性问题分析

背景介绍

在 Next.js 应用开发中，当同时使用 Pigment CSS 和 ESM 模块时，开发者可能会遇到模块兼容性问题。本文将深入分析这一问题的成因，并提供有效的解决方案。

问题现象

在 Next.js 应用中使用 Pigment CSS 进行样式处理时，如果项目中同时引入了仅支持 ESM 格式的模块（如 nuqs），构建过程中会出现错误提示："This package is ESM only"。这是因为 Pigment CSS 在静态分析阶段会扫描所有被引用的文件，包括 ESM 模块。

技术原理

Pigment CSS 作为 CSS-in-JS 解决方案，在构建时会对项目中的所有文件进行静态分析以提取样式信息。当它遇到 ESM 模块时，由于传统的构建工具链对 ESM 支持不足，会导致解析失败。

现代 JavaScript 生态正在向 ESM 标准迁移，但部分工具链仍存在兼容性问题。Node.js 20+ 版本已经开始原生支持 require() 加载 ESM 模块，这将从根本上解决此类问题。

解决方案

针对当前情况，可以通过配置 Pigment CSS 的异步解析器来规避这个问题：

// next.config.js
{
  asyncResolve: (what) => {
    if (what.includes("nuqs")) {
      return import.meta.resolve(what).replace("file://", "");
    }
    return null;
  }
}

这个配置的作用是：

1. 检测到 nuqs 模块引用时
2. 使用 import.meta.resolve 获取模块的完整路径
3. 移除文件协议前缀后返回

最佳实践建议

1. 确保使用 Node.js 20 或更高版本，以获得更好的 ESM 支持
2. 定期检查 Pigment CSS 的更新，未来版本可能会原生支持 ESM
3. 对于新项目，优先选择纯 ESM 的依赖项
4. 在混合使用 CJS 和 ESM 模块时，注意构建工具的兼容性配置

总结

随着 JavaScript 生态向 ESM 标准迁移，这类兼容性问题将逐渐减少。目前通过合理的配置可以解决大部分构建时的问题。开发者应关注工具链的更新，及时调整项目配置以获得最佳的开发体验。