ESLint 的 no-magic-numbers 规则仅做静态检查，不支持自动替换为具名常量，因其设计为只读分析；真正实现语义化重写的需在构建阶段通过 Babel 插件等可写工具操作 AST，并辅以上下文判断、作用域管理与可维护性设计。
为什么 eslint-plugin-no-magic-numbers 不够用
它只能报错或警告，无法自动替换成具名常量。你在打包阶段需要的是“修改 AST 并写回源码”，不是静态检查。真正起作用的环节在构建流水线里——比如 webpack 的 loader 阶段，或 esbuild / swc 的 transform 插件中。
常见错误现象：eslint --fix 对魔法数字完全无反应；自定义 babel 插件跑完没改任何文件；重写后变量名冲突导致运行时 ReferenceError。
- 必须区分“只读分析”和“可写重写”：ESLint 是只读的，
@babel/core的transformSync才能生成新代码 - 语义重写不能只靠正则：比如
if (x === 42)和const MAX_RETRY = 42中的42含义完全不同，需结合上下文（父节点类型、作用域、注释）判断 - 重命名必须全局唯一且可追溯：建议生成形如
__MAGIC_0x2a_v1的临时标识符，再统一映射到最终常量名（如HTTP_STATUS_OK），避免手动维护字典
用 Babel 插件在 webpack 中注入重写逻辑
这是目前最可控的方式：把转换逻辑塞进 babel-loader 的 plugins 数组，确保它在所有其他插件之前执行（防止已被转译的代码逃过检测）。
关键点在于 AST 节点识别和安全替换：
- 只处理
NumberLiteral节点，但跳过出现在ObjectProperty键、ArrayExpression索引、CallExpression参数中的高频无意义数字（如[1,2,3]中的1） - 用
path.scope.generateUidIdentifier创建新标识符，再通过path.replaceWith替换原节点 - 必须调用
path.scope.crawl()更新作用域，否则后续引用会找不到声明 - 在插件 exit 钩子中统一收集所有新声明，用
path.unshiftContainer插入到文件顶部（注意避免重复插入）
示例片段（简化版）：
module.exports = function (babel) {
const { types: t } = babel;
return {
name: 'magic-number-rewriter',
visitor: {
NumberLiteral(path) {
const value = path.node.value;
if (value === 0 || value === 1 || value > 1000) return; // 过滤掉明显非语义数字
const id = path.scope.generateUidIdentifier(`MAGIC_${value}`);
path.replaceWith(t.identifier(id.name));
// 记录待声明：{ id, value, loc: path.node.loc }
}
}
};
};如何让重写结果可维护、不破坏调试体验
直接替换成 HTTP_STATUS_OK 看似干净，但会导致 source map 错位、断点失效、diff 难以追踪。更务实的做法是分两层：保留原始数字 + 注释说明 + 可选的常量导入。
- 重写后生成形如
/* MAGIC: 42 → HTTP_STATUS_OK */ 42，既不影响运行，又提供语义提示 - 如果项目已定义
constants.ts，可自动追加import { HTTP_STATUS_OK } from './constants';（需检测是否已存在） - 对
console.log(42)这类调试语句，默认不重写；可通过注释开关控制：// @rewrite-magic或// @no-rewrite - 输出一份
magic-rewrite-report.json，记录每个数字被替换的位置、推导出的含义、置信度，供人工复核
esbuild 插件方案的取舍与限制
如果你用 esbuild，可以用 onLoad 或 onResolve 钩子做类似事，但它不暴露完整 AST，只能基于字符串或简易语法树操作，精度远低于 Babel。
典型问题：
-
esbuild的transform不支持跨文件作用域分析，无法判断42在当前模块是否已被定义为常量 - 无法安全处理模板字面量中的数字：
`timeout ${5000}ms`会被当成字符串，而非NumberLiteral - source map 映射容易断裂，尤其当重写引入新行或注释时
- 性能虽快，但一旦出错难以调试——没有
path.traverse或path.debug()这类工具
结论：仅适合简单规则（如“所有孤立的 200 替换为 OK_CODE”），不适合语义化推导。
真正难的不是怎么写脚本，而是怎么定义“哪些数字值得重写”以及“重写成什么”。这需要结合团队约定、领域知识和少量人工标注，自动化只是放大器，不是决策者。
