Vite+React+TypeScript项目ESLint跨平台运行异常问题咨询

项目ESLint配置（.eslintrc.json） #

{
  "extends": [
    "eslint:recommended",
    "airbnb/hooks",
    "airbnb-typescript",
    "plugin:react/recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:prettier/recommended"
  ],
  "parserOptions": {
    "project": "./tsconfig.json"
  },
  "rules": {
    "react-hooks/exhaustive-deps": "off",
    "@typescript-eslint/no-explicit-any": "off",
    "import/order": [
      "error",
      {
        "groups": [["external", "builtin"], "internal", "parent", "sibling", "index"],
        "alphabetize": { "order": "asc", "caseInsensitive": true }
      }
    ]
  },
  "settings": {
    "import/resolver": {
      "typescript": { "project": "./tsconfig.json" }
    }
  }
}

问题描述 #

本地执行eslint . --ext .ts,.tsx无任何错误，但Windows系统的队友运行相同命令时出现多个lint错误。

环境差异 #

• 本地：macOS系统（无ESLint错误）
• 队友：Windows系统（出现ESLint错误）

怀疑是路径解析、换行符（LF vs CRLF）或大小写敏感性导致的问题，求相关分析与解决方案。

已尝试操作 #

• 确保所有队友使用相同版本的node_modules和ESLint
• 删除node_modules和package-lock.json后重新执行npm install
• 检查并禁用全局ESLint设置
• 仅启用ESLint和Prettier插件的VS Code环境
• 在VS Code外手动运行ESLint

问题分析与解决建议 #

1. 大小写敏感性问题 #

macOS文件系统默认不区分大小写，Windows则默认区分。如果代码中导入路径的大小写与实际文件目录/文件名不匹配（比如导入./components/Button但实际文件是./components/button），macOS下ESLint不会报错，Windows下会触发import/no-unresolved或类型检查类错误。

• 解决建议：
  • 统一代码中所有导入路径的大小写，与实际文件完全匹配
  • 在tsconfig.json中添加"forceConsistentCasingInFileNames": true，强制TypeScript检查文件名大小写一致性，从编译阶段拦截问题

2. 路径解析差异 #

Windows用反斜杠\作为路径分隔符，macOS用正斜杠/。虽然多数工具会自动兼容，但部分配置或插件可能存在适配问题：

• 检查点：
  • 确认tsconfig.json的baseUrl、paths配置使用相对路径，避免硬编码绝对路径
  • 验证import/resolver是否正确指向tsconfig.json，确保跨系统路径解析逻辑一致
• 解决建议：
  • 在.eslintrc.json的import/resolver中明确指定扩展名，避免解析歧义：

    "import/resolver": {
      "typescript": {
        "project": "./tsconfig.json",
        "extensions": [".ts", ".tsx", ".js", ".jsx"]
      }
    }
    

3. 换行符差异（LF vs CRLF） #

Airbnb的ESLint配置默认启用linebreak-style规则，Windows下如果文件使用CRLF换行符，会触发该规则报错；同时Prettier的换行符设置也可能导致跨系统差异。

• 解决建议：
  • 在项目根目录添加.editorconfig文件，强制统一换行符：

    root = true
    
    [*]
    end_of_line = lf
    charset = utf-8
    indent_style = space
    indent_size = 2
    trim_trailing_whitespace = true
    insert_final_newline = true
    

  • 调整ESLint的linebreak-style规则，允许自动适配系统：

    "rules": {
      "linebreak-style": ["error", "unix", { "overrides": { "windows": "windows" } }]
    }
    

  • 配置Git自动转换换行符：Windows用户执行git config --global core.autocrlf true，macOS/Linux用户执行git config --global core.autocrlf input，确保代码提交时统一为LF

4. 其他排查点 #

• 确认队友的tsconfig.json与本地完全一致，尤其是include、exclude字段，避免ESLint扫描到额外文件
• 检查.eslintignore配置，确保队友本地的忽略规则和项目统一

内容的提问来源于stack exchange，提问作者Ethan Caldwell