企业官网建设流程全解析

ESLint 完全使用指南：安装、配置与语义化版本策略

【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint

ESLint 是用于在 ECMAScript/JavaScript 代码中识别并报告问题模式（problem patterns）的静态检查工具，其核心定位是“Find and fix problems in your JavaScript code”。本文以 ESLint 官方 README（README.md）为主体，结合当前仓库源码（版本 10.9.1，见 package.json）深入讲解：如何安装与初始化、如何编写eslint.config.js扁平配置文件、三种规则级别的含义，以及版本支持、语义化版本策略、ESM 依赖约束等工程化细节。读完本文，你将能独立完成 ESLint 的安装配置、规则调优，并理解其发布策略对 CI 构建稳定性的影响。

ESLint 是什么

ESLint 是一个用于在 ECMAScript/JavaScript 代码中识别并报告问题模式的工具。在许多方面它与 JSLint、JSHint 类似，但有以下几个关键区别：

• ESLint 使用 Espree 进行 JavaScript 解析；
• ESLint 使用 AST（抽象语法树）来评估代码中的模式；
• ESLint 完全可插拔（pluggable），每一条规则本身就是一个插件，并且可以在运行时随时添加更多规则。

从源码看，这三点均有明确对应实现：lib/languages/js/index.js 中直接require("espree")并将 espree 作为默认解析器（parser: espree）；所有内置规则都位于 lib/rules/ 目录下，每条规则一个文件、通过meta与create导出，例如 lib/rules/prefer-const.js 与 lib/rules/no-constant-binary-expression.js；规则既可以作为内置规则加载，也可以作为第三方插件在运行时动态注册。

安装与使用

环境要求（Prerequisites）

要使用 ESLint，你必须安装 Node.js 且版本满足^20.19.0、^22.13.0或>=24，并且 Node.js 需要以 SSL 和 ICU 支持构建（如果使用官方 Node.js 发行版，SSL 和 ICU 始终已内置）。

如果使用 ESLint 的 TypeScript 类型定义，还需要 TypeScript 5.3 或更高版本。这一点在 package.json 的engines字段中得到了印证：

"engines": { "node": "^20.19.0 || ^22.13.0 || >=24" }

仓库的 tsconfig.types-legacy.json 与 tsconfig.types.json 分别用于针对 TypeScript 5.3 与 5.x 的类型测试，package.json 中也提供了test:types:5.3、test:types:5.x等脚本用于验证不同 TS 版本的兼容性。

npm 安装

可以使用以下命令安装并配置 ESLint：

npm init @eslint/config@latest

该命令会启动交互式初始化向导，根据你的项目情况（模块类型、框架、TypeScript 与否等）自动生成eslint.config.js配置文件并安装必要依赖。

之后，可以对任何文件或目录运行 ESLint：

npx eslint yourfile.js

ESLint 的 CLI 二进制入口定义在 package.json 的bin字段（"eslint": "./bin/eslint.js"），CLI 选项解析实现在 lib/options.js 中，其用法格式为eslint [options] file.js [file.js] [dir]。

pnpm 安装

使用 pnpm 时，建议在项目根目录设置一个.npmrc文件，至少包含以下配置：

auto-install-peers=true node-linker=hoisted

这可以确保 pnpm 以与 npm 更兼容的方式安装依赖，从而减少报错的可能。仓库本身也使用 pnpm 工作区（workspaces字段见 package.json），并有专门的 pnpm 测试（test:pnpm脚本与 tests/pnpm/ 目录）验证 pnpm 环境下的可用性。

配置：eslint.config.js 与扁平配置

基本配置示例

可以在eslint.config.js文件中配置规则，例如：

import { defineConfig } from "eslint/config"; export default defineConfig([ { files: ["**/*.js", "**/*.cjs", "**/*.mjs"], rules: { "prefer-const": "warn", "no-constant-binary-expression": "error", }, }, ]);

这里defineConfig是从eslint/config子路径导入的，其实现位于 lib/config-api.js，由@eslint/config-helpers提供，除defineConfig外还导出了globalIgnores与includeIgnoreFile，可用于声明全局忽略模式或将.gitignore文件纳入忽略规则。该子路径的导出映射定义在 package.json 的exports字段中。

扁平配置（Flat Config）的加载机制

从源码看，配置在运行时由 lib/config/flat-config-array.js 中的FlatConfigArray统一管理。它继承自@eslint/config-array的ConfigArray，并按以下顺序组织配置：

1. 基础配置（Base config）
2. 原始配置（Original configs）
3. 用户定义配置（User-defined configs，即从eslint.config.*加载的内容）
4. CLI 定义配置（CLI-defined configs）

配置文件的实际加载逻辑位于 lib/config/config-loader.js，运行时统一入口类为 lib/eslint/eslint.js 中的ESLint。

规则级别（error level）

示例中的"prefer-const"和"no-constant-binary-expression"是 ESLint 中规则的名称。每条规则的第一个值是规则级别（error level），可以是以下值之一：

三种错误级别让你可以精细控制 ESLint 应用规则的方式。作为佐证，tests/conf/eslint-recommended.js 中验证了eslint:recommended预设将no-undef配置为"error"，而不会配置非推荐规则（如camelcase）：

it("should configure recommended rules as error", () => { assert.strictEqual(rules["no-undef"], "error"); }); it("should not configure non-recommended rules", () => { assert.notProperty(rules, "camelcase"); });

内置的eslint:recommended与eslint:all预设定义在 packages/js/src/index.js 中，从./configs/eslint-recommended与./configs/eslint-all导出。

版本支持（Version Support）

ESLint 团队对当前版本提供持续支持，对上一个版本提供六个月的有限支持。有限支持仅包括关键 bug 修复、安全问题与兼容性问题。

ESLint 通过合作伙伴 Tidelift 和 HeroDevs 为当前版本和上一版本提供商业支持。

每个 ESLint 主版本发布时，受支持的 Node.js 版本会被更新为：

1. Node.js 最新的维护版本（most recent maintenance release）；
2. 包含 ESLint 团队希望使用的特性的 Node.js LTS 版本的最低 minor 版本；
3. Node.js Current 版本。

ESLint 也预期可以在 Node.js Current 之后发布的版本上正常工作。

常见问题（FAQ）

ESLint 支持 JSX 吗？

支持。ESLint 原生支持解析 JSX 语法（需要在配置中启用）。请注意，支持 JSX 语法并不等同于支持 React——React 对 JSX 语法应用了 ESLint 无法识别的特定语义。如果使用 React 并需要 React 语义，建议使用eslint-plugin-react。

从实现看，ESLint 的核心语言包（lib/languages/js/index.js）通过 espree 解析器解析代码，而 JSX、Flow、TypeScript 等语言扩展则由社区解析器与插件提供（如@babel/eslint-parser、@typescript-eslint/parser）。

Prettier 会取代 ESLint 吗？

不会。ESLint 和 Prettier 的职责不同：ESLint 是 linter（查找问题模式），Prettier 是代码格式化器（code formatter）。两者同时使用很常见，可以参考 Prettier 官方文档了解如何配置二者协同工作。

ESLint 支持哪些 ECMAScript 版本？

ESLint 完全支持 ECMAScript 3、5 以及从 2015 年起直到最新 stage 4 规范（默认）的每一年版本。可以通过配置设置所需的 ECMAScript 语法以及其他设置（如全局变量）。

实验性特性如何处理？

ESLint 的解析器只正式支持最新的最终版 ECMAScript 标准。为了在 stage 3 的 ECMAScript 语法提案（只要它们使用正确的实验性 ESTree 语法实现）上避免崩溃，ESLint 会修改核心规则。ESLint 也可能根据具体情况修改核心规则，以更好地支持语言扩展（如 JSX、Flow 和 TypeScript）。

在其他情况下（包括因新语法需要规则报告更多或更少的情况，而不仅仅是避免崩溃），建议使用其他解析器和/或规则插件。如果使用 Babel，可以使用@babel/eslint-parser和@babel/eslint-plugin来使用 Babel 中的任何选项。

一旦某个语言特性被纳入 ECMAScript 标准（根据 TC39 流程达到 stage 4），ESLint 将根据贡献指南接受与该新特性相关的 issue 和 pull request。在此之前，请为你的实验性特性使用适当的解析器和插件。

ESLint 支持哪些 Node.js 版本？

ESLint 会在每个主版本发布时更新受支持的 Node.js 版本，更新规则见上文"版本支持"一节。

去哪里寻求帮助？

可以开启一个 discussion，或加入 ESLint 的 Discord 服务器。

为什么 ESLint 不锁定依赖版本？

锁文件（如package-lock.json）对部署应用很有帮助，它们确保依赖在不同环境和部署之间保持一致。

而像eslint这样发布到 npm registry 的包不包含锁文件。用户执行npm install eslint时会遵循 ESLintpackage.json中的版本约束。ESLint 及其依赖会包含在用户的锁文件（如果存在）中，但 ESLint 自己的锁文件不会被使用。

ESLint 故意不锁定依赖版本，以便在开发和 CI 中使用与用户安装 ESLint 时得到的最新兼容依赖版本保持一致。

发布节奏（Releases）

ESLint 每两周在周五或周六安排一次发布。可以关注 release issue 了解任何特定发布的排期更新。

安全策略（Security Policy）

ESLint 非常重视安全。团队努力确保 ESLint 对所有人都是安全的，并且安全问题的处理快速且负责。完整的 security policy 可以在仓库的 SECURITY.md 中阅读。

语义化版本策略（Semantic Versioning Policy）

ESLint 遵循语义化版本（semver）。然而，由于 ESLint 作为代码质量工具的特性，minor 或 major 版本何时提升并不总是清晰的。为此，ESLint 定义了以下语义化版本策略：

Patch 版本（旨在不破坏你的 lint 构建）

• 规则中的 bug 修复，使 ESLint 报告的 lint 错误减少；
• CLI 或核心（包括 formatters）的 bug 修复；
• 文档改进；
• 非用户可见的更改，如重构代码、添加/删除/修改测试、提高测试覆盖率；
• 在失败发布后重新发布（即发布一个对任何人都无法工作的版本）。

Minor 版本（可能破坏你的 lint 构建）

• 导致 ESLint 报告更多 lint 错误的 bug 修复（例如修复核心规则的漏报，或 lint 之前被错误跳过的额外文件）；
• 创建新规则；
• 现有规则的新选项，默认情况下不会导致 ESLint 报告更多 lint 错误；
• 现有规则新增对语言特性的支持（最近 12 个月内），默认情况下会导致 ESLint 报告更多 lint 错误；
• 弃用现有规则；
• 创建新的 CLI 能力；
• 公共 API 新增能力（新类、新方法、现有方法的新参数等）；
• 创建新的 formatter；
• eslint:recommended更新且只会导致 lint 错误严格减少（如规则移除）。

Major 版本（很可能破坏你的 lint 构建）

• eslint:recommended更新且可能导致新的 lint 错误（如规则新增、大部分规则选项更新）；
• 现有规则的新选项默认会导致 ESLint 报告更多 lint 错误；
• 移除现有 formatter；
• 公共 API 的一部分被移除或以不兼容的方式更改。公共 API 包括：
  • 规则 schema（Rule schemas）
  • 配置 schema（Configuration schema）
  • 命令行选项（Command-line options）
  • Node.js API
  • 规则、formatter、parser、plugin API

根据该策略，任何 minor 更新都可能比之前的版本报告更多的 lint 错误（例如来自 bug 修复）。因此，建议在package.json中使用波浪号（~），例如"eslint": "~3.1.0"，以保证构建结果的一致性。

ESM 依赖约束（ESM Dependencies）

由于 ESLint 是 CommonJS 包，对哪些仅支持 ESM 的包可以用作依赖存在限制。

由 ESLint 团队控制且没有外部依赖的包，可以安全地使用require(esm)同步加载，因此可以在任何上下文中使用。

对于外部包，ESLint 不使用require(esm)，因为包可能添加顶层await从而破坏 ESLint。只有在异步代码中需要时，才可以使用动态import()加载外部 ESM-only 包。

这些策略不适用于仅供 ESLint 自己使用的包，例如eslint-config-eslint（位于 packages/eslint-config-eslint/）。

许可证

ESLint 使用 MIT License，版权归 OpenJS Foundation 及其他贡献者所有。许可证全文见 LICENSE。

从源码继续深入

如果你希望进一步理解 ESLint 的底层实现，以下仓库路径是很好的切入点：

• 规则定义：lib/rules/（每个规则一个文件，如 lib/rules/prefer-const.js）
• 扁平配置加载：lib/config/flat-config-array.js 与 lib/config/config-loader.js
• 核心运行入口：lib/eslint/eslint.js（ESLint类）与 lib/linter/linter.js
• 公共 API 导出：lib/api.js（导出ESLint、Linter、RuleTester、SourceCode、loadESLint）与 lib/config-api.js（导出defineConfig、globalIgnores、includeIgnoreFile）
• 预设计配置：packages/js/src/index.js（eslint:recommended与eslint:all）
• 测试参考：tests/lib/rules/ 与 tests/conf/eslint-recommended.js

【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint