eslint 配置 import 的引入规则

0背景

项目开发的过程中，对于 import 的导入，尤其是 import 过多的情况下，没有一些规范的话导入非常混乱。举例：

import { Parsing, Management, Comparison, Review } from './index'
import { SvgIcon } from '@/components'
import { useMemo } from 'react'
import { Space } from '@arco-design/web-react'
import ChatSendIcon from '@/assets/svg-icon/contract/chat-send.svg'
import { useContractChat } from '../hook/useChat'
import type { Itest } from '../test/Itest'

没有区分内置模块、第三方模块、本地模块等等，显得混乱。下面以 vite + ts + react 为例，配置 import 的导入规范。

1安装依赖

首先需要安装必要的包（假设项目已使用 ESLint，若未初始化 ESLint 需先执行 npx eslint --init）：

npm install --save-dev eslint-plugin-import eslint-import-resolver-alias eslint-import-resolver-typescript

2配置 ESLint（.eslintrc.js）

在 ESLint 配置文件中添加插件和规则，重点配置 import/order 排序规则和路径解析（适配 Vite 的别名）：

module.exports = {
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  extends: [
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:react-hooks/recommended',
    'plugin:import/recommended', // 引入 import 插件的基础规则
    'plugin:import/react' // 针对 React 项目的导入规则（可选）
  ],
  parserOptions: {
    ecmaFeatures: {
      jsx: true
    },
    ecmaVersion: 'latest',
    sourceType: 'module'
  },
  plugins: [
    'react',
    'import' // 注册 import 插件
  ],
  settings: {
    'import/resolver': {
      'alias': {
        map: [['@', './src']], // 匹配@开头的路径别名
        extensions: ['.js', '.jsx', '.ts', '.tsx']
      }
    }
  },
  rules: {
    // 导入排序规则（核心配置）
    'import/order': [
      'error',
      {
        // 自定义分组顺序（按你的要求）
        groups: [
          ['builtin', 'external'], // 1. npm包（内置模块+第三方模块）
          ['internal'], // 2. @开头的路径（通过pathGroups定义）
          ['parent', 'sibling', 'index'], // 3. 相对路径（../、./、./index）
          'type' // 4. TypeScript类型导入
        ],
        // 自定义路径分组（关键：将@开头的路径归为internal组）
        pathGroups: [
          {
            pattern: '@/**', // 匹配所有@开头的路径
            group: 'internal', // 归入internal组
            position: 'after' // 在builtin和external之后
          }
        ],
        // 确保@路径不会被归到其他组
        pathGroupsExcludedImportTypes: ['builtin', 'external'],
        // 不同组之间必须空行
        'newlines-between': 'always',
        // 每组内按字母升序排序（忽略大小写）
        alphabetize: {
          order: 'asc',
          caseInsensitive: true
        }
      }
    ]
  }
}

3同步 Vite 别名配置

确保 ESLint 中的 import/resolver/alias 配置与 Vite 中的路径别名一致（在 vite.config.js 中）：

// vite.config.js
import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '@components': path.resolve(__dirname, './src/components')
      // 其他别名...
    }
  }
})

4配置自动修复（可选）

为了在保存时自动修复导入顺序，可在 package.json 中添加脚本，或配置 IDE。

package.json 脚本

{
  "scripts": {
    "lint": "eslint .",
    "lint:fix": "eslint . --fix" // 自动修复可修复的问题（包括导入顺序）
  }
}

VSCode 自动修复

在 .vscode/settings.json 中添加：

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  }
}

5注意事项

• 如果是 TypeScript 项目，需确保 tsconfig.json 中的 compilerOptions.paths 与 Vite 别名一致，避免路径解析冲突；
• 若导入排序规则不符合预期，可调整 import/order 中的 groups 顺序或添加 pathGroups 自定义特殊路径的排序（例如优先排序 @/hooks 等）；
• 部分第三方库可能需要通过 import/ignore 忽略排序（极少情况）。

配置完成后，ESLint 会自动校验并修复导入顺序，保持代码风格一致。

6结果：格式化后效果

import { Space } from '@arco-design/web-react'
import { useMemo } from 'react'

import ChatSendIcon from '@/assets/svg-icon/contract/chat-send.svg'
import { SvgIcon } from '@/components'

import { Parsing, Management, Comparison, Review } from './index'
import {
  CONSTRUCT_LIST,
  CONSTRUCT_PARSING,
  CONSTRUCT_MANAGEMENT,
  CONSTRUCT_COMPARISON,
  CONSTRUCT_REVIEW
} from '../constants/index'
import { useContractChat } from '../hook/useChat'