RegExp.escape() 怎麼用？動態建立 JavaScript 正則表達式先處理輸入

為什麼手寫 replace 不夠#

很多舊範例會用一段 replace 把 . * + ? ^ $ { } ( ) | [ ] \ 前面加反斜線。這類程式碼常漏掉 /、連字號、換行或其他需要在不同 regex context 特別處理的字元，也容易在字串前面再接上 \1、\u 等 escape 時產生歧義。

RegExp.escape() 的規則不只是「每個特殊字元前面加反斜線」：

因此，不要把輸出長相當成「醜陋但多餘」。例如：

1
RegExp.escape("foo-bar.*");
2
// "\\x66oo\\x2dbar\\.\\*"

前面的 f 變成 \x66，連字號變成 \x2d，這正是 API 要避免相鄰 escape 改變語意的地方。

動態搜尋的完整寫法#

假設頁面有一個搜尋框，需求是找出包含使用者輸入的文字；輸入應該只代表 literal，不應該變成 regex：

1
function containsKeyword(text, keyword) {
2
  const pattern = new RegExp(RegExp.escape(keyword), "iu");
3
  return pattern.test(text);
4
}
5

6
containsKeyword("Release v26.9.0", "v26.9.0"); // true
7
containsKeyword("a+b", "a+b"); // true

如果要組合一小段固定 regex 語法，也只逃逸變動的部分，不要把整個 pattern 都包起來：

1
function matchesHost(url, host) {
2
  const literalHost = RegExp.escape(host);
3
  const pattern = new RegExp(
4
    "^https?://" + literalHost + "(?=/|$)",
5
    "i",
6
  );
7
  return pattern.test(url);
8
}
9

10
matchesHost("https://example.com/docs", "example.com"); // true
11
matchesHost("https://exampleXcom/docs", "example.com"); // false

這種寫法讓 ^https?:// 和 lookahead 保留程式設計者定義的語意，只有 host 被視為外部 literal。若 host 也來自不可信輸入，仍需在 URL parser、允許的 domain 與 regex 三個層次分別驗證。

encodeURIComponent() 不能代替 RegExp.escape()#

encodeURIComponent() 的目標是 URI component，不是 regex pattern。它會產生 % 編碼，無法保證輸入在 new RegExp() 裡代表原字串；反過來，regex escape 也不能拿來做 URL encoding。

1
const keyword = "a+b/c";
2

3
new RegExp(RegExp.escape(keyword), "u"); // 搜尋 literal "a+b/c"
4
encodeURIComponent(keyword);              // URL 使用的編碼，不是 regex escape

兩者要依資料會進入的語法層次分開處理。若一段輸入先進 URL、再進 regex，應先設計清楚每一層的資料邊界，不要重複或錯用另一種 encoder。

舊環境的 feature detection 與 fallback#

RegExp.escape() 是較新的標準 API。若程式需要跑在尚未提供它的 runtime，先做 feature detection：

1
function escapeRegexLiteral(value) {
2
  if (typeof RegExp.escape === "function") {
3
    return RegExp.escape(value);
4
  }
5

6
  throw new Error(
7
    "RegExp.escape() is unavailable; load an approved polyfill before building a pattern.",
8
  );
9
}

正式專案有兩個選擇：

1. 將支援矩陣提高到提供 RegExp.escape() 的 runtime。
2. 依專案的 browser／Node 版本，載入經維護、經測試和資安審查的 polyfill，並把它加入相容性測試。

不要在 fallback 裡臨時補一個只處理 .、* 和 ? 的 replace。它可能在今天的範例通過，卻在連字號、slash、開頭字元或 Unicode 輸入上改變語意。

可重複的最小驗證#

升級 Node.js、瀏覽器或 polyfill 後，可以用一個包含不同邊界的字串做 smoke test：

1
node -e 'const value = "foo-bar.*"; console.log(typeof RegExp.escape, RegExp.escape(value));'

預期在支援的 runtime 中會得到 function，以及類似 \x66oo\x2dbar.* 的輸出。接著再測試：

• 輸入開頭是 ASCII 英文字母或數字。
• 輸入包含 -、/、\、.、*、?、( 和 )。
• 輸入包含換行、emoji、非 ASCII 字元與 lone surrogate（若應用程式會接收這些資料）。
• pattern 放在固定語法前後時，仍只匹配 literal，而不會擴大範圍。

這個檢查只能確認 API 和基本輸出，不能代替應用程式的資源限制。若 pattern 仍可能很大，或輸入與固定語法組合後可能造成高成本回溯，還是要設長度限制、測試 worst case，並考慮避免把 regex 當成搜尋引擎。

用斷言檢查完整字面值與 Unicode 邊界#

只看 escape 輸出，還不能確認組合後的 pattern 符合需求。以下可存成 escape-check.mjs，在提供 RegExp.escape() 的 Node 環境執行 node escape-check.mjs：

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

3
const samples = [
4
  'foo-bar.*', 'a+b/c', '中文😀',
5
  'line\nbreak', '\u2028', '\uD800', '',
6
];
7

8
for (const value of samples) {
9
  const pattern = new RegExp('^(?:' + RegExp.escape(value) + ')$', 'u');
10
  const match = pattern.exec(value);
11
  assert.equal(match?.[0], value);
12
  assert.equal(pattern.test('x' + value), false);
13
  assert.equal(pattern.test(value + 'x'), false);
14
}
15
assert.equal(new RegExp(RegExp.escape('a+b'), 'u').test('aaab'), false);
16
assert.equal(new RegExp(RegExp.escape('Sale'), 'u').test('sale'), false);
17
assert.equal(new RegExp(RegExp.escape('Sale'), 'iu').test('sale'), true);
18
console.log('escape checks passed');

本次維護在 Node.js v24.13.0 執行這組斷言，全部通過；沒有測試瀏覽器或外部 polyfill。測試涵蓋空字串、換行、emoji、行分隔符與 lone surrogate，也確認正則語法 + 沒有變成量詞。MDN 與 ECMAScript 規格 說明了這些字元的 escaping 規則。

這裡用 u 旗標檢查原始大小寫；前面的搜尋框範例使用 iu，因此會接受大小寫變體。escape 決定輸入是字面值，flags 決定匹配方式。 若需求是整段輸入完全相同，除了固定前後邊界，還應確認匹配結果覆蓋完整字串；若加上 m 旗標，^ 與 $ 會改成逐行邊界，可能只匹配多行輸入中的其中一行，不能拿它宣稱整段字串完全相等。只需字串相等時直接用 === 更清楚。

若同一個 lazy-loaded 搜尋功能還要處理載入失敗，可另參考 動態 import 的有限重試；不要把模組載入錯誤和搜尋輸入錯誤共用一套修復邏輯。

結論#

當需求是「把外部字串當成正則表達式裡的 literal」時，優先使用 RegExp.escape()，再把結果放進 new RegExp()。它不只是替特殊字元加反斜線，也處理開頭 ASCII 字元、punctuator、slash 與 Unicode 邊界。舊環境先做 feature detection，必要時使用經審查的 polyfill；不要用 encodeURIComponent() 或不完整的手寫 replace 代替。

常見問題#