Node.js API

While ESLint is designed to be run on the command line, it’s possible to use ESLint programmatically through the Node.js API. The purpose of the Node.js API is to allow plugin and tool authors to use the ESLint functionality directly, without going through the command line interface.

ESLint 被设计为在命令行中运行,所以通过 Node.js API 使用 ESLint 编程是可能的。Node.js API 的目的是使插件和工具的作者可以直接使用 ESLint 的功能,而不需要通过命令行接口。

Note: Use undocumented parts of the API at your own risk. Only those parts that are specifically mentioned in this document are approved for use and will remain stable and reliable. Anything left undocumented is unstable and may change or be removed at any point.

注意:使用文档中没有的 API 的风险需自己承担。只有文档中声明的部分是赞成使用且可保持稳定可靠。文档中未声明的部分是不稳定的且可能随时被移除。

SourceCode

The SourceCode type represents the parsed source code that ESLint executes on. It’s used internally in ESLint and is also available so that already-parsed code can be used. You can create a new instance of SourceCode by passing in the text string representing the code and an abstract syntax tree (AST) in ESTree format (including location information, range information, comments, and tokens):

SourceCode 类型表示 ESLint 执行分析的源代码。它在 ESLint 内部使用,对于已经解析的代码也是可用的。你可以以 ESTree 的形式传递表示代码和抽象语法树 (AST) 的文本字符串创建SourceCode的新实例。(包含本地信息,范围信息,注释和标志):

var SourceCode = require("eslint").SourceCode;

var code = new SourceCode("var foo = bar;", ast);

The SourceCode constructor throws an error if the AST is missing any of the required information.

缺少任何必要的信息 SourceCode 构造器都会抛出错误。

The SourceCode constructor strips Unicode BOM. Please note the AST also should be parsed from stripped text.

SourceCode 构造函数剥离 Unicode BOM。请注意,AST 也应该从剥离后的文本进行解析。

var SourceCode = require("eslint").SourceCode;

var code = new SourceCode("\uFEFFvar foo = bar;", ast);

assert(code.hasBOM === true);
assert(code.text === "var foo = bar;");

splitLines()

This is a static function on SourceCode that is used to split the source code text into an array of lines.

这是 SourceCode 的一个静态函数,用来将源码文本分割成一个行的数组。

var SourceCode = require("eslint").SourceCode;

var code = "var a = 1;\nvar b = 2;"

// split code into an array
var codeLines = SourceCode.splitLines(code);

/*
    Value of codeLines will be
    [
        "var a = 1;",
        "var b = 2;"
    ]
 */

Linter

The Linter object does the actual evaluation of the JavaScript code. It doesn’t do any filesystem operations, it simply parses and reports on the code. In particular, the Linter object does not process configuration objects or files. You can retrieve instances of Linter like this:

Linter 对象对 JavaScript 代码进行评估。它不会对文件系统进行操作,它只会简单地解析和报告代码。特别是,Linter 对象不会处理配置对象或文件。你可以这样取得 Linter 实例:

var Linter = require("eslint").Linter;
var linter = new Linter();

The most important method on Linter is verify(), which initiates linting of the given text. This method accepts four arguments:

Linter 最重要的方法为 verify(),它对给出的文本进行检测。这个方法接受4个参数:

You can call verify() like this:

你可以这样调用 verify()

var Linter = require("eslint").Linter;
var linter = new Linter();

var messages = linter.verify("var foo;", {
    rules: {
        semi: 2
    }
}, { filename: "foo.js" });

// or using SourceCode

var linter = require("eslint").linter,
    SourceCode = require("eslint").SourceCode;

var code = new SourceCode("var foo = bar;", ast);

var messages = linter.verify(code, {
    rules: {
        semi: 2
    }
}, { filename: "foo.js" });

The verify() method returns an array of objects containing information about the linting warnings and errors. Here’s an example:

verify() 方法返回一个包含警告和错误的对象的数组。下面是个例子:

{
    fatal: false,
    ruleId: "semi",
    severity: 2,
    line: 1,
    column: 23,
    message: "Expected a semicolon.",
    fix: {
        range: [1, 15],
        text: ";"
    }
}

The information available for each linting message is:

这些信息对所有的检测信息都是可用的:

Please note: the source property will be removed from the linting messages in an upcoming breaking release. If you depend on this property, you can still use the getSourceCode method described below to get the line of code for each message.

请注意:source 属性将在未来的大版本中从检测消息中移除。如果你依赖这个属性,你仍可以使用下面描述的 getSourceCode 方法来获得每行代码的每条消息。

You can also get an instance of the SourceCode object used inside of linter by using the getSourceCode() method:

你也可以通过 getSourceCode() 方法获取一个在 linter 内部使用 SourceCode 的实例:

var Linter = require("eslint").Linter;
var linter = new Linter();

var messages = linter.verify("var foo = bar;", {
    rules: {
        semi: 2
    }
}, { filename: "foo.js" });

var code = linter.getSourceCode();

console.log(code.text);     // "var foo = bar;"

In this way, you can retrieve the text and AST used for the last run of linter.verify().

通过这种方式,你可以获取用作 linter.verify() 最终返回值的文本和 AST。

verifyAndFix()

This method is similar to verify() except that it also runs autofixing logic, similar to the --fix flag on the command line. The result object will contain the autofixed code, along with any remaining linting messages for the code that were not autofixed.

该方法类似于 verify(),它还有运行自动修复的逻辑,类似于命令行中的 --fix 标记。返回的结果对象将包含自动修复后的代码,和其他没有自动修复过的代码的检测消息。

var Linter = require("eslint").Linter;
var linter = new Linter();

var messages = linter.verifyAndFix("var foo", {
    rules: {
        semi: 2
    }
}, { filename: "foo.js" });

Output object from this method:

该方法输出的对象为:

{
    fixed: true,
    text: "var foo;",
    messages: []
}

The information available is:

字段的含义为:

linter

The eslint.linter object (deprecated) is an instance of the Linter class as defined above. eslint.linter exists for backwards compatibility, but we do not recommend using it because any mutations to it are shared among every module that uses eslint. Instead, please create your own instance of eslint.Linter.

eslint.linter 对象(已弃用)是 Linter 类(如上定义)的一个实例。eslint.linter 是为了向后兼容,但我们不推荐使用它,因为对它的任何改变将影响所有使用 eslint 的模块。相反,请创建你自己的 eslint.Linter 实例。

var linter = require("eslint").linter;

var messages = linter.verify("var foo;", {
    rules: {
        semi: 2
    }
}, { filename: "foo.js" });

Note: This API is deprecated as of 4.0.0.

注意:该 API 已在 4.0.0 版中被弃用。

CLIEngine

The primary Node.js API is CLIEngine, which is the underlying utility that runs the ESLint command line interface. This object will read the filesystem for configuration and file information but will not output any results. Instead, it allows you direct access to the important information so you can deal with the output yourself.

主要的 Node.js API 是 CLIEngine,它是运行在 ESLint 命令行接口的基础实用工具。该对象会读取文件系统获得配置和文件信息,但不会输出任何结果。相反,它允许你直接访问重要信息,这样你就可以自己处理输出结果。

You can get a reference to the CLIEngine by doing the following:

你可以通过下面的方式获得 CLIEngine 的引用:

var CLIEngine = require("eslint").CLIEngine;

The CLIEngine is a constructor, and you can create a new instance by passing in the options you want to use. The available options are:

CLIEngine 是一个构造器,你可以通过传递想用的选项创建一个实例。下面是可以的选项:

For example:

例如:

var CLIEngine = require("eslint").CLIEngine;

var cli = new CLIEngine({
    envs: ["browser", "mocha"],
    useEslintrc: false,
    rules: {
        semi: 2
    }
});

In this code, a new CLIEngine instance is created that sets two environments, "browser" and "mocha", disables loading of .eslintrc and package.json files, and enables the semi rule as an error. You can then call methods on cli and these options will be used to perform the correct action.

在上面的代码中,创建了一个 CLIEngine 实例,设置两种环境,"browser""mocha",禁止加载 .eslintrcpackage.json 文件,开启 semi 规则作为错误。你可以在 cli 调用,然后这些选项将被应用并正确运行。

executeOnFiles()

If you want to lint one or more files, use the executeOnFiles() method. This method accepts a single argument, which is an array of files and/or directories to traverse for files. You can pass the same values as you would using the ESLint command line interface, such as "." to search all JavaScript files in the current directory. Here’s an example:

如果你检测一个或多个文件,就使用 executeOnFiles() 方法。这个方法接收一个参数,类型为文件的数组且/或要遍历文件的目录。你也可以在 ESLint 命令行接口使用时传递相同的值,例如 . 在当前目录搜索所有的 JavaScript 文件。下面举个例子:

var CLIEngine = require("eslint").CLIEngine;

var cli = new CLIEngine({
    envs: ["browser", "mocha"],
    useEslintrc: false,
    rules: {
        semi: 2
    }
});

// lint myfile.js and all files in lib/
var report = cli.executeOnFiles(["myfile.js", "lib/"]);

The return value is an object containing the results of the linting operation. Here’s an example of a report object:

返回值是包含检测操作的结果对象。下面是报告对象的例子:

{
    results: [
        {
            filePath: "/Users/eslint/project/myfile.js",
            messages: [{
                ruleId: "semi",
                severity: 2,
                message: "Missing semicolon.",
                line: 1,
                column: 13,
                nodeType: "ExpressionStatement",
                source: "\"use strict\"", // Deprecated: see "please note" paragraph below.
                fix: { range: [12, 12], text: ";" }
            }],
            errorCount: 1,
            warningCount: 0,
            fixableErrorCount: 1,
            fixableWarningCount: 0,
            source: "\"use strict\"\n"
        }
    ],
    errorCount: 1,
    warningCount: 0,
    fixableErrorCount: 1,
    fixableWarningCount: 0
}

You can also pass fix: true when instantiating the CLIEngine in order to have it figure out what fixes can be applied.

你也可以在 CLIEngine 实例化时,传入 fix: true,以指明可以应用哪些修复。

var CLIEngine = require("eslint").CLIEngine;

var cli = new CLIEngine({
    envs: ["browser", "mocha"],
    fix: true, // difference from last example
    useEslintrc: false,
    rules: {
        semi: 2,
        quotes: [2, "double"]
    }
});

// lint myfile.js and all files in lib/
var report = cli.executeOnFiles(["myfile.js", "lib/"]);
{
    results: [
        {
            filePath: "/Users/eslint/project/myfile.js",
            messages: [
                {
                    ruleId: "semi",
                    severity: 2,
                    message: "Missing semicolon.",
                    line: 1,
                    column: 13,
                    nodeType: "ExpressionStatement",
                    source: "\"use strict\"", // Deprecated: see "please note" paragraph below.
                    fix: { range: [12, 12], text: ";" }
                },
                {
                    ruleId: "func-name-matching",
                    severity: 2,
                    message: "Function name `bar` should match variable name `foo`",
                    line: 2,
                    column: 5,
                    nodeType: "VariableDeclarator",
                    source: "var foo = function bar() {};"
                }
            ],
            errorCount: 2,
            warningCount: 0,
            fixableErrorCount: 1,
            fixableWarningCount: 0,
            output: "\"use strict\";\nvar foo = function bar() {};\nfoo();\n"
        }
    ],
    errorCount: 2,
    warningCount: 0,
    fixableErrorCount: 1,
    fixableWarningCount: 0,
}

If the operation ends with a parsing error, you will get a single message for this file, with fatal: true added as an extra property.

如果操作出现一个解析错误,你将获得一条消息,带有一个额外的属性 fatal: true

{
    results: [
        {
            filePath: "./myfile.js",
            messages: [
                {
                    ruleId: null,
                    fatal: true,
                    severity: 2,
                    source: "fucntion foo() {}",
                    message: "Parsing error: Unexpected token foo",
                    line: 1,
                    column: 10
                }
            ],
            errorCount: 1,
            warningCount: 0,
            fixableErrorCount: 0,
            fixableWarningCount: 0,
            source: "fucntion foo() {}"
        }
    ],
    errorCount: 1,
    warningCount: 0,
    fixableErrorCount: 0,
    fixableWarningCount: 0,
}

The top-level report object has a results array containing all linting results for files that had warnings or errors (any files that did not produce a warning or error are omitted). Each file result includes:

报告对象的顶层是个 results 数组,包含文件的所有检查结果,有警告或错误(任何不产生讲过或错误的文件将被忽略)。每个文件结果包括:

The top-level report object also has errorCount and warningCount which give the exact number of errors and warnings respectively on all the files.

顶层报告对象也有 errorCountwarningCount,分别给出所有文件的错误和警告具体数量。

Please note: the source property will be removed from the linting messages returned in messages in an upcoming breaking release. If you depend on this property, you should now use the top-level source or output properties instead.

请注意:source 属性将在未来的大版本中从检测消息中移除。如果你依赖这个属性,你现在应该使用顶层的 sourceoutput 属性。

Once you get a report object, it’s up to you to determine how to output the results. Fixes will not be automatically applied to the files, even if you set fix: true when constructing the CLIEngine instance. To apply fixes to the files, call outputFixes.

一旦你得到了一个报告对象,由你来决定如何输出结果。修复不会自动应用到文件,即使你在创建 CLIEngine 实例时设置 fix: true。调用 outputFixes来使修复生效。

resolveFileGlobPatterns()

You can pass filesystem-style or glob patterns to ESLint and have it function properly. In order to achieve this, ESLint must resolve non-glob patterns into glob patterns before determining which files to execute on. The resolveFileGlobPatterns() methods uses the current settings from CLIEngine to resolve non-glob patterns into glob patterns. Pass an array of patterns that might be passed to the ESLint CLI and it will return an array of glob patterns that mean the same thing. Here’s an example:

你可以传递 filesystem-style 或者 glob 模式给 ESLint,以让它正常运行。为了做到这点,ESLint 必须在确定要执行的文件之前将 non-glob 模式分解为 glob 模式 。resolveFileGlobPatterns() 方法使用CLIEngine的当前设置将non-glob模式分解为glob模式。传递一个模式的数组,它可能传入到ESLint CLI ,将返回一个glob模式的数组意味着同样的事情。例如:

var CLIEngine = require("eslint").CLIEngine;

var cli = new CLIEngine({
});

// pass an array of patterns
var globPatterns = cli.resolveFileGlobPatterns(["."]);
console.log(globPatterns[i]);       // ["**/*.js"]

getConfigForFile()

If you want to retrieve a configuration object for a given file, use the getConfigForFile() method. This method accepts one argument, a file path, and returns an object represented the calculated configuration of the file. Here’s an example:

如果你想为给定的文件获得一个配置对象,使用 getConfigForFile() 方法。这个方法接收一个参数,为一个文件路径,并且返回代表该文件的计算配置的对象。例如:

var CLIEngine = require("eslint").CLIEngine;

var cli = new CLIEngine({
    envs: ["browser", "mocha"],
    useEslintrc: false,
    rules: {
        semi: 2
    }
});

var config = cli.getConfigForFile("myfile.js");

Once you have the configuration information, you can pass it into the linter object:

一旦你获得配置信息,可以将它传入到 linter 对象:

var CLIEngine = require("eslint").CLIEngine,
    linter = require("eslint").linter;

var cli = new CLIEngine({
    envs: ["browser", "mocha"],
    useEslintrc: false,
    rules: {
        semi: 2
    }
});

var config = cli.getConfigForFile("myfile.js");

var messages = linter.verify('var foo;', config);

executeOnText()

If you already have some text to lint, then you can use the executeOnText() method to lint that text. The linter will assume that the text is a file in the current working directory, and so will still obey any .eslintrc and .eslintignore files that may be present. Here’s an example:

如果你已经有一些文本要检测,你可以使用 executeOnText()。linter会假设这段文本为在当前工作目录下的文件,并且仍会遵守可能存在的 .eslintrc.eslintignore 。例如:

var CLIEngine = require("eslint").CLIEngine;

var cli = new CLIEngine({
    envs: ["browser", "mocha"],
    useEslintrc: false,
    rules: {
        semi: 2
    }
});

// lint the supplied text and optionally set
// a filename that is displayed in the report
var report = cli.executeOnText("var foo = 'bar';", "foo.js");

The report returned from executeOnText() is in the same format as from executeOnFiles(), but there is only ever one result in report.results.

reportexecuteOnText() 返回和从 executeOnFiles() 返回具有相同的格式, 但是在 report.results 中永远只有一个结果。

If a filename in the optional second parameter matches a file that is configured to be ignored, then this function returns no errors or warnings. To return a warning instead, call the method with true as the optional third parameter.

如果第二个可选参数的文件名匹配配置文件中被忽略的文件,该函数不会返回任何错误或经过。为了返回一个警告,调用该方法时设置第三个参数为 true。

addPlugin()

Loads a plugin from configuration object with specified name. Name can include plugin prefix (“eslint-plugin-“)

从指定名称的配置对象中加载插件,名称可以包含插件前缀(”eslint-plugin-“)

var CLIEngine = require("eslint").CLIEngine;
var cli = new CLIEngine({
    ignore: true
});
cli.addPlugin("eslint-plugin-processor", {
    processors: {
        ".txt": {
            preprocess: function(text) {
                return [text];
            },
            postprocess: function(messages) {
                return messages[0];
            }
        }
    }
});

isPathIgnored()

Checks if a given path is ignored by ESLint.

检查给定的路径是否被ESLint忽略。

var CLIEngine = require("eslint").CLIEngine;

var cli = new CLIEngine({
    ignore: true,
    ignorePath: ".customIgnoreFile"
});

var isIgnored = cli.isPathIgnored("foo/bar.js");

getFormatter()

Retrieves a formatter, which you can then use to format a report object. The argument is either the name of a built-in formatter:

获取一个格式化工具,可以用它格式报告对象。参数或者是内建格式化工具的名字:

or the full path to a JavaScript file containing a custom formatter. You can also omit the argument to retrieve the default formatter.

或者是包含自定义格式化工具的 JavaScript 文件的全路径。你也可以忽略这个参数来获取默认的格式化工具。

var CLIEngine = require("eslint").CLIEngine;

var cli = new CLIEngine({
    envs: ["browser", "mocha"],
    useEslintrc: false,
    rules: {
        semi: 2
    }
});

// lint myfile.js and all files in lib/
var report = cli.executeOnFiles(["myfile.js", "lib/"]);

// get the default formatter
var formatter = cli.getFormatter();

// Also could do...
// var formatter = cli.getFormatter("compact");
// var formatter = cli.getFormatter("./my/formatter.js");

// output to console
console.log(formatter(report.results));

Note: Also available as a static function on CLIEngine.

注意:CLIEngine 的静态方法也是适用的。

// get the default formatter by calling the static function
var formatter = CLIEngine.getFormatter();

Important: You must pass in the results property of the report. Passing in report directly will result in an error.

重要:你必须传递报告的 results。直接传递 report 会引起错误。

getErrorResults()

This is a static function on CLIEngine. It can be used to filter out all the non error messages from the report object.

这是 CLIEngine 的静态方法。它可以用于从报告对象中过滤掉所有没有错误的信息。

var CLIEngine = require("eslint").CLIEngine;

var cli = new CLIEngine({
    envs: ["browser", "mocha"],
    useEslintrc: false,
    rules: {
        semi: 2
    }
});

// lint myfile.js and all files in lib/
var report = cli.executeOnFiles(["myfile.js", "lib/"]);

// only get the error messages
var errorReport = CLIEngine.getErrorResults(report.results)

Important: You must pass in the results property of the report. Passing in report directly will result in an error.

重要:你必须传递报告的 results。直接传递 report 会引起错误。

outputFixes()

This is a static function on CLIEngine that is used to output fixes from report to disk. It does by looking for files that have an output property in their results. Here’s an example:

这是 CLIEngine 的静态方法,用于从 report 输出修复到磁盘。它通过搜索在结果中包含 output 的文件。例如:

var CLIEngine = require("eslint").CLIEngine;

var cli = new CLIEngine({
    envs: ["browser", "mocha"],
    fix: true,
    useEslintrc: false,
    rules: {
        semi: 2
    }
});

// lint myfile.js and all files in lib/
var report = cli.executeOnFiles(["myfile.js", "lib/"]);

// output fixes to disk
CLIEngine.outputFixes(report);

Deprecated APIs