# @ast-grep/wasm 中文文档

规范地址：https://npmcn.com/package/%40ast-grep/wasm/

版本：0\.51\.1
npm 元数据更新时间：2026-11-02T05:36:31.313Z
中文译文更新时间：2026-11-07T00:31:49.570Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ast-grep/wasm
原文对照：https://npmcn.com/package/%40ast-grep/wasm/?lang=original
项目主页：https://github.com/ast-grep/ast-grep#readme
源码仓库：https://github.com/ast-grep/ast-grep

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

- 包体积（解压后）：2.3 MB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：web-tree-sitter ^0\.26\.0 \|\| ^0\.27\.0
- 首次发布：2026-02-21T23:14:53.595Z
- 最新版本发布：2026-11-02T05:36:31.140Z
- 近 30 天下载量：9224（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

使用精确的 AST 模式大规模搜索和重写代码

## 安装

```sh
npm install @ast-grep/wasm
```

也可以使用：`pnpm add @ast-grep/wasm`、`yarn add @ast-grep/wasm`、`bun add @ast-grep/wasm`

## README

# @ast-grep/wasm (英语)

网络大会构建 [ast- grep 图像](https://ast-grep.github.io/) 用于浏览器和节点.js.

此软件包提供的API与 [`@ast-grep/napi`](https://www.npmjs.com/package/@ast-grep/napi) 但运行在任何支持WebAssembly的JavaScript环境中,包括浏览器,Deno,以及边缘运行时间.

## 安装

```bash
yarn add @ast-grep/wasm web-tree-sitter
```

`web-tree-sitter` 是一个必要的同伴依赖.

### 维特

在使用Vite时,需要制作 `tree-sitter.wasm` 可在您的公共目录中找到。 你可以将这个自动化 `postinstall` 您的脚本 `package.json` (见 [网络植树人设置](https://github.com/tree-sitter/tree-sitter/tree/master/lib/binding_web#setup):

```json
"postinstall": "cp node_modules/web-tree-sitter/tree-sitter.wasm public"
```

## 使用量

与 `@ast-grep/napi`,此软件包没有预定义的语言支持。 所有语言都必须在运行时通过加载其树保姆WASM 解析器来注册.

```js
import { initializeTreeSitter, registerDynamicLanguage, parse, kind } from '@ast-grep/wasm'

// 1. Initialize the tree-sitter WASM runtime (once)
await initializeTreeSitter()

// 2. Register a language by loading its WASM parser
await registerDynamicLanguage({
  javascript: { libraryPath: '/path/to/tree-sitter-javascript.wasm' },
})

// 3. Parse and search code
const sg = parse('javascript', 'console.log("hello world")')
const node = sg.root().find('console.log($ARG)')
console.log(node.getMatch('ARG').text()) // "hello world"
```

### 注册语文

`registerDynamicLanguage` 接受注册配置的语文名称地图。 它可以被多次调用来添加或更新语言.

```js
await registerDynamicLanguage({
  javascript: { libraryPath: '/path/to/tree-sitter-javascript.wasm' },
  python: {
    libraryPath: '/path/to/tree-sitter-python.wasm',
    expandoChar: 'µ',  // custom expando char for languages where $ is special
  },
})
```

这个 `expandoChar` 选项设置内部用于表示可变变量的字符(默认为 `$`) (中文(简体) ). 对语言使用不同的字符 `$` 是有效的标识符字符(例如PHP, Bash).

### 模式匹配

```js
// By pattern string
sg.root().find('console.log($$$ARGS)')

// By kind number
const k = kind('javascript', 'call_expression')
sg.root().find(k)

// By rule config (same as YAML rules)
sg.root().find({
  rule: { pattern: 'console.log($A)' },
  constraints: { A: { kind: 'string' } },
})
```

### 代码重写

```js
const match = sg.root().find('console.log($A)')
const edit = match.replace('console.error($A)')
const newCode = sg.root().commitEdits([edit])
```

## API 参考

### 高级职能

#### `initializeTreeSitter(): Promise<void>`

初始化树保姆 WASM 运行时间 。 必须在其他功能之前调用一次 .

#### `registerDynamicLanguage(langs: Record<string, { libraryPath: string, expandoChar?: string }>): Promise<void>`

通过加载其WASM 二进制来注册一个或多个语言解析器. 可以多次调用;现有语言被更新.

#### `parse(lang: string, src: string): SgRoot`

解析源代码并返回一个 `SgRoot` 举个例子 如果语言尚未注册, 则丢弃 .

#### `kind(lang: string, kindName: string): number`

返回给定语言中命名的节点类型的数字类型ID。 用于以节点类型匹配 .

#### `pattern(lang: string, patternStr: string): object`

将模式字符串编译为规则配置对象(相当于 `{ rule: { pattern: patternStr } }`) (中文(简体) ). 用于在程序上构建规则配置.

#### `dumpPattern(lang: string, patternStr: string, selector?: string, strictness?: string): PatternTree`

倾倒检查和调试模式的内部结构。 返回显示 ast- grep 描述模式的树, 包括源位置和节点类型 .

-   `selector`:背景图案的可选类型名称(例如:. `'field_definition'`(中文(简体) )
-   `strictness`: 一个 `"cst"`, (中文(简体) ), `"smart"` (违约), `"ast"`, (中文(简体) ), `"relaxed"`, (中文(简体) ), `"signature"`, (中文(简体) ), `"template"`

每个 `PatternTree` 节点有:

-   `kind`: 树保姆节点类型字符串
-   `pattern`数字 : `"metaVar"`, (中文(简体) ), `"terminal"`,或 `"internal"`
-   `isNamed`: 节点是否是一个命名的节点
-   `text`: 源文本(用于元和终端节点)
-   `children`: 儿童 `PatternTree` 节点
-   `start`, (中文(简体) ), `end`数字 : `{ line, column }` 模式来源中的职位

### `SgRoot`

代表代码的解析树 .

#### `root(): SgNode`

返回根数 `SgNode`。 。 。 .

#### `filename(): string`

回返 `"anonymous"` 当实例是通过 `parse`。 。 。 .

#### `getInnerTree(): Tree`

返回基础 `web-tree-sitter` `Tree` 对象。 用于低级检查或调试.

### `SgNode`

代表一个AST节点.

#### 立场和信息

| 方法 | 说明 |
| --- | --- |
| `range()` | 回返 `{ start, end }` 每一地点 `{ line, column, index }` |
| `isLeaf()` | 如果节点没有孩子,就是真的 |
| `isNamed()` | 如果节点是命名( 非匿名) 节点, 则为真 |
| `isNamedLeaf()` | 如果节点是没有孩子的有名节点,那就是真的 |
| `kind()` | 返回节点类型字符串 |
| `is(kind: string)` | 如果节点类型相等, 则为真 `kind` |
| `text()` | 返回节点的源文本 |
| `id()` | 返回唯一节点 ID |

#### 搜索中

| 方法 | 说明 |
| --- | --- |
| `find(matcher)` | 返回匹配者的第一个后人,或 `undefined` |
| `findAll(matcher)` | 返回匹配者的所有后人 |

匹配符可以是图案字符串,类型数(来自 `kind()`),或规则配置对象.

#### 关系匹配者

| 方法 | 说明 |
| --- | --- |
| `matches(matcher)` | 如果节点本身匹配, 则为真 |
| `inside(matcher)` | 如果节点在与匹配者相匹配的祖先体内,则为真 |
| `has(matcher)` | 如果节点有匹配匹配者的后人,那就是真的 |
| `precedes(matcher)` | 如果节点在比对对手的弟弟之前出现,那就是真的 |
| `follows(matcher)` | 如果结点是跟比对者比对的兄弟 |

#### 匹配环境

| 方法 | 说明 |
| --- | --- |
| `getMatch(name: string)` | 返回链接到可变元的节点(例如:. `$VAR`(中文(简体) ) |
| `getMultipleMatches(name: string)` | 返回绑定在多变量的节点(例如:. `$$$ARGS`(中文(简体) ) |
| `getTransformed(name: string)` | 返回已变换变量的字符串值 |

#### 树倒转

| 方法 | 说明 |
| --- | --- |
| `children_nodes()` | 返回所有子节点 |
| `parent_node()` | 返回父节点,或 `undefined` |
| `child(nth: number)` | 返回第一个孩子,或 `undefined` |
| `ancestors()` | 将所有祖先从父辈返回到根 |
| `next_node()` | 返回下一个兄弟姐妹,或 `undefined` |
| `nextAll()` | 遣返所有以下兄弟姐妹 |
| `prev()` | 返回上一个兄弟姐妹,或 `undefined` |
| `prevAll()` | 遣返所有前兄弟姐妹 |
| `field(name: string)` | 返回指定字段的儿童节点,或 `undefined` |
| `fieldChildren(name: string)` | 返回指定字段的所有子节点 |

#### 编辑

| 方法 | 说明 |
| --- | --- |
| `replace(text: string)` | 创建一个 `WasmEdit` 以 `text` |
| `commitEdits(edits: WasmEdit[])` | 应用编辑到节点的文本并返回新的源字符串 |

`WasmEdit` 已经 `start_pos`, (中文(简体) ), `end_pos` (单位:千美元) `inserted_text`。这些字段在调用前可以修改 `commitEdits`。 。 。 .

## 来源建筑

要求数 [包装](https://rustwasm.github.io/wasm-pack/installer/)。 。 。 .

```bash
# For browser (ES module)
yarn build

# For Node.js (CommonJS)
yarn build:nodejs

# For bundlers
yarn build:bundler
```

## 测试

```bash
yarn install
```

### 粗瓦斯M测试

```bash
yarn test
```

> **说明:** `wasm-pack test --node` 从临时目录运行测试带. 这个 `test` 脚本集 `NODE_PATH=$PWD/node_modules` 这样 `web-tree-sitter` 财务报告和审定财务报表 解析器 WASM 文件可以解决。 如果你运行 `wasm-pack test --node` 直接, 设定 `NODE_PATH` 自己说:
> 
> ```bash
> NODE_PATH=$PWD/node_modules wasm-pack test --node
> ```

### Java 脚本测试

```bash
yarn test:js
```

这为Node.js构建了WASM软件包,并对其进行AVA测试.

## 常见问题

### @ast-grep/wasm 是什么？

使用精确的 AST 模式大规模搜索和重写代码

### 如何安装 @ast-grep/wasm？

在项目目录运行 npm install @ast-grep/wasm，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：web-tree-sitter（^0\.26\.0 \|\| ^0\.27\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ast-grep/wasm 支持 TypeScript 吗？

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

### @ast-grep/wasm 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @ast-grep/wasm 可以商用吗？

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

### @ast-grep/wasm 的下载量有多少？

根据 npm 官方下载统计，@ast-grep/wasm 在 2026/10/07 – 2026/11/05 这 30 天内被下载 9,224 次，日均约 307 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ast-grep/wasm 还在维护吗？

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