深入解析 ESLint `space-before-keywords` 规则：关键字前置空格的强制规范与 `keyword-spacing` 演进之路

深入解析 ESLintspace-before-keywords规则：关键字前置空格的强制规范与keyword-spacing演进之路

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

关键字（keyword）是 JavaScript 语法结构中的保留标识符，例如function、if、return等。它们在语言中具有特殊含义，其前后空格的使用方式往往是团队代码风格规范的重要一环。本文基于 ESLint 仓库中的space-before-keywords规则文档，完整还原该规则的设计理念、参数选项与正反示例，并结合仓库源码剖析其接替者keyword-spacing的底层实现原理。读完本文，你将掌握关键字前置空格的两种风格（always/never）如何配置，理解该规则为何在 ESLint v2.0.0 被移除、如何平滑迁移到keyword-spacing，以及新规则在源码层面如何完成检查与自动修复。

规则背景：为什么需要规范关键字前的空格

关键字是 JavaScript 语法元素的组成部分，如function和if。这些标识符对语言具有特殊含义，因此代码编辑器中通常会以不同的颜色显示它们。作为语言的重要组成部分，各类风格指南常常对关键字周围的空格做出约定。例如，你可能有一个风格指南要求关键字必须始终被空格前置，那么if-else语句必须写成这样：

if (foo) { // ... } else { // ... }

当然，也可能存在相反的风格指南——禁止在关键字前出现空格。

space-before-keywords规则正是为了在团队中统一"关键字前是否留空格"这一细节而设计的。该规则属于布局类（layout）规则，并且支持自动修复：原文档明确指出，通过命令行的--fix选项，可以自动修复该规则报告的问题（fixable）。

重要提示：该规则已在 ESLint v2.0.0 中被移除，由 keyword-spacing 规则取代。仓库的版本数据文件 rule_versions.json 中记录着这条规则的生命周期：其首次出现于 1.4.0（"space-before-keywords": "1.4.0"），在 2.0.0-beta.3（"space-before-keywords": "2.0.0-beta.3"）之后正式退役。

规则详情：覆盖的关键字与两种风格选项

该规则将强制以下关键字之前的空格一致性：

• 条件与循环：if、else、for、while、do、switch
• 异常处理：throw、try、catch、finally
• 流程控制：with、break、continue、return
• 声明：function、yield、class，以及变量声明（let、const、var）
• 标签语句（label statements）

参数选项

该规则接收一个参数："always"或"never"：

值得注意的是，当选项为"always"时，该规则允许关键字前面出现左花括号{（即}else {会被要求修正，但{后的换行与空格不在此规则管辖范围）。如果你希望调整这一行为，可以考虑使用 block-spacing 规则。

代码示例："always"选项下的正反例

默认"always"选项下的错误代码

/*eslint space-before-keywords: ["error", "always"]*/ if (foo) { // ... }else {} // "else" 前缺少空格 const foo = 'bar';let baz = 'qux'; // "let" 前缺少空格 var qux =function bar () {} // "function" 前缺少空格 function bar() { if (foo) {return; } // "return" 前缺少空格 }

默认"always"选项下的正确代码

/*eslint space-before-keywords: ["error", "always"]*/ if (foo) { // ... } else {} // "else" 前有空格 (function() {})(); // "function" 前是 "( )" 等起始符号，不受限制 <Foo onClick={function bar() {}} /> // JSX 属性中的 function 表达式 for (let foo of ['bar', 'baz', 'qux']) {} // "for"/"of" 前均有空格

从上面的 JSX 示例可以看出，该规则同样作用于 JSX 语法上下文中的关键字（示例中开启了parserOptions.ecmaFeatures.jsx）。

代码示例："never"选项下的正反例

"never"选项下的错误代码

/*eslint space-before-keywords: ["error", "never"]*/ if (foo) { // ... } else {} // "else" 前不应有空格 do { } while (foo) // do...while 的 "while" 前不应有空格 try {} finally {} // "finally" 前不应有空格 try {} catch(e) {} // "catch" 前不应有空格

"never"选项下的正确代码

/*eslint space-before-keywords: ["error", "never"]*/ if (foo) { // ... }else {} // "else" 前无空格 do {}while (foo) // do...while 的 "while" 前无空格 try {}finally {} // "finally" 前无空格 try{}catch(e) {} // "catch" 前无空格

何时不使用该规则

如果你不希望强制执行关键字空格的一致性，则可以完全关闭此规则（不启用space-before-keywords）。

规则的演进：v2.0.0 移除与keyword-spacing接替

space-before-keywords之所以被移除，是因为 ESLint 团队在 v2.0.0 推出了能力更全面的keyword-spacing规则——后者不仅能控制关键字之前（before）的空格，还能控制关键字之后（after）的空格，并且支持对每个关键字单独定制（overrides）。

仓库中的 replacements.json 明确记录了这一替代关系：

"space-before-keywords": ["keyword-spacing"]

同时，迁移指南 migrating-to-2.0.0.md 也写明了对应说明：

space-before-keywordsis replaced bykeyword-spacing.

因此，如果你从旧版本升级到 ESLint 2.0.0 或更高版本，只需将配置中的规则名替换为keyword-spacing，并按下文所述方式设置before选项即可保持原有的检查行为。

源码剖析：keyword-spacing如何实现"关键字前空格"检查

替代规则 keyword-spacing.js 的实现位于仓库lib/rules/目录，其meta声明为type: "layout"（布局类）与fixable: "whitespace"（可自动修复空白）。其配置 Schema 如下（源码 lib/rules/keyword-spacing.js 第 112–136 行）：

schema: [ { type: "object", properties: { before: { type: "boolean", default: true }, after: { type: "boolean", default: true }, overrides: { type: "object", properties: KEYS.reduce((retv, key) => { retv[key] = { type: "object", properties: { before: { type: "boolean" }, after: { type: "boolean" }, }, additionalProperties: false, }; return retv; }, {}), additionalProperties: false, }, }, additionalProperties: false, }, ],

该 Schema 揭示了三层能力：

• before（默认true）：控制关键字前是否需要空格，等价于旧的space-before-keywords的"always"（true）与"never"（false）；
• after（默认true）：控制关键字后是否需要空格，这是旧规则不具备的能力；
• overrides：以关键字名为键，可针对单个关键字单独覆盖before/after行为，实现细粒度的"特例"控制。

在检查逻辑中，规则维护了两组正则（源码第 20–23 行）：

const PREV_TOKEN = /^[)\]}>]$/u; const NEXT_TOKEN = /^(?:[([{<~!]|\+\+?|--?)$/u; const PREV_TOKEN_M = /^[)\]}>*]$/u; const NEXT_TOKEN_M = /^[{*]$/u;

这些模式用于判断"关键字前/后的相邻 token 是什么"。当关键字前一个 token 匹配PREV_TOKEN（如}、)、]、>）时，才触发"期望空格"（expectSpaceBefore）或"禁止空格"（unexpectSpaceBefore）的判断。

修复逻辑的底层实现

expectSpaceBefore（源码第 156–177 行）通过sourceCode.getTokenBefore(token)获取关键字的前一个 token，在满足"前一个 token 类型或值匹配模式、与关键字处于同一行、且两者之间没有空格"时报告错误，并调用修复器：

fix(fixer) { return fixer.insertTextBefore(token, " "); }

即在关键字前插入一个空格。

与之对应的unexpectSpaceBefore（源码第 185–209 行）则在"两个 token 之间存在空格"时报告错误，并移除两者之间的空白区域：

fix(fixer) { return fixer.removeRange([ prevToken.range[1], token.range[0], ]); }

这种"先取前一个 token、再判断行内空格"的机制，保证了规则只在同一行内检查空格，不会误伤跨行代码（例如else换行到下一行的写法）。规则在create阶段会根据options.before !== false决定对每个关键字挂载expectSpaceBefore还是unexpectSpaceBefore（源码第 280–300 行），并支持overrides中的逐关键字覆盖，这正是迁移自space-before-keywords后最直接的对应关系。

测试用例印证

在测试文件 tests/lib/rules/keyword-spacing.js 中，可以看到对before: false的验证（等价于旧的"never"选项）：

options: [{ before: false }],

以及通过overrides对单个关键字做特判的用例，例如对else、if单独设置before: false、as设置before: true等（测试第 982–987 行、1234–1248 行、2395 行、4904 行）。这些用例直接覆盖了从"全局统一"到"逐关键字定制"的全部配置形态。

迁移对照：从space-before-keywords到keyword-spacing

综合原规则文档与keyword-spacing的源码 Schema，两者的配置映射关系如下：

迁移时的关键提醒：原space-before-keywords的"never"只作用于else、while（do...while）、finally和catch四个关键字；而keyword-spacing的before: false会影响其关键字列表中的全部关键字（源码中KEYS由keywords模块导出，并额外包含as、async、await、from、get、let、of、set、yield等，见 keyword-spacing.js 第 28–38 行）。因此，如果旧配置使用"never"，迁移到新规则后若不想改变对if、for等关键字的行为，需要借助overrides精确指定哪些关键字前置空格被禁用，例如：

{ "rules": { "keyword-spacing": ["error", { "before": true, "overrides": { "else": { "before": false }, "catch": { "before": false }, "finally": { "before": false } } }] } }

补充：keyword-spacing的后续命运与格式化规则迁移

需要留意的是，keyword-spacing规则本身在 ESLint 8.53.0 也被标记为弃用。仓库源码 keyword-spacing.js 第 80–101 行的meta.deprecated字段记录了这一事实：该规则属于格式化类规则，ESLint 团队正逐步将格式化规则移出核心，keyword-spacing计划在 11.0.0 之后从核心中移除，其维护职责已移交至 ESLint Stylistic 项目（@stylistic/eslint-plugin中的keyword-spacing规则）。这意味着，新项目若需要关键字空格检查，建议直接使用 ESLint Stylistic 提供的对应规则；而历史项目在升级时则需关注这一迁移路径。

总结

space-before-keywords虽然已在 ESLint v2.0.0 退役，但它所承载的"关键字前空格一致性"这一风格诉求至今仍是格式化检查的重要一环。通过本文，你不仅完整掌握了该规则的两个选项（always/never）及其全部正反示例，还深入理解了其接替者keyword-spacing在 lib/rules/keyword-spacing.js 中的 Schema 设计、token 相邻判断机制与自动修复实现，以及从旧规则到新规则的精确迁移对照。当你需要在团队中统一关键字空格风格时，无论是直接启用现代规则，还是阅读历史代码中的旧配置，都可以借助本文快速定位到正确的配置形态。

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