no-magic-numbers

禁止幻数

'魔法数字’是指在代码中多次出现但没有明确意义的数字。它们最好被替换为具名常量。

const now = Date.now(),
    inOneHour = now + (60 * 60 * 1000);
1
2

规则详情

🌐 Rule Details

no-magic-numbers 规则旨在通过确保将特殊数字声明为常量，以使其含义明确，从而提高代码的可读性并便于重构。

🌐 The no-magic-numbers rule aims to make code more readable and refactoring easier by ensuring that special numbers are declared as constants to make their meaning explicit.

此规则的错误代码示例：

🌐 Examples of incorrect code for this rule:

/*eslint no-magic-numbers: "error"*/

const dutyFreePrice = 100,
    finalPrice = dutyFreePrice + (dutyFreePrice * 0.25);
1
2
3
4

/*eslint no-magic-numbers: "error"*/

const data = ['foo', 'bar', 'baz'];

const dataLast = data[2];
1
2
3
4
5

/*eslint no-magic-numbers: "error"*/

let SECONDS;

SECONDS = 60;
1
2
3
4
5

符合此规则的正确代码示例：

🌐 Examples of correct code for this rule:

/*eslint no-magic-numbers: "error"*/

const TAX = 0.25;

const dutyFreePrice = 100,
    finalPrice = dutyFreePrice + (dutyFreePrice * TAX);
1
2
3
4
5
6

选项

🌐 Options

ignore

要忽略的数字数组。默认设置为 []。 如果提供，它必须是 Array。

🌐 An array of numbers to ignore. It’s set to [] by default. If provided, it must be an Array.

该数组可以包含 number 和 string 类型的值。如果它是字符串，则文本必须被解析为 bigint 字面值（例如，"100n"）。

🌐 The array can contain values of number and string types. If it’s a string, the text must be parsed as bigint literal (e.g., "100n").

示例 { "ignore": [1] } 选项的正确代码示例：

🌐 Examples of correct code for the sample { "ignore": [1] } option:

/*eslint no-magic-numbers: ["error", { "ignore": [1] }]*/

const data = ['foo', 'bar', 'baz'];
const dataLast = data.length && data[data.length - 1];
1
2
3
4

示例 { "ignore": ["1n"] } 选项的正确代码示例：

🌐 Examples of correct code for the sample { "ignore": ["1n"] } option:

/*eslint no-magic-numbers: ["error", { "ignore": ["1n"] }]*/

foo(1n);
1
2
3

ignoreArrayIndexes

一个布尔值，用于指定在数组索引上下文中使用的数字（例如 data[2]）是否被认为是可以的。默认值为 false。

🌐 A boolean to specify if numbers used in the context of array indexes (e.g., data[2]) are considered okay. false by default.

此选项仅允许有效的数组索引：将被强制转换为 "0"、"1"、"2" … "4294967294" 之一的数字。

🌐 This option allows only valid array indexes: numbers that will be coerced to one of "0", "1", "2" … "4294967294".

数组是对象，因此它们可以有属性名称，例如 "-1" 或 "2.5"。然而，这些只是“普通”的对象属性，并不代表数组元素。它们不会影响数组的 length，并且会被像 .map 或 .forEach 这样的数组方法忽略。

🌐 Arrays are objects, so they can have property names such as "-1" or "2.5". However, those are just “normal” object properties that don’t represent array elements. They don’t influence the array’s length, and they are ignored by array methods like .map or .forEach.

此外，由于最大数组长度为 2³² - 1，所有大于 2³² - 2 的值也只是普通属性名称，因此不被视为数组索引。

适用于 { "ignoreArrayIndexes": true } 选项的正确代码示例：

🌐 Examples of correct code for the { "ignoreArrayIndexes": true } option:

/*eslint no-magic-numbers: ["error", { "ignoreArrayIndexes": true }]*/

const item = data[2];

data[100] = a;

f(data[0]);

a = data[-0]; // same as data[0], -0 will be coerced to "0"
a = data[+1]; // same as data[1], +1 will be coerced to "1"

a = data[0xAB];

a = data[5.6e1];

a = data[10n]; // same as data[10], 10n will be coerced to "10"

a = data[4294967294]; // max array index
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

针对 { "ignoreArrayIndexes": true } 选项的错误代码示例：

🌐 Examples of incorrect code for the { "ignoreArrayIndexes": true } option:

/*eslint no-magic-numbers: ["error", { "ignoreArrayIndexes": true }]*/

f(2); // not used as array index

a = data[-1];

a = data[2.5];

a = data[5.67e1];

a = data[-10n];

a = data[4294967295]; // above the max array index

a = data[1e500]; // same as data["Infinity"]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

ignoreDefaultValues

一个布尔值，用于指定在默认值分配中使用的数字是否被认为是可以的。默认值为 false。

🌐 A boolean to specify if numbers used in default value assignments are considered okay. false by default.

适用于 { "ignoreDefaultValues": true } 选项的正确代码示例：

🌐 Examples of correct code for the { "ignoreDefaultValues": true } option:

/*eslint no-magic-numbers: ["error", { "ignoreDefaultValues": true }]*/

const { tax = 0.25 } = accountancy;

function mapParallel(concurrency = 3) { /***/ }
1
2
3
4
5

/*eslint no-magic-numbers: ["error", { "ignoreDefaultValues": true }]*/

let head;
[head = 100] = []
1
2
3
4

ignoreClassFieldInitialValues

一个布尔值，用于指定作为类字段初始值的数字是否被认为是可以的。默认值为 false。

🌐 A boolean to specify if numbers used as initial values of class fields are considered okay. false by default.

适用于 { "ignoreClassFieldInitialValues": true } 选项的正确代码示例：

🌐 Examples of correct code for the { "ignoreClassFieldInitialValues": true } option:

/*eslint no-magic-numbers: ["error", { "ignoreClassFieldInitialValues": true }]*/

class C {
    foo = 2;
    bar = -3;
    tux = +1;
    #baz = 4;
    static qux = 5;
}
1
2
3
4
5
6
7
8
9

针对 { "ignoreClassFieldInitialValues": true } 选项的错误代码示例：

🌐 Examples of incorrect code for the { "ignoreClassFieldInitialValues": true } option:

/*eslint no-magic-numbers: ["error", { "ignoreClassFieldInitialValues": true }]*/

class C {
    foo = 2 + 3;
}

class D {
    2;
}
1
2
3
4
5
6
7
8
9

enforceConst

一个布尔值，用于指定是否在数字的变量声明中检查 const 关键字。默认值为 false。

🌐 A boolean to specify if we should check for the const keyword in variable declaration of numbers. false by default.

针对 { "enforceConst": true } 选项的错误代码示例：

🌐 Examples of incorrect code for the { "enforceConst": true } option:

/*eslint no-magic-numbers: ["error", { "enforceConst": true }]*/

let TAX = 0.25;

let dutyFreePrice = 100,
    finalPrice = dutyFreePrice + (dutyFreePrice * TAX);
1
2
3
4
5
6

detectObjects

一个布尔值，用于指定在设置对象属性时是否应该检测数字。例如，默认值为 false。

🌐 A boolean to specify if we should detect numbers when setting object properties for example. false by default.

针对 { "detectObjects": true } 选项的错误代码示例：

🌐 Examples of incorrect code for the { "detectObjects": true } option:

/*eslint no-magic-numbers: ["error", { "detectObjects": true }]*/

const magic = {
  tax: 0.25
};

const dutyFreePrice = 100,
    finalPrice = dutyFreePrice + (dutyFreePrice * magic.tax);
1
2
3
4
5
6
7
8

适用于 { "detectObjects": true } 选项的正确代码示例：

🌐 Examples of correct code for the { "detectObjects": true } option:

/*eslint no-magic-numbers: ["error", { "detectObjects": true }]*/

const TAX = 0.25;

const magic = {
  tax: TAX
};

const dutyFreePrice = 100,
    finalPrice = dutyFreePrice + (dutyFreePrice * magic.tax);
1
2
3
4
5
6
7
8
9
10

ignoreEnums（仅限 TypeScript）

🌐 ignoreEnums (TypeScript only)

在 TypeScript 中使用的枚举是否被认为是可以的。默认情况下为 false。

🌐 Whether enums used in TypeScript are considered okay. false by default.

针对 { "ignoreEnums": false } 选项的错误代码示例：

🌐 Examples of incorrect code for the { "ignoreEnums": false } option:

/*eslint no-magic-numbers: ["error", { "ignoreEnums": false }]*/

enum foo {
  SECOND = 1000,
}
1
2
3
4
5

适用于 { "ignoreEnums": true } 选项的正确代码示例：

🌐 Examples of correct code for the { "ignoreEnums": true } option:

/*eslint no-magic-numbers: ["error", { "ignoreEnums": true }]*/

enum foo {
  SECOND = 1000,
}
1
2
3
4
5

ignoreNumericLiteralTypes（仅限 TypeScript）

🌐 ignoreNumericLiteralTypes (TypeScript only)

在 TypeScript 数字字面量类型中使用的数字是否被视为可以。默认情况下为 false。

🌐 Whether numbers used in TypeScript numeric literal types are considered okay. false by default.

针对 { "ignoreNumericLiteralTypes": false } 选项的错误代码示例：

🌐 Examples of incorrect code for the { "ignoreNumericLiteralTypes": false } option:

/*eslint no-magic-numbers: ["error", { "ignoreNumericLiteralTypes": false }]*/

type Foo = 1 | 2 | 3;
1
2
3

适用于 { "ignoreNumericLiteralTypes": true } 选项的正确代码示例：

🌐 Examples of correct code for the { "ignoreNumericLiteralTypes": true } option:

/*eslint no-magic-numbers: ["error", { "ignoreNumericLiteralTypes": true }]*/

type Foo = 1 | 2 | 3;
1
2
3

ignoreReadonlyClassProperties（仅限 TypeScript）

🌐 ignoreReadonlyClassProperties (TypeScript only)

在 TypeScript 只读类属性中使用数字是否被认为是可以的。默认情况下为 false。

🌐 Whether numbers used in TypeScript readonly class properties are considered okay. false by default.

针对 { "ignoreReadonlyClassProperties": false } 选项的错误代码示例：

🌐 Examples of incorrect code for the { "ignoreReadonlyClassProperties": false } option:

/*eslint no-magic-numbers: ["error", { "ignoreReadonlyClassProperties": false }]*/

class Foo {
  readonly A = 1;
  readonly B = 2;
  public static readonly C = 1;
  static readonly D = 1;
}
1
2
3
4
5
6
7
8

适用于 { "ignoreReadonlyClassProperties": true } 选项的正确代码示例：

🌐 Examples of correct code for the { "ignoreReadonlyClassProperties": true } option:

/*eslint no-magic-numbers: ["error", { "ignoreReadonlyClassProperties": true }]*/

class Foo {
  readonly A = 1;
  readonly B = 2;
  public static readonly C = 1;
  static readonly D = 1;
}
1
2
3
4
5
6
7
8

ignoreTypeIndexes（仅限 TypeScript）

🌐 ignoreTypeIndexes (TypeScript only)

用于索引类型的数字是否可以。默认是 false。

🌐 Whether numbers used to index types are okay. false by default.

针对 { "ignoreTypeIndexes": false } 选项的错误代码示例：

🌐 Examples of incorrect code for the { "ignoreTypeIndexes": false } option:

/*eslint no-magic-numbers: ["error", { "ignoreTypeIndexes": false }]*/

type Foo = Bar[0];
type Baz = Parameters<Foo>[2];
1
2
3
4

适用于 { "ignoreTypeIndexes": true } 选项的正确代码示例：

🌐 Examples of correct code for the { "ignoreTypeIndexes": true } option:

/*eslint no-magic-numbers: ["error", { "ignoreTypeIndexes": true }]*/

type Foo = Bar[0];
type Baz = Parameters<Foo>[2];
1
2
3
4

版本

此规则是在 ESLint v1.7.0 中引入。

资源

• 规则源码
• 测试源码