Python变量重命名必须用F2触发Rename Symbol而非文本替换，因其实现依赖Pylance语义分析；失效常见原因包括状态栏显示“Plain Text”、未选解释器、缺少pyproject.toml、光标位置不当或动态访问等。
重命名 Python 变量必须用 Rename Symbol，不是文本替换
VS Code 的 Python 重命名功能完全依赖 Pylance（或 Pyright）提供的语义分析，F2 触发的是 Rename Symbol 命令，不是搜字符串。按了没反应、只改了当前文件、漏掉 import 行——基本说明语言服务没接管成功。
常见失效点：
- 右下角显示 “Plain Text” 而非 “Python”：点它 → 选择 “Python”
- 没选解释器：命令面板运行
Python: Select Interpreter，指向含pyproject.toml或setup.py的环境 - 项目根目录没有
pyproject.toml：Pylance 默认降级为单文件模式，跨文件引用不识别 - 光标停在字符串、注释、或
getattr(obj, "user_name")这类动态访问上：这些位置根本不会触发语义重命名
from module import func 重命名后 module.py 里不更新？
这是设计行为，不是 bug。Rename Symbol 默认只作用于「当前符号的定义 + 本文件内所有引用」。而 from module import func 中的 func 是导入绑定，不是定义；它不会反向去改 module.py 里的 def func():。
正确做法：
立即学习“Python免费学习笔记（深入）”；
- 把光标落在
module.py中那个原始def func()上，再按F2 - 重命名后，手动检查
import行是否同步更新：用Ctrl+Shift+F搜旧名字，关掉正则，避免匹配到function这类子串 - 禁用
from module import *：这种写法会让 Pylance 完全无法追踪符号来源，重命名基本不可用
类型提示里的类名重命名失败，大概率是路径解析断链
比如 def process(user: User) -> list[Item]:，重命名 User 后类型提示没变，往往不是重命名本身出错，而是 Pylance 找不到 User 的定义位置。
典型原因：
- 用了相对导入但没配路径映射，例如
from ..models import User，但项目结构在src/下 -
pyproject.toml缺少[tool.pyright]块，或没加extraPaths = ["src"] - 状态栏没显示 “1 definition, 2 references”：把光标停在
User上就能看到
验证方式：打开开发者工具（Developer: Toggle Developer Tools），查 Console 里有没有 Failed to resolve import 类报错。
动态访问和字符串拼接永远绕不开人工检查
Rename Symbol 再强，也处理不了静态分析覆盖不了的地方。这些地方不会出现在预览列表里，也不会被自动修改：
obj[variable_name]getattr(obj, "user" + "name")eval("user_name = 42")- 日志字符串里硬编码的
"user_name"
真正容易被忽略的是：重命名后，你得自己扫一遍这些上下文。尤其当变量名出现在字典 key、JSON 字段、SQL 查询字符串或配置项中时，F2 完全无感——它只认语法树里的标识符节点。
