ESLint no-bitwise 规则全解析：禁止位运算符，从误写陷阱到 `allow` / `int32Hint` 配置实战

ESLint no-bitwise 规则全解析：禁止位运算符，从误写陷阱到allow/int32Hint配置实战

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

本篇文章以 ESLint 官方内置规则no-bitwise为核心，讲解它为什么要把 JavaScript 中的位运算符列为检查对象，如何在.eslintrc或扁平化eslint.config.js中启用并配置allow与int32Hint选项，并结合当前仓库 lib/rules/no-bitwise.js 的源码实现与 tests/lib/rules/no-bitwise.js 的测试用例，深入剖析该规则的检测原理、算子白名单机制与 int32 类型转换豁免逻辑。读完本文，你将能熟练启用、调优并理解这一规则，避免团队代码中出现隐晦的位运算 bug。

为什么需要禁用位运算符

JavaScript 中的位运算符在日常业务代码里出现频率极低，但&、|与逻辑运算符&&、||在视觉上高度相似，常常是手误输入的结果，例如：

const x = y | z;

本意可能是逻辑或y || z，结果写成了按位或y | z。这类错误很难通过阅读发现，却会产生与预期完全不同的运行时行为。正因为如此，no-bitwise规则被设计为"默认建议禁用位运算符"，其官方定位是suggestion类型规则（见 docs/src/rules/no-bitwise.md 的 frontmatter 与 conf/rule-type-list.json 中的规则分类）。

需要注意的是，该规则在官方推荐配置中默认不开启（recommended: false），属于按项目需要自行启用的建议型规则。这一点可以从 docs/src/_data/rules_meta.json 中的元数据得到确认。

规则检测范围：覆盖全部位运算符及其复合赋值形式

从源码 lib/rules/no-bitwise.js 可以看到，规则内部定义了一张完整的位运算符清单：

const BITWISE_OPERATORS = [ "^", "|", "&", "<<", ">>", ">>>", "^=", "|=", "&=", "<<=", ">>=", ">>>=", "~", ];

这张清单同时用于两处：一是作为默认的违规判定依据，二是约束allow选项的可选枚举值（见 lib/rules/no-bitwise.js 中的 schema 定义，allow数组的每一项必须是上述枚举之一且不可重复）。

从 AST（抽象语法树）的节点类型看，这些算子分属三类表达式节点，规则在create()中对它们统一挂载了检查器（见 lib/rules/no-bitwise.js）：

• AssignmentExpression：捕获^=、|=、&=、<<=、>>=、>>>=等复合赋值；
• BinaryExpression：捕获^、|、&、<<、>>、>>>等双目运算；
• UnaryExpression：捕获按位取反~。

也就是说，凡是清单内出现的算子，无论以二元运算、一元运算还是复合赋值形式出现，都会被该规则标记。

错误示例

以下代码均会触发no-bitwise报错（示例源自 docs/src/rules/no-bitwise.md）：

/*eslint no-bitwise: "error"*/ let x = y | z; const x1 = y & z; const x2 = y ^ z; const x3 = ~ z; const x4 = y << z; const x5 = y >> z; const x6 = y >>> z; x |= y; x &= y; x ^= y; x <<= y; x >>= y; x >>>= y;

对应的报错信息由messages.unexpected定义（见 lib/rules/no-bitwise.js）：

Unexpected use of '{{operator}}'.

其中{{operator}}会被替换为实际命中的算子字符，例如Unexpected use of '|'.。在 tests/lib/rules/no-bitwise.js 的 invalid 用例中，每一种算子（^、|、&、<<、>>、>>>、~、^=、|=、&=、<<=、>>=、>>>=，以及未开启豁免时的a|0）都配有断言，验证其确实抛出unexpected消息。

正确示例

非位运算的逻辑运算、比较运算与普通赋值不会被误报（示例源自 docs/src/rules/no-bitwise.md）：

/*eslint no-bitwise: "error"*/ let x = y || z; const x1 = y && z; const x2 = y > z; const x3 = y < z; x += y;

同样，在 tests/lib/rules/no-bitwise.js 的 valid 用例中还覆盖了a + b、!a、a && b、a || b、a += b以及 ES2021 的&&=、||=、??=（逻辑赋值运算符，不属于位运算范畴）。

选项配置：allow与int32Hint

规则接受一个对象选项（见 docs/src/rules/no-bitwise.md 的 Options 章节），包含两个字段：

两个字段的默认值在规则元数据defaultOptions中直接给出（见 lib/rules/no-bitwise.js 与 docs/src/_data/rules_meta.json），因此即使不传任何选项，规则也能安全运行。

allow：为特定算子开白名单

当项目确有合理使用某个位运算符的场景时，可用allow显式放行。例如允许使用~配合indexOf判断元素是否存在：

/*eslint no-bitwise: ["error", { "allow": ["~"] }] */ ~[1,2,3].indexOf(1) === -1;

上述代码符合规则、不再报错（示例源自 docs/src/rules/no-bitwise.md 的 allow 章节）。对应地，测试用例 tests/lib/rules/no-bitwise.js 验证了{ allow: ["~"] }放行~[1, 2, 3].indexOf(1)，以及{ allow: ["~", "<<"] }放行~1<<2 === -8的组合场景。

allow可以同时列出多个算子，例如{ "allow": ["~", "|"] }。其判定逻辑在源码 lib/rules/no-bitwise.js 的allowedOperator()函数中：只要节点的operator出现在allowed数组中即视为例外，不再报告。

int32Hint：放行|0整数转换惯用法

在某些性能敏感代码中，开发者常使用a|0将浮点数截断为 32 位整数（ToInt32转换）。开启int32Hint: true后，这种| 0惯用法会被放行：

/*eslint no-bitwise: ["error", { "int32Hint": true }] */ const b = a|0;

上述代码符合规则、不再报错（示例源自 docs/src/rules/no-bitwise.md 的 int32Hint 章节）。

其实现细节非常严格，见源码 lib/rules/no-bitwise.js 的isInt32Hint()函数，必须同时满足四个条件才视为豁免：

1. int32Hint选项为true；
2. 算子必须是|（按位或）；
3. 右操作数必须是Literal（字面量节点）；
4. 右操作数的值严格等于0。

也就是说，a|0被放行，而a|1、a|b依然会报错。测试用例 tests/lib/rules/no-bitwise.js 验证了{ int32Hint: true }放行a|0，而未开启时a|0在 invalid 用例中会被报告。

判定流程与底层原理

综合以上实现，规则对每个命中的 AST 节点的判定顺序是（见 lib/rules/no-bitwise.js 的checkNodeForBitwiseOperator()）：

1. 节点算子是否在BITWISE_OPERATORS清单中（hasBitwiseOperator，lib/rules/no-bitwise.js）——不在则直接放行；
2. 节点算子是否在allow白名单中（allowedOperator）——在则放行；
3. 节点是否满足int32Hint豁免条件（isInt32Hint）——满足则放行；
4. 以上均不满足时调用report()（lib/rules/no-bitwise.js）通过context.report抛出Unexpected use of '{{operator}}'.。

这种"清单命中 → 白名单 → 特例豁免 → 报告"的检查顺序，让规则在保持默认严格的同时，通过配置获得精准的弹性。规则并未实现自动修复（meta 中没有fixable字段），因为位运算符改写为逻辑运算符通常需要人工判断语义，无法安全自动修复。

在配置文件中启用与调优

由于recommended配置不包含该规则，需要手动在配置中开启。在传统的.eslintrc风格配置中：

{ "rules": { "no-bitwise": ["error", { "allow": ["~"], "int32Hint": true }] } }

在扁平化配置（flat config，即eslint.config.js）中：

export default [ { rules: { "no-bitwise": ["error", { "allow": ["~"], "int32Hint": true }] } } ];

严格模式请直接使用"no-bitwise": "error"或"no-bitwise": ["error", {}]；需要在代码注释中临时豁免单行时，可使用行内禁用注释，例如：

// eslint-disable-next-line no-bitwise const flags = a | b;

规则入口与文档映射

no-bitwise规则通过 lib/rules/index.js 以惰性加载方式注册（"no-bitwise": () => require("./no-bitwise")），与 docs/src/rules/no-bitwise.md 一一对应。其规则类型suggestion、默认选项与描述信息同步维护在 docs/src/_data/rules_meta.json 中，供文档站点渲染与工具链消费。测试用例 tests/lib/rules/no-bitwise.js 完整覆盖了全部算子、选项组合与边界情况，是理解该规则行为最直接的参考。

总结

no-bitwise规则通过一张覆盖 13 种位运算符（含 6 种复合赋值与~）的算子清单，配合AssignmentExpression、BinaryExpression、UnaryExpression三类节点检查，帮助团队拦截 JS 中绝大多数误写的位运算；allow白名单与int32Hint豁免则分别解决了"确有合理用途"与"|0整数转换惯用法"两大真实场景。理解其判定顺序与豁免条件后，你就能在代码质量与必要性能技巧之间做出有依据的取舍。

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