WebStorm Structural Search & Replace 速查表

核心概念

基于语法树而非纯文本的模式搜索与替换。

Template：代码结构模式，包含字面量与变量
$Variable$ ：占位符，匹配特定代码节点
Filters：对变量的文本、类型、次数或脚本约束

参考文档： https://www.jetbrains.com/help/webstorm/structural-search-and-replace.html

入口与适用场景

Edit | Find | Search Structurally：结构化搜索
Edit | Find | Replace Structurally：结构化替换
适用于 API 迁移、批量重构、编码规范检查
当正则难以表达代码结构时优先使用 SSR

模板创建流程

输入最小可匹配的代码片段作为模板
将可变部分替换为 $var$ 占位符
点击变量或打开 Filters 面板设置约束
通过结果预览确认匹配范围
必要时保存模板或保存为 Inspection

变量与基础语法

$var$ ：匹配任意表达式或语句
"$text$"：匹配字符串字面量
/* $comment$ */：匹配注释内容
class $Name$：匹配类定义
function $name$($args$)：匹配函数定义

变量名称自由，但应与语义一致，便于复用。

变量修饰符与过滤

Text/Regex：正则限制文本内容
Type：限定类型或语法元素
Count：限定出现次数，如 0..*
Script：使用 Groovy/BeanShell 进行复杂判断

过滤器可作用于单个变量，也可组合使用。

常见模板：函数与调用

查找 console.log 调用

console.log($args$);

将 $args$ 的 Count 设为 0..*。

查找超过 3 个参数的函数

function $name$($params$) {
  $body$
}

将 $params$ Count 设为 4..*。

查找特定实例的方法调用

$instance$.$method$($args$)

给 $instance$ 设置 Text 或 Script 过滤。

常见模板：语句与结构

空的 try-catch

try {
  $tryStmt$;
} catch ($err$) {
}

将 $tryStmt$ Count 设为 0..*。

没有花括号的 if

if ($cond$) $stmt$;

用 Script 排除块语句。

常见模板：HTML/JSX

缺少 alt 的 img

<img $attrs$ />

Script 判断 alt= 不存在。

包含特定属性的组件

<MyComponent $prop$ />

Text 设为 deprecated.*。

结构化替换

var 替换为 const

搜索：

var $x$ = $y$;

替换：

const $x$ = $y$;

参数顺序调整

搜索：$obj$.make($a$, $b$)

替换：$obj$.create($b$, $a$)

替换后重新格式化

可在 Replace 对话框中启用 Reformat。

脚本约束

__context__：当前匹配的 PSI 节点
__context__.text：匹配文本内容
__context__.parent：父节点访问

常用脚本片段

__context__.text.contains("foo")
__context__.text.length() > 50
__context__.parent instanceof JSIfStatement

保存与复用

Save Template：保存常用模板
Save as Inspection：转为检查项并持续提示
模板可在搜索窗口中直接复用

分享与导入导出

模板可复制为 XML 进行分享
在 SSR 对话框中粘贴 XML 可导入
导入会恢复变量与范围设置

结果确认与范围

在 Find 工具窗预览匹配结果
替换可逐条或批量应用
范围建议：Project / Module / Directory / Changed Files