JavaScript replaceAll 取代後文字變了？字串搜尋與 $ 替換排錯

2026-11-04

前端

JavaScript

/

前端開發

/

疑難排解

/

最佳實踐

把通知模板中的每個 {{name}} 換成使用者名稱，replace() 卻只改第一個。換成 replaceAll() 可以處理全部符合項目；但若名稱剛好含有 $& 或 $$，結果仍可能和原文不同。

搜尋一般文字時，直接把字串交給 replaceAll；替換內容要原樣保留時，使用回傳該內容的 callback。 這兩個選擇分別處理搜尋模式與替換規則。

先確認只改一處，還是替換內容被解讀#

MDN replace 說明指出，字串模式只取代第一個符合項目；第二個參數若是字串，仍會解讀特殊替換模式。$& 表示這次符合的文字，$$ 產生一個 $。

以下每個 JavaScript 區塊可獨立存成 .mjs，使用 Node.js 執行：

1
import assert from 'node:assert/strict';
2

3
const template = '{{name}} / {{name}}';
4
assert.equal(template.replace('{{name}}', '小明'), '小明 / {{name}}');
5
assert.equal(template.replaceAll('{{name}}', '小明'), '小明 / 小明');
6
assert.equal(template.replaceAll('{{name}}', '$&'), template);
7
assert.equal(template.replaceAll('{{name}}', '$$'), '$ / $');
8

9
const name = '$& / $$ / $1';
10
assert.equal(template.replaceAll('{{name}}', () => name), `${name} / ${name}`);
11
// 字串方法回傳新值，原字串保持原樣。
12
assert.equal(template, '{{name}} / {{name}}');
13
console.log('replacement semantics: PASS');

$1 等捕捉群組規則要配合實際正則群組判讀，不能把每個 $ 後接數字都視為已展開。callback 回傳的字串會直接當成替換內容，適合名稱、備註與外部文字；MDN replaceAll也支援此種形式。

將「一般文字全部取代」寫成明確契約#

若搜尋文字來自輸入框，new RegExp(search, 'g') 會把 .、* 等當成正則語法。直接使用字串搜尋，可以讓 a.b 只符合 a.b。需要動態正則時，可另看 RegExp.escape 的輸入處理。

下面的 helper 限定三個參數都是字串，並拒絕空搜尋值。空字串原本有合法行為，但對模板替換工具而言，把文字插入每個位置容易掩蓋輸入錯誤，因此在應用程式入口先擋住。

1
import assert from 'node:assert/strict';
2

3
function replaceLiteralAll(text, search, replacement) {
4
  if ([text, search, replacement].some(value => typeof value !== 'string')) {
5
    throw new TypeError('text, search and replacement must be strings');
6
  }
7
  if (search.length === 0) throw new RangeError('search must not be empty');
8
  return text.replaceAll(search, () => replacement);
9
}
10

11
assert.equal(replaceLiteralAll('a.b aXb a.b', 'a.b', '$&'), '$& aXb $&');
12
assert.equal(replaceLiteralAll('aaa', 'aa', 'X'), 'Xa'); // 符合項目不重疊
13
assert.equal(replaceLiteralAll('aaa', 'a', 'aa'), 'aaaaaa'); // 不反覆掃描插入值
14
assert.equal(replaceLiteralAll('abc', 'x', ''), 'abc');
15
assert.equal(replaceLiteralAll('a-a', 'a', ''), '-');
16
assert.throws(() => replaceLiteralAll('abc', '', 'x'), RangeError);
17
assert.throws(() => replaceLiteralAll('abc', 'a', null), TypeError);
18
assert.throws(() => 'abc'.replaceAll(/a/, 'x'), TypeError);
19
assert.equal('aba'.replaceAll(/a/g, () => '$&'), '$&b$&');
20
console.log('literal replacement contract: PASS');