# @adguard/re2-wasm 中文文档

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

版本：1\.2\.1
npm 元数据更新时间：2026-08-19T10:43:34.760Z
中文译文更新时间：2026-11-05T22:04:59.649Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.1 MB，11 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=10
- 运行依赖：0 个
- 首次发布：2024-06-19T15:27:06.210Z
- 最新版本发布：2026-07-14T13:52:41.071Z
- 近 30 天下载量：14022（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 1 个）

## 中文简介

Google的RE2库作为由AdGuard补丁的WASM模块发售.

## 安装

```sh
npm install @adguard/re2-wasm
```

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

## README

# @ adguard/ re2-wasm (英语) [![NPM version](https://img.shields.io/npm/v/@adguard/re2-wasm.svg)](https://npmjs.org/package/@adguard/re2-wasm)

> Google的RE2库作为由AdGuard补丁的WASM模块发售.

> **说明:** 此软件包开发于 [辅助软件](https://github.com/AdGuardSoftwareLimited/ext-re2-wasm)。 。 。 . 这个 [护卫小组/re2-wasm](https://github.com/AdguardTeam/re2-wasm) 寄存器是一个公共镜像.

## 说明

**@ adguard/ re2-wasm (英语)** 是谷歌的一个叉子 [旧的](https://github.com/google/re2-wasm) 添加可配置 正则表达式的最大内存限制。 它编译了谷歌的 [可再生能源2](https://github.com/google/re2) C++ 库到 WASM通过 Emscripten 并将其曝光为 JavaScript 的倒置替代 `RegExp`。 。 。 .

此库供需要处理用户提供的正则表达式的 JavaScript 和 TypeScript 开发者使用 安全无虞. 内置 `RegExp` 引擎可以在指数化时间运行,同时具有脆弱的正则表达式和 "邪恶输入",导致 [拒绝正常表达服务 (ReDOS) (英语)](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS)RE2担保 线性时间匹配,保护您的应用程序不受 ReDoS 攻击。 AdGuard 叉添加了已绑定的内存 通过 `maxMem` 选项——如果匹配尝试超过所配置的内存,引擎会丢出错误 限制,防止资源消耗.

`RE2`'正则表达式语言几乎是一个超级集,它是由 `RegExp` (见 [语法](https://github.com/google/re2/wiki/Syntax)),但它缺乏两个特征:回溯参考和前瞻 断言。 见 [与RegExp 的区别](https://npmcn.com/package/%40adguard/re2-wasm/#readme-differences-from-regexp) 详细情况.

## 目录

-   [安装](https://npmcn.com/package/%40adguard/re2-wasm/#readme-installation)
-   [快速启动](https://npmcn.com/package/%40adguard/re2-wasm/#readme-quick-start)
-   [API 概览](https://npmcn.com/package/%40adguard/re2-wasm/#readme-api-overview)
-   [用法实例](https://npmcn.com/package/%40adguard/re2-wasm/#readme-usage-examples)
-   [与RegExp 的区别](https://npmcn.com/package/%40adguard/re2-wasm/#readme-differences-from-regexp)
-   [文档](https://npmcn.com/package/%40adguard/re2-wasm/#readme-documentation)

* * *

## 安装

```bash
npm install @adguard/re2-wasm
```

需要Node.js QQ 10或一个有WASM支持的浏览器. 该软件包具有零运行时间依赖性——所有功能 来源于编译的WASM模块.

## 快速启动

```js
const { RE2 } = require('@adguard/re2-wasm');

const re = new RE2('hello (\\w+)', 'u');
const result = re.exec('hello world');
// result[0]: 'hello world'
// result[1]: 'world'
// result.index: 0
console.log(result[0]); // 'hello world'
```

或带有ES模块:

```js
import { RE2 } from '@adguard/re2-wasm';

const re = new RE2('\\d+', 'gu');
'abc 123 def 456'.match(re); // ['123', '456']
```

## API 概览

这个 `RE2` 类模拟标准 `RegExp` 接口。 在大多数情况下,它可以用作倒置替代.

### 构造器

```ts
new RE2(pattern: string | RegExp | RE2, flags?: string, maxMem?: number)
```

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `pattern` | `string`, (中文(简体) ), `RegExp`,或 `RE2` | 正则表达式图案. 接受已有 `RegExp` 或者说 `RE2` 对象. |
| `flags` | `string` | 标准 RegExp 旗 (`g`, (中文(简体) ), `i`, (中文(简体) ), `m`, (中文(简体) ), `s`, (中文(简体) ), `u`, (中文(简体) ), `y`) (中文(简体) ). 这个 `u` 旗帜是 **所需经费**。 。 。 . |
| `maxMem` | `number` | Regex 引擎可以使用的最大内存以字节表示. 默认为 `0` (无所限. 如果超过,则丢出一个错误. |

### 属性

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `lastIndex` | `number` | 启动下一个匹配的索引( 使用于 `g` 财务报告和审定财务报表 `y` 旗帜). |
| `global` | `boolean` | 是否为 `g` 已设置了旗帜. |
| `ignoreCase` | `boolean` | 是否为 `i` 已设置了旗帜. |
| `multiline` | `boolean` | 是否为 `m` 已设置了旗帜. |
| `dotAll` | `boolean` | 是否为 `s` 已设置了旗帜. |
| `unicode` | `boolean` | 是否为 `u` 已设置了旗帜。 永远 `true`。 。 。 . |
| `sticky` | `boolean` | 是否为 `y` 已设置了旗帜. |
| `source` | `string` | 原图案字符串. |
| `flags` | `string` | 出旗弦来. |
| `internalSource` | `string` | 翻译为RE2语法后的图案(只读,用于调试). |

### 方法

| 方法 | 说明 |
| --- | --- |
| `exec(str: string): RE2ExecArray | null` | 执行对匹配的搜索。 返回匹配数组或 `null`。 。 。 . |
| `test(str: string): boolean` | 试为一相. 回返 `true` 或者说 `false`。 。 。 . |
| `toString(): string` | 返回 regex 作为字符串(`/pattern/flags`) (中文(简体) ). |
| `match(str: string): RE2MatchArray | null` | 将字符串与正则ex相匹配。 等值为 `String.prototype.match`。 。 。 . |
| `search(str: string): number` | 寻相取相. 等值为 `String.prototype.search`。 。 。 . |
| `replace(str: string, replacer: string | function): string` | 替换匹配。 等值为 `String.prototype.replace`。 。 。 . |
| `split(str: string, limit?: number): (string | undefined)[]` | 将弦分出. 等值为 `String.prototype.split`。 。 。 . |

这个 `RE2` 类也支持有名的符号,所以 `String` 方法直接工作:

```js
const re = new RE2('\\d+', 'u');
'abc 123'.match(re);        // ['123', index: 4, input: 'abc 123']
'abc 123'.search(re);       // 4
'abc 123'.replace(re, 'X'); // 'abc X'
'abc 123'.split(re);        // ['abc ', '']
```

## 用法实例

### 从 RegExp 对象构造

```js
const orig = /\w+/gu;
const re = new RE2(orig);
// Flags and pattern are copied from the original
console.log(re.flags); // 'gu'
```

### 使用 maxMem 选项绑定内存

```js
// Limit the regex engine to 4 KB of memory
const re = new RE2('a*b*c*d*e*f*g*h*i*j*k*l*m*n*o*p*q*r*s*t*u*v*w*x*y*z*', 'u', 4096);
try {
  re.exec('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa');
} catch (e) {
  console.log('Pattern exceeded memory limit');
}
```

### 命名的捕获组

```js
const re = new RE2('(?P<word>\\w+) (?P<number>\\d+)', 'u');
const result = re.exec('hello 42');
console.log(result.groups.word);   // 'hello'
console.log(result.groups.number); // '42'
```

### 使用符号. matchall

```js
const re = new RE2('\\w+', 'gu');
for (const match of 'one two three'.matchAll(re)) {
  console.log(match[0]);
}
// 'one'
// 'two'
// 'three'
```

### 替换一个函数

```js
const re = new RE2('(\\d+)', 'gu');
const result = re.replace('a 10 b 20 c 30', (match, n) => String(Number(n) * 2));
console.log(result); // 'a 20 b 40 c 60'
```

### 返回到 RegExp 不支持的模式

```js
const pattern = /(a)+(b)*\\1/u;
let re;
try {
  re = new RE2(pattern);
} catch (e) {
  // Pattern uses backreferences — fall back to RegExp
  re = pattern;
}
const result = re.exec('aabbaabb');
```

## 与RegExp 的区别

### 背书和抬头的断言不支持

`RE2` 不支持回溯引用( n)`\\1`, (中文(简体) ), `\\2`或看头/看后面的断言(等等)`(?=...)`, (中文(简体) ), `(?<=...)`, (中文(简体) ), `(?!...)`, (中文(简体) ), `(?<!...)`) (中文(简体) ). 试图使用这些特性会投出 `SyntaxError`如果你的图案需要它们, 倒计时 `RegExp` (见《大会正式记录,第五十八届会议,补编第6号》) [倒置示例](https://npmcn.com/package/%40adguard/re2-wasm/#readme-falling-back-to-regexp-for-unsupported-patterns) (见上文).

### Unicode 旗帜是强制的

这个 `RE2` 引擎总是以Unicode模式运行。 这个 `u` 构建时必须传递旗帜 `RE2` 实例:

```js
new RE2('\\w+');           // throws Error: "u" flag must be passed
new RE2('\\w+', 'u');      // OK
```

### 内存限制

这个 `maxMem` 构造器参数( AdGuard 扩展) 限制 regex 引擎可分配多少内存 在匹配时。 如果超过限制,引擎会扔出一个错误. 过 `0` 不设限.

### 点行为

在RE2中, `.` 匹配任意字符,包括 `\\n`,无论是否 `m` 或者说 `s` 旗帜已经设定。 这是 等值为 `RegExp`是因为 `s` (dotall)旗帜总是在:

```js
const re = new RE2('a.b', 'u');
console.log(re.exec('a\\nb')); // ['a\\nb']
console.log(/a.b/u.exec('a\\nb')); // null
```

### 多行模式锁定

在多行模式下, `$` 在RE2中不匹配 `\\r` 财务报告和审定财务报表 `\\n` 当字符串结束时 `\\r\\n`数字 :

```js
const re = new RE2('a$', 'mu');
re.exec('a\\r\\n'); // null — RE2 does not match between \\r and \\n
/a$/mu.exec('a\\r\\n'); // ['a'] — RegExp matches between \\r and \\n
```

### `compile()` 方法

`RegExp.prototype.compile()` 在 `RE2`。称它是一个错误。 创建新 `RE2` 以实例代替.

### `d` 旗帜( 有索引)

这个 `hasIndices` (单位:千美元)`d`) 旗帜不支持. 使用 `RegExp` 与 `d` 如果您需要开始和结束索引 捕捉组.

* * *

## 文档

-   [发展](https://npmcn.com/package/%40adguard/re2-wasm/DEVELOPMENT.md) 如何建立和作出贡献
-   [更改日志](https://npmcn.com/package/%40adguard/re2-wasm/CHANGELOG.md) ——版本历史
-   [LLM 代理规则](https://npmcn.com/package/%40adguard/re2-wasm/AGENTS.md) ——AI协助发展指南

## 常见问题

### @adguard/re2-wasm 是什么？

Google的RE2库作为由AdGuard补丁的WASM模块发售\.

### 如何安装 @adguard/re2-wasm？

在项目目录运行 npm install @adguard/re2-wasm，或使用 pnpm add / yarn add / bun add。

### @adguard/re2-wasm 支持 TypeScript 吗？

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

### @adguard/re2-wasm 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @adguard/re2-wasm 需要什么版本的 Node\.js？

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

### @adguard/re2-wasm 可以商用吗？

@adguard/re2-wasm 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @adguard/re2-wasm 的下载量有多少？

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

### @adguard/re2-wasm 还在维护吗？

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