CommitLint 在 ES 模块项目中的配置问题解析

CommitLint 是一个流行的 Git 提交消息规范检查工具，但在 ES 模块项目中使用时可能会遇到配置问题。本文将深入分析这一问题的成因，并提供完整的解决方案。

问题现象

当项目在 package.json 中设置了 "type": "module" 时，运行 CommitLint 会报错：

ReferenceError: module is not defined in ES module scope

错误提示表明 Node.js 将配置文件当作 ES 模块处理，但配置文件中使用了 CommonJS 的语法。

根本原因

Node.js 从 12 版本开始支持 ES 模块，通过 package.json 中的 "type" 字段来指定模块系统：

• "type": "module"：将 .js 文件视为 ES 模块
• 无指定或 "type": "commonjs"：将 .js 文件视为 CommonJS 模块

CommitLint 的默认配置文件（commitlint.config.js）使用 CommonJS 语法（module.exports），当项目设置为 ES 模块时就会产生冲突。

解决方案

有三种方法可以解决这个问题：

方法一：使用 .cjs 扩展名

将配置文件重命名为 commitlint.config.cjs，Node.js 会始终将其作为 CommonJS 模块处理。

方法二：使用 .mjs 扩展名

将配置文件重命名为 commitlint.config.mjs，并使用 ES 模块语法：

export default {
  extends: ['@commitlint/config-conventional']
};

方法三：修改 package.json 配置

在 package.json 中指定特定文件的模块类型：

{
  "type": "module",
  "exports": {
    "./commitlint.config.js": {
      "require": "./commitlint.config.js",
      "default": "./commitlint.config.js"
    }
  }
}

最佳实践建议

1. 统一项目规范：如果项目主要使用 ES 模块，建议采用 .mjs 方案，保持一致性
2. 兼容性考虑：如果需要支持较旧版本的 Node.js，.cjs 方案更可靠
3. 配置验证：修改后运行 echo "test" | commitlint 验证配置是否生效

技术原理扩展

Node.js 的模块解析规则：

1. 优先检查文件扩展名：
   • .mjs 总是作为 ES 模块
   • .cjs 总是作为 CommonJS 模块
2. 无扩展名时检查最近的 package.json 中的 "type" 字段
3. 默认使用 CommonJS

理解这些规则有助于在各种工具链配置中避免类似问题，不仅限于 CommitLint，也适用于 ESLint、Prettier 等工具的配置文件。