JS正则替换只匹配第一个？详解g标志与replaceAll区别

一、为什么 replace 默认只替换第一个匹配项？

很多初学 JavaScript 的开发者在处理字符串替换时，往往会写出如下代码并困惑为什么后续的字符没有被处理：

const rawText = "2026-03-15 and 2026-04-20";
const result = rawText.replace("-", "/");

// 示例输出：
// "2026/03-15 and 2026-04-20" —— 只有第一个连字符被替换！

这个现象并非引擎 Bug，而是 ECMAScript 语言规范自 1999 年第三版（ES3）便明确规定的固定行为。依据规范中对 String.prototype.replace(searchValue, replaceValue) 的算法流程描述：

1. 当 searchValue 是普通字符串时：引擎在内部执行类似 StringIndexOf 操作，从当前字符串的 0 号索引向后线性检索；一旦找到与 searchValue 相符的首个子串位置，便记录其起始偏移量与匹配长度，并立即构建替换后的新字符串返回，检索直接终止。
2. 当 searchValue 是非全局正则表达式时（无 g 标志）：引擎调用该正则对象的 RegExpBuiltinExec 算法。因为缺少全局修饰符，正则执行引擎只进行单次寻径，捕获首次命中的子串后便立刻向字符串包装器回传匹配对象，整个替换流程随即结束。

换言之，replace() 方法在参数不具备“全局意图指示”时，其设计契约就是为了高效率地处理“单次命中并返回”。在处理大规模文本时，这种尽早跳出（Early Return）的设计可以避免无意义的全量扫描开销。

二、正则表达式的 g 标志（Global）如何改变替换行为？

要让 replace() 继续向后寻找下一个匹配项，传统方式是在正则表达式后附加上 g 标志，即 /pattern/g。

1. g 标志的驱动机制

在正则表达式中，g 代表“Global（全局）”。当 RegExp 实例被标记为全局匹配时，它会向 String.prototype.replace 发出持续扫描的信号。引擎会在底层开启一个迭代循环：

• 引擎首先在索引 0 处寻找匹配项。
• 命中目标后，引擎将匹配位置前后的片段与替换内容拼接存入暂存缓冲区。
• 随后，引擎将扫描起始索引推进至 matchIndex + matchLength，继续向右扫描寻找下一个目标，直到遇到字符串末尾。

const rawText = "2026-03-15 and 2026-04-20";
// 传入带 g 标志的正则：
const globalResult = rawText.replace(/-/g, "/");

// 示例输出：
// "2026/03/15 and 2026/04/20" —— 全量替换成功

2. 一个关于 lastIndex 的重要辨析

许多开发者在深入学习正则时，常会听到一个说法：“全局正则对象是有状态的，执行时会不断修改自身的 lastIndex 属性，多次执行会导致匹配诡异跳过”。这种说法在调用 RegExp.prototype.exec() 或 RegExp.prototype.test() 时确实成立：全局正则实例会在每次执行后把下一次搜索位置记录到自身的 lastIndex 属性中，导致下次调用时从上次结束处起步。

但在 String.prototype.replace() 内部，规范明确要求：方法开始执行前会由引擎重置该正则内部游标或创建临时上下文，完成所有替换后还会将其重置为 0。因此，直接在 replace 中传入全局正则不会污染外部实例的后续检索状态，但为了代码可读性与防范并发/共享隐患，依然建议在每次替换时使用字面量正则或重新构造实例。

3. 传统正则替换的最大痛点：动态字面量转义

虽然 /pattern/g 解决了已知固定模式的全局替换，但如果我们要替换的关键词来自外部输入或动态变量，就必须使用 new RegExp(keyword, 'g')。此时会遇到极具隐患的陷阱：若变量中包含正则表达式保留字符（如 .、*、?、$、[、( 等），正则构造器会直接将其解析为元字符，甚至直接抛出语法错误。

const userKeyword = "cost(usd)"; // 含有正则保留字符 '(' 和 ')'
const content = "items: cost(usd) = 10, cost(usd) = 20";

// 错误做法：直接传入动态字符串构建正则
try {
  const badRegex = new RegExp(userKeyword, "g");
  content.replace(badRegex, "price");
} catch (e) {
  // 运行时异常：SyntaxError: Invalid regular expression: missing )
}

为了使动态字符串能够安全用作正则，以往的前端代码中不得不引入一长串转义样板函数（Escape Function）：

function escapeRegExp(string) {
  return string.replace(/[.*+?^${}()|[\]\]/g, "\$&");
}

const safeRegex = new RegExp(escapeRegExp(userKeyword), "g");
const safeResult = content.replace(safeRegex, "price");
// 示例输出："items: price = 10, price = 20"

这种手动转义不仅书写冗长、容易产生遗漏，而且对纯文本替换而言带来了多余的正则编译与运行时开销。这一痛点直接催生了 ES2021 中 replaceAll 的诞生。

三、ES2021 原生 replaceAll：纯文本全局替换的最佳解

为了终结“为了全局替换一个普通字符串必须使用正则转义”的历史局限，ECMAScript 2021（ES12）正式将 String.prototype.replaceAll 纳入标准规范。

1. 字面量字符串的无痛替换

当首个参数为普通字符串时，replaceAll 会自动在整个输入字符串中寻找该子串的所有出现位置，并逐一替换。它将参数视为严格的字面量文本，不进行任何正则元字符解析：

const userKeyword = "cost(usd)";
const content = "items: cost(usd) = 10, cost(usd) = 20";

// 无需编写转义辅助函数，直接传入纯文本字符串：
const cleanResult = content.replaceAll(userKeyword, "price");

// 示例输出：
// "items: price = 10, price = 20" —— 干净、直观、绝对安全！

不仅是带有括号等标点的文本，任何包括 $、.、* 等特殊符号的用户搜索词，在 replaceAll(string, ...) 中都不会引发歧义。底层引擎采用优化的快速字符串检索（如 Boyer-Moore 变种算法），免去了构建正则 DFA/NFA 状态机的内存与计算成本。

四、关键陷阱：replaceAll 与正则搭配时的严格限制

很多开发者在知晓 replaceAll 后，误以为它可以无脑替换掉既有的 replace 调用。然而，当把正则表达式传给 replaceAll 时，存在一个极其容易在生产环境中触发线上故障的强制规则。

const text = "cat and dog";

// 致命调用：传入无 g 标志的正则对象
try {
  text.replaceAll(/cat/, "bird");
} catch (err) {
  // 抛出异常：
  // TypeError: String.prototype.replaceAll called with a non-global RegExp argument
}

为什么规范故意设计为抛出异常，而不是自动补上 g 标志？

部分人可能会产生疑问：既然调用了名为“replaceAll”的方法，用户意图显然是全量替换，引擎为什么不悄悄补全全局标志，或者退化为单次替换？

TC39 委员会在制定规范时进行了专门的严谨论证：

1. 防御隐式错误（Fail-Fast 原则）：如果开发者传入了 /abc/（没有 g），这说明开发者的正则声明与其调用的“全量”语义存在显著冲突。如果引擎隐式将其转为全局，当正则内含有复杂的捕获状态、先行断言或状态游标时，可能会引发意料之外的严重数据损坏；若退化为只替换首个，又违背了方法名为“All”的基本契约。
2. 保持语义纯粹：显式抛出 TypeError 能够让这类逻辑矛盾在开发阶段、单元测试阶段尽早暴露并被修复，避免静默降级导致在生产环境中长期潜伏。

因此，若要在 replaceAll 中使用正则，必须确保显式带有 g 标志：

// 正确做法：必须附带 g 标志
const safeRegResult = text.replaceAll(/cat/g, "bird"); // 正常执行

五、替换值中的高级模式与回调函数一致性

无论使用 replace(/.../g, ...) 还是 replaceAll()，两者的第二个参数（替换模式或替换回调函数）在 ECMAScript 规范中保持了高度的对齐与通用性。

1. 特殊替换变量语法

当第二个参数是字符串时，你可以使用以下预设的特殊转义标记：

2. Replacer 回调函数传参

当第二个参数传入函数时，每次匹配都会触发一次该回调。两者的函数签名完全对齐：

const raw = "apple: 5, banana: 12, orange: 8";

const formatted = raw.replaceAll(/(\w+):\s*(\d+)/g, (match, p1, p2, offset, source) => {
  // match: 完整匹配串，如 "apple: 5"
  // p1: 第 1 捕获组，如 "apple"
  // p2: 第 2 捕获组，如 "5"
  // offset: 当前匹配在整个原串中的起始索引
  // source: 原始完整字符串
  return `${p1.toUpperCase()}=[${p2}件]`;
});

// 示例输出：
// "APPLE=[5件], BANANA=[12件], ORANGE=[8件]"

六、现代项目技术选型与最佳实践

面对具体业务开发需求，如何准确、清晰地做出方法选择？可以参考以下三条核心准则：

1. 纯字符串（字面量或动态变量）的全局替换：无条件优先选择 replaceAll()
   只要搜索目标是固定字符串或用户输入的关键词，就应当直接使用 str.replaceAll(keyword, replacement)。这能完全省去编写正则表达式转义代码的麻烦，消除潜在的 ReDoS 或正则语法奔溃漏洞，同时提高代码的可读性与意图表达。
2. 模糊模式、字符集或捕获组结构的全局替换：使用带 g 标志的正则
   如果需要匹配数字序列（如 \d+）、单词边界（）或使用命名捕获组进行文本换位，请使用 replace(/pattern/g, ...) 或 replaceAll(/pattern/g, ...)。在社区实践中，开发者更倾向于使用久经考验的 str.replace(/pattern/g, ...)，因为其在各大工具库、旧工程与语法高亮器中的认知度极高且行为完全一致。
3. 老旧浏览器与运行环境兼容方案：
   replaceAll 属于 ECMAScript 2021 特性。如果你的项目需要支持 Node.js 14 及以下版本，或者需要兼容旧版移动端 WebView、旧版 Safari（< 14.1），可使用官方标准 polyfill（如引入 core-js/actual/string/replace-all）或者在打包配置中通过 Babel 进行转译兼容。

七、常见混淆说法与针对性辨析

辨析 1：“replaceAll 可以全面取代 replace”？

修正分析：这一说法并不准确。replaceAll 的定位非常聚焦——它专门用于全量匹配场景。而在实际开发中，仍有大量场景明确要求“只替换首个匹配项”（例如只替换第一个出现的首字母、只剥离最外层的协议头等），这些场景必须依赖 replace()。两者并非替代与被替代的关系，而是互补的精确语义工具。

辨析 2：“用 split(str).join(newStr) 进行全局替换比 replace 更好”？

修正分析：在 replaceAll 诞生之前，社区确实经常使用 text.split("-").join("/") 来模拟字面量全局替换，以规避正则转义。这种写法虽然巧妙，但它会在底层先将整个字符串根据分隔符切散并分配一个完整的临时数组（Array），然后再将数组遍历拼接为一个新字符串。这会产生额外的内存分配和垃圾回收（GC）压力。在现代浏览器与 Node.js 环境中，直接使用底层的 replaceAll 不仅在性能与内存上更具优势，语义上也远比“拆散再拼合”更为直接。