Super-Linter 中 TSX 文件校验的 ERR_UNKNOWN_FILE_EXTENSION 问题解析

问题现象

在使用 Super-Linter 对 Next.js 项目中的 TSX 文件进行校验时，开发者遇到了 ERR_UNKNOWN_FILE_EXTENSION 错误。该错误出现在 ESLint 处理配置文件时，具体表现为无法识别 .yml 文件扩展名。

错误分析

从错误日志可以看出，问题发生在 ESLint 8.57.1 版本尝试加载 .eslintrc.yml 配置文件时。Node.js 的 ESM 模块系统无法识别 .yml 扩展名，导致校验过程失败。

配置建议

1. 配置文件格式选择：

   • 推荐使用 .js 或 .cjs 扩展名的 ESLint 配置文件
   • 避免使用 .mjs 或 .yml 格式的配置文件
   • 确保配置文件内容使用 CommonJS 语法

2. 环境变量设置：

   • 正确使用 TYPESCRIPT_ES_CONFIG_FILE 变量指定配置文件路径
   • 避免同时设置 VALIDATE_xxxx 变量的 true 和 false 值

3. 权限配置：

   • 确保 GitHub Actions 工作流具有足够的权限
   • 特别是 pull request 状态检查需要额外授权

解决方案

1. 修改配置文件：

   • 将现有的 eslint.config.mjs 重命名为 eslint.config.cjs
   • 确保配置文件内容使用 module.exports 而非 export default

2. 调整工作流配置：

   env:
     VALIDATE_TYPESCRIPT_ES: true
     TYPESCRIPT_ES_CONFIG_FILE: eslint.config.cjs
   

3. 权限调整：

   permissions:
     contents: read
     pull-requests: read
     statuses: write
   

技术背景

Super-Linter 在容器环境中运行，其 Node.js 运行时默认配置为 CommonJS 模块系统。当遇到 ESM 模块或非常规扩展名的配置文件时，可能会出现模块加载错误。理解 Node.js 的模块解析机制对于解决此类问题至关重要。

最佳实践

1. 保持配置文件简单明确
2. 优先使用 JavaScript 格式的配置文件
3. 定期更新 Super-Linter 版本以获取最新修复
4. 在本地环境复现问题有助于快速调试

通过以上调整，可以解决 TSX 文件校验中的文件扩展名识别问题，确保代码质量检查流程顺畅运行。