# espree 中文文档

规范地址：https://npmcn.com/package/espree/

版本：11\.2\.0
npm 元数据更新时间：2026-03-06T22:32:41.283Z
中文译文更新时间：2026-11-04T19:21:05.145Z
软件包许可：BSD-2-Clause

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/espree
原文对照：https://npmcn.com/package/espree/?lang=original
项目主页：https://github.com/eslint/js/blob/main/packages/espree/README.md
源码仓库：https://github.com/eslint/js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：95.7 kB，13 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| ^22\.13\.0 \|\| \>=24
- 运行依赖：3 个
- 首次发布：2014-12-06T03:10:12.402Z
- 最新版本发布：2026-03-06T22:32:40.951Z
- 近 30 天下载量：650897742（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：103（近 12 个月 4 个）

## 中文简介

一个基于Acorn的esprima兼容的JavaScript解析器

## 安装

```sh
npm install espree
```

也可以使用：`pnpm add espree`、`yarn add espree`、`bun add espree`

## README

[![npm version](https://img.shields.io/npm/v/espree.svg)](https://www.npmjs.com/package/espree) [![npm downloads](https://img.shields.io/npm/dm/espree.svg)](https://www.npmjs.com/package/espree) [![Build Status](https://github.com/eslint/js/workflows/CI/badge.svg)](https://github.com/js/espree/actions) [![Bountysource](https://www.bountysource.com/badge/tracker?tracker_id=9348450)](https://www.bountysource.com/trackers/9348450-eslint?utm_source=9348450&utm_medium=shield&utm_campaign=TRACKER_BADGE)

# Espree

Espree最初是一种叉子 [Esprima](http://esprima.org/) v1.2.2， Esprima在ECMAScript 6工作开始之前发布的最后一个稳定版本。Espree现在建立在 [橡子](https://github.com/ternjs/acorn)，它的模块化架构允许扩展核心功能。Espree的目标是使用类似的API生成类似于Esprima的输出，以便它可以代替Esprima使用。

## 用法

安装:

```
npm i espree
```

在ESM文件中使用：

```js
import * as espree from "espree";

const ast = espree.parse(code);
```

在普通JS文件中使用：

```js
const espree = require("espree");

const ast = espree.parse(code);
```

## API

### `parse()`

`parse` 解析给定的代码并返回抽象语法树（AST）。它有两个参数。

-   `code` 字符串 -需要解析的代码。
-   `options (Optional)` 对象 -阅读更多关于这个 [在这里](https://npmcn.com/package/espree/#readme-options)。

```js
import * as espree from "espree";

const ast = espree.parse(code);
```

**例子:**

```js
const ast = espree.parse('let foo = "bar"', { ecmaVersion: 6 });
console.log(ast);
```

输出

```
Node {
  type: 'Program',
  start: 0,
  end: 15,
  body: [
    Node {
      type: 'VariableDeclaration',
      start: 0,
      end: 15,
      declarations: [Array],
      kind: 'let'
    }
  ],
  sourceType: 'script'
}
```

### `tokenize()`

`tokenize` 返回给定代码的令牌。它有两个参数。

-   `code` 字符串 -需要解析的代码。
-   `options (Optional)` 对象 -阅读更多关于这个 [在这里](https://npmcn.com/package/espree/#readme-options)。

即使 `options` 是空的还是未定义的 `options.tokens` 是 `false`，它赋值给 `true` 为了得到 `tokens` 数组

**例子:**

```js
import * as espree from "espree";

const tokens = espree.tokenize('let foo = "bar"', { ecmaVersion: 6 });
console.log(tokens);
```

输出

```
Token { type: 'Keyword', value: 'let', start: 0, end: 3 },
Token { type: 'Identifier', value: 'foo', start: 4, end: 7 },
Token { type: 'Punctuator', value: '=', start: 8, end: 9 },
Token { type: 'String', value: '"bar"', start: 10, end: 15 }
```

### `version`

返回当前 `espree` 版本

### `VisitorKeys`

返回用于遍历AST的所有访问者键 [eslint-visitor-keys](https://github.com/eslint/js/tree/main/packages/eslint-visitor-keys)

### `latestEcmaVersion`

所支持的最新ECMAScript `espree`

### `supportedEcmaVersions`

返回所有支持的ECMAScript版本的数组

## 选项

```js
const options = {
    // attach range information to each node
    range: false,

    // attach line/column location information to each node
    loc: false,

    // create a top-level comments array containing all comments
    comment: false,

    // create a top-level tokens array containing all tokens
    tokens: false,

    // Set to 3, 5 (the default), 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16 or 17 to specify the version of ECMAScript syntax you want to use.
    // You can also set to 2015 (same as 6), 2016 (same as 7), 2017 (same as 8), 2018 (same as 9), 2019 (same as 10), 2020 (same as 11), 2021 (same as 12), 2022 (same as 13), 2023 (same as 14), 2024 (same as 15), 2025 (same as 16) or 2026 (same as 17) to use the year-based naming.
    // You can also set "latest" to use the most recently supported version.
    ecmaVersion: 3,

    allowReserved: true, // only allowed when ecmaVersion is 3

    // specify which type of script you're parsing ("script", "module", or "commonjs")
    sourceType: "script",

    // specify additional language features
    ecmaFeatures: {
        // enable JSX parsing
        jsx: false,

        // enable return in global scope (set to true automatically when sourceType is "commonjs")
        globalReturn: false,

        // enable implied strict mode (if ecmaVersion >= 5)
        impliedStrict: false,
    },
};
```

## Esprima兼容性向前发展

主要目标是生成与Esprima完全相同的AST结构和令牌，并且优先于其他任何东西。(AST结构为 [ESTree](https://github.com/estree/estree) 带有JSX扩展的API。)除此之外，在附加注释的位置和方式以及AST节点上可用的附加信息方面，Espree可能会偏离Esprima的输出。也就是说，与Esprima相比，Espree可能会向AST节点添加更多的东西，但生成的AST整体结构将是相同的。

Espree也可能在它所公开的接口中偏离Esprima。

## 贡献

问题和pull请求将被分类并尽快做出回应。我们在 [ESLint贡献者指南](http://eslint.org/docs/developer-guide/contributing),所以请务必在投稿前阅读它们。如果您不确定在哪里挖掘，请查看 [问题](https://github.com/eslint/js/issues)。

Espree是在一个宽松的BSD 2条款许可下许可的。

## 安全政策

我们努力确保Espree对每个人都是安全的，安全问题得到迅速和负责任的解决。阅读全文 [安全策略](https://github.com/eslint/.github/blob/master/SECURITY.md)。

## 生成命令

-   `npm test` -运行所有测试
-   `npm run lint` -运行所有的linting

## 与Espree 2.x的区别

-   这个 `tokenize()` 方法不使用 `ecmaFeatures`． 任何字符串都将完全基于ECMAScript 6语义进行标记化。
-   末尾的空格不再被计算为节点的一部分。
-   `let` 和 `const` 默认情况下不再解析声明。您必须使用 `ecmaVersion` 更新的比 `5` 或设置 `sourceType` 来 `module`。
-   这个 `esparse` 和 `esvalidate` 二进制脚本已被删除。
-   没有 `tolerant` 选择。我们将在将来研究添加此功能。

## 已知的不兼容

为了帮助那些想要从其他解析器过渡到Espree的人，下面列出了与其他解析器的值得注意的不兼容性。这些都是已知的差异，我们不打算改变。

### Esprima 1.2.2

-   Esprima将尾随空格计数为每个AST节点的一部分，而Espree不这样做。在Espree中，节点的末尾是最后一个令牌出现的地方。
-   Espree不解析 `let` 和 `const` 默认的声明。
-   解析错误返回的错误消息是不同的。
-   每个节点和令牌上都有两个附加属性： `start` 和 `end`． 表示相同的数据 `range` 是Acorn内部使用的。

### Esprima 2.倍

-   Esprima 2。x使用不同的评论附件算法，导致一些评论被添加到与Espree不同的位置。Espree使用的算法与Esprima 1.2.2中使用的算法相同。

## 常见问题

### 为什么要使用另一个解析器

[ESLint](http://eslint.org/) 从一开始就依赖Esprima作为它的解析器。虽然在JavaScript语言发展缓慢的时候，这还不错，但随着开发步伐的急剧加快，Esprima已经落后了。和其他依赖Esprima的工具一样，ESLint一直在使用新的JavaScript语言特性，直到Esprima更新，这让我们的用户感到沮丧。

我们决定前进的唯一途径是创建我们自己的解析器，使我们与JSHint和JSLint内联，并允许我们在需要时不断实现新功能。我们选择分叉Esprima，而不是从头开始，以便通过兼容的API尽可能快地移动。

在Espree 2.0.0中，我们不再是Esprima的分支，而是Acorn和Esprima语法之间的翻译层。这使我们能够将工作重新放到社区支持的解析器（Acorn）中，该解析器将继续成长和发展，同时为那些仍然构建在Esprima上的实用程序维护一个与Esprima兼容的解析器。

### 你试过和Esprima合作吗？

是。自ESLint发布以来，我们定期向Esprima提交bug和特性请求，并将继续这样做。然而，关于项目如何工作有一些不同的理念需要完成。最初的目标是让Espree跟踪Esprima，并最终将两者合并在一起，但我们最终决定在Acorn之上构建是一个更好的选择，因为Acorn的插件支持。

### 你为什么不直接用橡果呢？

Acorn是一个很棒的JavaScript解析器，可以生成与Esprima兼容的AST。不幸的是，ESLint不仅仅依赖于AST来完成它的工作。它依赖于Esprima的令牌和注释附件功能来获得源代码的完整图像。我们研究过切换到Acorn，但是Esprima和Acorn之间的不一致性给ESLint这样的项目带来了太多的工作。

然而，我们是在Acorn的基础上建设的，这样我们就可以回馈并帮助Acorn变得更好。

### 你支持哪些ECMAScript特性？

Espree支持ECMAScript 2025的所有特性，并部分支持ECMAScript 2026的特性。

由于ECMAScript 2026仍在开发中，我们正在实现最终确定的特性。目前，Espree支持：

-   [显式资源管理](https://github.com/tc39/proposal-explicit-resource-management)

看到 [finished-proposals.md](https://github.com/tc39/proposals/blob/master/finished-proposals.md) 了解哪些功能已经完成。

### 如何决定支持哪些实验特性？

一般来说，我们不支持实验性的JavaScript特性。我们可能会根据功能的成熟度不时地做出例外。

## 赞助商

以下公司、组织和个人支持ESLint的持续维护和开发。 [成为赞助商](https://eslint.org/donate) 把你的标志印在我们的自述上 [网站](https://eslint.org/sponsors)。

### 白金赞助商

[![Automattic](https://images.opencollective.com/automattic/d0ef3e1/logo.png)](https://automattic.com/)

### 黄金赞助商

[![Qlty Software](https://images.opencollective.com/qltysh/33d157d/logo.png)](https://qlty.sh/)

### 银赞助商

[![Vite](https://images.opencollective.com/vite/d472863/logo.png)](https://vite.dev/) [![Liftoff](https://images.opencollective.com/liftoff/2d6c3b6/logo.png)](https://liftoff.io/) [![StackBlitz](https://avatars.githubusercontent.com/u/28635252)](https://stackblitz.com/)

### 青铜赞助商

[![Cybozu](https://images.opencollective.com/cybozu/933e46d/logo.png)](https://cybozu.co.jp/) [![SAP](https://avatars.githubusercontent.com/u/2531208)](https://opensource.sap.com/) [![CrawlJobs](https://images.opencollective.com/crawljobs-poland/fa43a17/logo.png)](https://www.crawljobs.com/) [![Depot](https://images.opencollective.com/depot/39125a1/logo.png)](https://depot.dev/) [![N-iX Ltd](https://images.opencollective.com/n-ix-ltd/575a7a5/logo.png)](https://www.n-ix.com/) [![Icons8](https://images.opencollective.com/icons8/7fa1641/logo.png)](https://icons8.com/) [![Discord](https://images.opencollective.com/discordapp/f9645d9/logo.png)](https://discord.com/) [![GitBook](https://avatars.githubusercontent.com/u/7111340)](https://www.gitbook.com/) [![HeroCoders](https://avatars.githubusercontent.com/u/37549774)](https://herocoders.com/) [![TestMu AI Open Source Office (Formerly LambdaTest)](https://avatars.githubusercontent.com/u/171592363)](https://www.lambdatest.com/)

### 技术赞助商

技术赞助商允许我们免费使用他们的产品和服务，作为对开源生态系统和我们工作的贡献的一部分。

[![Netlify](https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/netlify-icon.svg)](https://netlify.com/) [![Algolia](https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/algolia-icon.svg)](https://algolia.com/) [![1Password](https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/1password-icon.svg)](https://1password.com/)

## 常见问题

### espree 是什么？

一个基于Acorn的esprima兼容的JavaScript解析器

### 如何安装 espree？

在项目目录运行 npm install espree，或使用 pnpm add / yarn add / bun add。

### espree 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### espree 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### espree 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.19\.0 \|\| ^22\.13\.0 \|\| \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### espree 可以商用吗？

espree 使用 BSD-2-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### espree 的下载量有多少？

根据 npm 官方下载统计，espree 在 2026/10/04 – 2026/11/02 这 30 天内被下载 650,897,742 次，日均约 21,696,591 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### espree 还在维护吗？

最新版本 11\.2\.0 发布于 2026/03/07（7 个月前）；至今共发布 103 个版本，其中过去 12 个月发布了 4 个；首次发布于 2014/12/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。