ActiveAdmin v4 插件模块兼容性问题解析与解决方案

问题背景

ActiveAdmin 是一个流行的 Ruby on Rails 后台管理框架，其最新版本 v4 在 JavaScript 模块系统兼容性方面出现了一些问题。核心问题源于项目在 package.json 中声明了 "type": "module"，但同时提供了 CommonJS 格式的 plugin.js 文件，这在现代 Node.js 环境下会导致模块加载冲突。

技术细节分析

模块系统冲突

Node.js 从 12 版本开始支持 ES 模块(ESM)，同时保留了传统的 CommonJS(CJS)模块系统。当 package.json 中设置了 "type": "module" 时，该包内的所有 .js 文件默认会被视为 ESM 模块。然而，ActiveAdmin v4 的 plugin.js 文件使用了 CommonJS 语法：

const plugin = require('tailwindcss/plugin')
module.exports = plugin(...)

这种混合使用方式在现代 Node.js 环境(特别是 Node 23+)中会引发以下问题：

1. 当其他项目通过 require() 加载该文件时，Node.js 会抛出 ERR_REQUIRE_ESM 错误
2. 在 ESM 环境中直接使用 require 会导致 ReferenceError
3. 使用 Vite 等现代构建工具时会出现兼容性问题

影响范围

这个问题主要影响以下使用场景：

1. 使用 Vite 或 vite_rails 构建的项目
2. 在 Node.js 23+ 环境下运行的项目
3. 任何尝试通过 require() 加载 ActiveAdmin 插件的 CommonJS 环境

解决方案

推荐方案：双格式分发

最理想的解决方案是同时提供 ESM 和 CommonJS 两种格式的插件文件：

1. 保留现有的 plugin.js 作为 ESM 模块
2. 新增 plugin.cjs 作为 CommonJS 模块
3. 在 package.json 中通过 exports 字段明确指定不同环境下的入口文件

临时解决方案

对于急需解决问题的开发者，可以采用以下临时方案：

1. 修改本地副本：复制 plugin.js 到项目本地，替换 require 为 import，module.exports 为 export default
2. 降级 Node.js：暂时使用 Node.js 22 或更早版本
3. 配置覆盖：创建自定义的 Tailwind 配置文件，避免直接引用 ActiveAdmin 的插件

实施建议

对于 ActiveAdmin 维护团队，建议采取以下步骤：

1. 将现有 plugin.js 转换为 ESM 语法
2. 创建 plugin.cjs 作为 CommonJS 版本
3. 更新 package.json 的 exports 字段：

{
  "exports": {
    "import": "./plugin.js",
    "require": "./plugin.cjs"
  }
}

4. 在文档中明确说明兼容性要求和推荐用法

未来展望

随着 JavaScript 生态向 ESM 的全面迁移，长期来看 ActiveAdmin 应该考虑：

1. 完全迁移到 ESM 模块系统
2. 提供清晰的迁移指南帮助用户过渡
3. 与主流构建工具(Vite、Webpack 等)保持更好的兼容性

这个问题反映了现代 JavaScript 生态系统中模块系统过渡期的典型挑战，通过合理的双格式分发策略，ActiveAdmin 可以为各种使用场景的用户提供更好的兼容性支持。