ESLint no-unused-labels 规则详解：自动清除重构残留的未使用标签

ESLint no-unused-labels 规则详解：自动清除重构残留的未使用标签

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

本篇指南围绕 ESLint 内置规则no-unused-labels展开，讲解如何检测并清理 JavaScript 代码中"声明了却从未被break/continue引用"的标签（Label），这类标签通常是重构不彻底的残留产物。读完本文，你将掌握该规则的报错条件、可自动修复的边界场景（注释、指令语句、ASI 陷阱）、其底层作用域栈实现原理，以及如何将它接入 eslintrc 或 flat config 配置，并与no-extra-label、no-labels、no-label-var等规则配合使用。

为什么需要关注"未使用的标签"

在 JavaScript 中，标签（Label）用于给语句命名，以便break或continue能够跳出嵌套循环或跳出代码块：

OUTER_LOOP: for (const student of students) { if (checkScores(student.scores)) { continue; } doSomething(student); }

如果声明了标签却在整个代码中从未被引用，这极有可能是不完整重构导致的错误——上面的例子中，很可能只是忘记删除OUTER_LOOP:这个标签了。这样的标签会白白占用代码空间，还会让读者产生困惑：它到底在控制什么？是否还有遗漏的跳转语句？no-unused-labels规则正是为了消除这类残留而设计的，它在 lib/rules/no-unused-labels.js 中实现，并同时出现在no-extra-label、no-labels、no-label-var等标签相关规则的关联列表中。

规则概览与元数据

从规则实现 lib/rules/no-unused-labels.js 和文档站点元数据 docs/src/_data/rules_meta.json 中可以确认该规则的关键元数据：

由于recommended: true，使用 ESLint 内置的eslint:recommended预设时，该规则会以 "error" 级别生效，无需手动配置；当然你也可以在自定义配置中显式覆盖它的级别。

Rule Details：规则的目标

该规则的目标是消除未使用的标签。只要一个标签从未被任何break或continue语句引用，无论它挂在变量声明、代码块还是循环语句上，都会被报告。

规则的报错有一个重要特性：可以自动修复，但存在两个例外场景，此时 ESLint 只会报告而不会给出修复：

1. 标签与后续语句之间存在注释——移除标签可能会连带破坏注释位置；
2. 移除标签后，后续语句会变成指令（Directive），例如"use strict"——这会意外改变代码的语义。

这两个限制的具体实现与边界条件，详见下文"自动修复的边界条件"一节。

错误的代码示例

::: incorrect

/*eslint no-unused-labels: "error"*/ A: var foo = 0; B: { foo(); } C: for (let i = 0; i < 10; ++i) { foo(); }

:::

以上三处标签A、B、C均未被任何break/continue引用，都会被报告为未使用。

正确的代码示例

::: correct

/*eslint no-unused-labels: "error"*/ A: { if (foo()) { break A; } bar(); } B: for (let i = 0; i < 10; ++i) { if (foo()) { break B; } bar(); }

:::

这两段代码中，标签A被break A引用、标签B被break B引用，属于合法的标签用法，不会触发规则。

源码剖析：基于作用域栈的标签追踪

该规则的核心实现并不复杂，其本质是一个"压栈 → 标记 → 出栈时校验"的过程，代码位于 lib/rules/no-unused-labels.js 的create(context)中。

用scopeInfo栈记录标签使用状态

规则维护了一个scopeInfo链表栈，每次遇到LabeledStatement节点时压栈（enterLabeledScope），记录标签名与used标记：

function enterLabeledScope(node) { scopeInfo = { label: node.label.name, used: false, upper: scopeInfo, }; }

当遍历到BreakStatement或ContinueStatement节点时，markAsUsed会从当前栈顶开始向上查找同名的标签并标记为已使用：

function markAsUsed(node) { if (!node.label) { return; } const label = node.label.name; let info = scopeInfo; while (info) { if (info.label === label) { info.used = true; break; } info = info.upper; } }

注意markAsUsed对无标签的break/continue（例如普通break;）直接返回，因为这类语句不会引用任何标签。

当LabeledStatement退出时（exitLabeledScope），如果scopeInfo.used仍为false，就说明该标签从未被引用，此时调用context.report上报问题，并尝试附加修复函数。这种"先记录、后判断"的设计保证了一个标签无论嵌套多深、无论break出现在它之前还是之后，都能被正确追踪——这也正是测试文件 tests/lib/rules/no-unused-labels.js 中A: { B: break B; C: for (...) { break A; continue C; } }这类嵌套用例能够通过的原因。

标签名与变量名互不干扰

一个容易混淆的点是：标签命名空间与变量命名空间是独立的。测试用例A: { var A = 0; console.log(A); }被判定为未使用标签（变量A的使用不能算作标签被使用），而A: { var A = 0; console.log(A); break A; }则是合法的。这说明规则只关心break/continue对标签的引用，与同名变量无关。

自动修复的边界条件：什么情况下不修复

规则声明fixable: "code"，但isFixable函数（lib/rules/no-unused-labels.js）对修复附加了三个严谨的前置条件。理解这些条件，你才能预测--fix的实际行为。

条件一：标签与语句之间不能有注释

修复逻辑是删除node.range[0]到node.body.range[0]之间的文本（即从标签开始到语句体开始）。如果这中间夹着注释，直接删除会连注释一起丢掉，因此规则选择放弃修复。源码通过对比"标签后的第一个 token/注释"与"语句体前的第一个 token/注释"是否为同一个 token 来判断：

if ( sourceCode.getTokenAfter(node.label, { includeComments: true }) !== sourceCode.getTokenBefore(node.body, { includeComments: true }) ) { return false; }

测试 tests/lib/rules/no-unused-labels.js 中的A: /* comment */ foo与A /* comment */: foo都验证了该行为：报错但output为null（不提供修复）。

条件二：移除标签不能让语句变成指令

指令（Directive）是指函数体或程序顶层的字符串字面量语句，例如"use strict"。如果删除标签后，原本带标签的字符串语句会变成指令，代码语义就会悄然改变，因此不修复。源码先向上找到"最近的、非LabeledStatement的祖先"：

let ancestor = node.parent; while (ancestor.type === "LabeledStatement") { ancestor = ancestor.parent; }

当该祖先是Program（程序顶层），或是函数体（BlockStatement且父节点是函数）时，再检查语句体是否为字符串字面量或静态模板字符串：

if ( body.type === "ExpressionStatement" && ((body.expression.type === "Literal" && typeof body.expression.value === "string") || astUtils.isStaticTemplateLiteral(body.expression)) ) { return false; // potential directive }

测试中的A: "use strict"、A: ("use strict")、A: \use strict`等用例（[tests/lib/rules/no-unused-labels.js](https://link.gitcode.com/i/170eead097ec0e95fced3ad0247f59e8)）均验证了这一点。其中带括号和模板字符串的情况体现了规则的**前瞻性**：尽管当前代码不会形成指令，但其他规则的修复（如去掉括号、将模板字符串转为普通字符串）可能随后让语句变成指令，因此同样不修复。而if (foo) { bar: 'baz' }这类位于普通代码块内的情况不受影响，可以正常修复为if (foo) { 'baz' }`。

条件三：修复不能引入 ASI 陷阱

这是最容易被忽视的一个边界。JavaScript 存在自动分号插入（ASI）机制，删除标签后，上一行的语句可能和标签体语句被解析为同一个表达式。源码用两个正则来识别这种危险：

const SAFE_TOKENS_BEFORE = /^[:;{]$/u; const UNSAFE_FIRST_CHARS = /^[([\-+/`]/u; const tokenBefore = sourceCode.getTokenBefore(node); const firstBodyToken = sourceCode.getFirstToken(node.body);

如果标签前的 token 不是:、;、{之一，同时语句体首个 token 以(、[、-、+、/、`开头，就不修复。例如测试中的foo()\nA: [1, 2, 3].forEach(x => x)若不修复会被解析成foo()[1,2,3].forEach(...)；而foo();\nA: [1, 2, 3].forEach(x => x)因前一行以;结尾可以安全修复（tests/lib/rules/no-unused-labels.js）。

多重标签的修复行为

对于A: B: 'foo'这种连续嵌套的标签，每次修复只删除最外层的一个标签（A:），输出为B: 'foo'；多个标签需要多轮--fix才能全部清除。测试中A: B: C: D: 'foo'单次修复输出为B: D: 'foo'，注释明确写着"第二次修复后变成D: 'foo'"（tests/lib/rules/no-unused-labels.js），这一点在批量修复时值得留意。

Options：无选项

该规则不提供任何选项（schema: []）。它只有开与关、以及严重级别（"off"/"warn"/"error"）的区别，没有类似"允许指定白名单标签名"之类的配置项。如果你的场景确实需要保留某些特定标签，只能通过关闭规则或在该行上方添加禁用注释（如// eslint-disable-line no-unused-labels）来处理。

配置方式

无论使用传统的 eslintrc 还是 flat config，都可以按以下方式启用或调整该规则：

eslintrc 风格（.eslintrc.json）：

{ "rules": { "no-unused-labels": "error" } }

flat config 风格（eslint.config.js）：

export default [ { rules: { "no-unused-labels": "error", }, }, ];

由于该规则recommended: true，只要配置中扩展了eslint:recommended（eslintrc 的"extends": ["eslint:recommended"]，或 flat config 的import js from "@eslint/js"; ... js.configs.recommended），它就会默认以"error"级别生效，无需重复声明。

与相关规则的配合

规则文档的 frontmatter 声明了三个相关规则（见 docs/src/rules/no-unused-labels.md），它们从不同角度管理标签的使用，建议按需组合：

• no-extra-label：禁止不必要的标签（即标签只被一个break/continue引用，且没有嵌套循环时，标签属于多余）；
• no-labels：全面禁止标签语句，适用于希望完全禁用标签语法的团队；
• no-label-var：禁止标签名与变量名相同，消除命名歧义。

三者与no-unused-labels的关注点互补：no-unused-labels管"标签有没有被用"，no-extra-label管"标签有没有必要"，no-label-var管"标签名是否与变量冲突"，no-labels则是一刀切的禁用。你可以在规则文档页面通过 related rules 链接跳转对比各自的示例。

When Not To Use It

如果你不希望在代码中收到"未使用标签"的提醒——例如你的代码库确实存在一些"有意识地保留、留作文档性标记"的标签——那么关闭该规则是安全的：

{ "rules": { "no-unused-labels": "off" } }

不过需要提醒的是：由于该规则属于eslint:recommended推荐集，关闭它意味着偏离推荐基线，建议在团队配置中明确注释说明理由，并确认没有更好的替代方案（例如直接删除标签或改用注释表达意图）。

小结

no-unused-labels是一个实现精巧、边界严谨的"建议"类规则：它借助作用域栈精确追踪每个标签是否被break/continue引用，自动修复时又细心地避开了注释丢失、指令语义变化和 ASI 解析陷阱三类危险场景。对于日常开发，配合eslint:recommended即可零成本获得这一保护；若需深入理解其行为边界，lib/rules/no-unused-labels.js 的isFixable函数与 tests/lib/rules/no-unused-labels.js 的 200 余行测试用例是最佳参考素材。

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