Shift+F6重命名默认不修改注释和字符串中的文本；需勾选“Search in comments and strings”才能匹配注释及引号内完整单词，若还需处理PHPDoc等裸文本，则须同时勾选“Search for text occurrences”。
Refactor → Rename 时勾选 Search in comments and strings
默认情况下，Shift+F6 重命名只改语义引用（如变量、方法调用、类名），不会碰注释和字符串里的同名文本。但如果你的代码里有硬编码路径、配置键名或示例值写在注释中（比如 // config key: $db_host 或 'table_name' => 'user_log'），就得手动开启扫描。
操作很简单：光标停在要重命名的符号上 → 按 Shift+F6 → 输入新名后，**务必勾选对话框底部的 “Search in comments and strings”** → 再点 Refactor。PhpStorm 就会把注释块和双/单引号内的匹配字符串一并列进预览列表。
- 这个选项不是默认开启的，漏勾就等于主动放弃补全注释和字符串里的上下文
- 勾选后性能略降，尤其大项目里含大量 JSON 或 SQL 字符串时，建议先在小范围试一次
- 它只匹配完整单词（类似 Words only），不会把
$user_id里的user单独拎出来替——除非你额外勾了 “Search for text occurrences”
Search for text occurrences 是什么作用
Search for text occurrences 是 Shift+F6 重命名对话框里的另一个开关，和 “Search in comments and strings” 是并列关系，不是子选项。它决定是否把纯文本层面的出现位置也纳入重构范围。
典型场景：一个常量名 MAX_RETRY 被写在 PHPDoc 的 @param int $retryCount [0, MAX_RETRY] 里，或者出现在 Twig 模板的注释 {# MAX_RETRY times #} 中。这些地方既不是 PHP 变量，也不在字符串值里，而是“裸文本”。这时必须同时勾选这两个选项，才能被识别。
立即学习“PHP免费学习笔记（深入）”；
- 只勾
Search in comments and strings→ 不会匹配 PHPDoc 参数说明里的MAX_RETRY - 只勾
Search for text occurrences→ 不会动// retry limit: MAX_RETRY这种注释行 - 两个都勾 → 所有上下文类型都被覆盖，但预览列表会变长，需逐条确认是否该改
为什么有时勾了也没搜到注释里的内容
常见原因不是功能失效，而是 PhpStorm 没把目标文件纳入索引范围，或当前文件未被识别为 PHP 上下文。
- 检查右下角状态栏是否还在显示
Indexing…，没索引完的文件不会参与任何语义搜索 - 确认文件后缀是
.php（不是.inc或无后缀），且文件类型被识别为 “PHP File”，右键文件 →Override File Type可修正 - 注释里如果混用了中文标点或全角空格（如
／／或 - 如果注释嵌套在 /* */ 多行块中，且跨了太多行（比如 200 行以上），部分版本会跳过扫描——这不是 bug，是性能保护机制
替代方案：用 Replace in Path 补漏
当 Shift+F6 勾选后仍漏掉某些注释或字符串（比如模板文件、配置 YAML、SQL 文件中的硬编码名），就该切到文本层补救。
用 Ctrl+Shift+R 打开全局替换 → 填入原名和新名 → 在 File mask 栏指定范围（如 *.{php,twig,yaml}）→ **务必勾选 “Match case” 和 “Words only”** → 先点 Find 预览所有匹配项。
- 不勾
Words only可能导致user替换时把username切成adminname -
File mask必须带*和扩展名，填php或.php都无效 - 注释里的内容属于纯文本，Replace in Path 能扫到，但无法区分语义——所以每处都要人工核对是否该改
复杂点在于：注释和字符串里的名字，有些该随重构一起变（如配置键名），有些不该（如文档示例、历史备注）。没有全自动方案，只有靠勾选组合 + 预览确认 + 手动兜底。
