TypeScript-ESLint 配置中关于 no-undef 规则的最佳实践

在 TypeScript 项目中配置 ESLint 时，no-undef 规则的处理是一个需要特别注意的技术点。本文将通过一个典型场景，深入分析如何正确配置 TypeScript-ESLint 以避免常见的 linting 问题。

问题背景

当开发者按照 TypeScript-ESLint 官方文档进行初始配置时，可能会遇到 no-undef 规则引发的错误提示。这些错误通常出现在 JavaScript 配置文件（如 .cjs 或 .mjs 文件）中，提示某些全局变量（如 module、console）未定义。

技术分析

为什么会出现这个问题

1. 规则来源：no-undef 规则来自 ESLint 的核心推荐配置（eslint.configs.recommended），默认会对所有文件生效
2. TypeScript 的特殊性：TypeScript 编译器本身已经具备类型检查能力，能够检测未定义变量，因此在 TypeScript 文件中重复使用 no-undef 规则是冗余的
3. JavaScript 文件的处理：对于非 TypeScript 文件（如项目配置文件），TypeScript 编译器不会进行类型检查，此时 no-undef 规则仍有其价值

解决方案

正确的配置应该区分对待 TypeScript 文件和 JavaScript 文件：

import { config as tseslint } from 'typescript-eslint';
import eslint from 'eslint';
import globals from 'globals';

export default tseslint(
  eslint.configs.recommended,
  {
    files: ['**/*.js', '**/*.cjs', '**/*.mjs'],
    languageOptions: {
      globals: {
        ...globals.node,
        // 可根据需要添加其他环境全局变量
      },
    },
  },
  ...tseslint.configs.recommended
);

这个配置实现了：

1. 对所有文件应用 ESLint 核心推荐规则
2. 为 JavaScript 类文件明确指定 Node.js 环境全局变量
3. 应用 TypeScript-ESLint 推荐配置（会自动禁用 TypeScript 文件中的 no-undef 规则）

进阶建议

1. 环境配置：根据项目实际运行环境，可能需要添加 browser 或其他环境的全局变量
2. 配置文件类型：现代 JavaScript 项目可能包含多种配置文件类型（如 .eslintrc.cjs、vite.config.ts），需要确保每种文件类型都得到正确处理
3. 性能考量：对于大型项目，可以进一步细化文件匹配模式，避免不必要的 linting 检查

总结

TypeScript-ESLint 的配置需要理解不同文件类型的处理差异。通过合理配置，既能利用 TypeScript 的类型检查优势，又能在 JavaScript 配置文件中保持必要的 linting 检查。这种精细化的配置策略是构建健壮 TypeScript 项目的基础之一。

对于初学者，建议从简单配置开始，随着项目复杂度增加再逐步细化 linting 规则。记住，好的 linting 配置应该既保证代码质量，又不妨碍开发效率。