**结论先行:ESLint v10 已彻底移除 eslintrc 配置体系,.eslintrc.* 文件、/* eslint-env / 注释与 --ignore-path 标志全部退场,flat config 成为唯一选择;迁移的核心动作是「extends 改 import 展开、overrides 改带 files 的配置对象、env 改 languageOptions.globals」,TypeScript 项目建议同步切换到 typescript-eslint 聚合包。* 本文给出从 v8/v9 到 v10 的完整迁移路径与排错清单。
v9 到 v10 的破坏性变更
ESLint v9 已把 flat config 设为默认,但保留 eslintrc 回退;v10(2026 年初发布,具体以官方公告为准)则完全切断回退:
| 项目 | v9 | v10 |
|---|---|---|
| .eslintrc.* | 仍可作为回退 | 完全不支持 |
| /* eslint-env */ 注释 | 支持 | 移除,改用 globals 配置 |
| --ignore-path | 可用 | 移除,改用 ignores |
| 配置格式 | 双轨 | 仅 eslint.config.* |
从 v8 直升 v10 的项目,需要按 v8→v9→v10 顺序消化两份官方迁移指南,因为 v10 假定你已处理 v9 的变更(Node.js 版本要求、formatters 拆分等)。
迁移六步
第一步,删除 .eslintrc.* 与 .eslintignore,新建 eslint.config.mjs。第二步,把 extends 数组改为 import + 展开。第三步,overrides 拆成带 files 的独立对象,注意 glob 要写 **/*.test.js 才能递归匹配。第四步,env 换成 globals 包。第五步,忽略规则写进 ignores 且置于数组最前。第六步,清理行内注释中的旧规则前缀与 eslint-env。一份典型的迁移后配置:
import js from '@eslint/js';
import globals from 'globals';
import tseslint from 'typescript-eslint';
import { defineConfig } from 'eslint/config';
export default defineConfig([
{ ignores: ['dist/**', 'node_modules/**'] },
js.configs.recommended,
...tseslint.configs.recommended,
{
files: ['**/*.{js,mjs,cjs,ts,tsx}'],
languageOptions: {
globals: { ...globals.browser, ...globals.node },
},
rules: { 'no-console': 'warn' },
},
{
files: ['**/*.test.ts'],
rules: { 'no-console': 'off' },
},
]);defineConfig 来自 eslint/config,提供类型提示与校验;数组中后出现的配置覆盖先前的同名规则,这正是「通用配置在前、特例在后」的组织依据。
typescript-eslint 聚合包
过去要分别安装 @typescript-eslint/parser 与 @typescript-eslint/eslint-plugin 并手工接线,现在统一使用 typescript-eslint 聚合包(v8 系列):tseslint.configs.recommended 开箱即用;需要类型感知规则时用 recommendedTypeChecked,并配合 languageOptions.parserOptions.projectService: true 让解析器自动找到 tsconfig。注意类型感知规则会显著增加 lint 耗时,建议只在 CI 全量开启,本地编辑器用非类型感知子集。
常见报错排查
「ESLintrc configuration objects are no longer supported」:v10 读到了旧配置,按上文迁移。「Cannot redefine plugin」:多个预设展开时注册了同名插件的不同实例,升级插件到支持 flat config 的版本,或保证同一命名空间指向同一对象。「Definition for rule was not found」:插件未注册或规则前缀变更,例如 eslint-comments/* 已迁移为 @eslint-community/eslint-comments/。编辑器不生效:确认 VS Code ESLint 扩展版本支持 flat config,并检查 eslint.config. 位于项目根目录。
用真实项目练手
迁移最好的练习场是有历史包袱的真实仓库。api工厂开源的 vueMinishop 与 wechat-app-mall 两套商城前端(大全见 https://www.it120.cc/help/uq920k.html)就是典型的多端存量项目:先在其上完成 flat config 迁移,再把同一套 eslint.config.mjs 作为共享配置包发进自己的 monorepo。业务接口由 api工厂 SDK(https://www.it120.cc/sdk/index.html)统一提供,lint 规则可以专注于前端代码质量本身,不必为后端模板文件分心。
文章标签
相关产品
api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。