Python重命名必须用Rename Symbol（F2），依赖Pylance语义分析；失效主因是语言服务未接管、文件类型错误、解释器未选、pyproject.toml缺失、光标位置不当或动态访问。
Python 重命名靠的是 Rename Symbol，不是 F2 文本替换
VSCode 对 Python 变量的全局重命名，必须用 Rename Symbol（快捷键 F2 或右键菜单），它依赖 Pylance 提供的语义分析，不是简单搜字符串。按了没反应、只改了局部、漏掉 import 行——基本都说明语言服务没接管成功。
常见失效场景：
- 文件是
.txt或未识别为 Python（右下角显示 “Plain Text” 而非 “Python”） - 没选中解释器：命令面板运行
Python: Select Interpreter，指向含pyproject.toml或setup.py的环境 - 项目根目录缺失
pyproject.toml，Pylance 默认降级为单文件模式，跨文件引用不识别 - 光标停在字符串里、注释里、或
getattr(obj, "user_name")这类动态访问上——这些根本不会被Rename Symbol触发
from import 的函数名重命名为什么不变？
Python 的 Rename Symbol 默认只更新当前符号的「定义 + 本文件内引用」，from module import func 中的 func 是导入绑定，不是定义；它不会自动去改 module.py 里的 def func():，更不会反向更新所有 import 行。
实操建议：
立即学习“Python免费学习笔记（深入）”；
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
- 把光标落在
module.py里那个原始def func()上，再按F2—— 这样才能触发对导出符号的重命名 - 对显式
import行，重命名后手动检查：用Ctrl+Shift+F搜旧名字，关掉正则，避免匹配到function这类子串 - 禁用
from module import *：这种写法会让 Pylance 完全无法追踪符号来源，重命名基本不可用
重命名后类型提示没更新？检查路径解析是否断链
Python 类型提示（如 def process(user: User) -> list[Item]:）能否被正确重命名，取决于 Pylance 能否定位 User 和 Item 的定义位置。如果它们来自本地模块但用了相对导入、或来自 src/ 子目录却没配 pyproject.toml 的 [tool.pyright] 路径映射，类型就“丢失”了。
验证方式：
- 把光标停在
User上，看状态栏是否显示1 definition, 2 references - 没有？打开开发者工具（
Developer: Toggle Developer Tools），查 Console 里有没有Failed to resolve import类报错 - 补救：在
pyproject.toml加[tool.pyright]块，配extraPaths = ["src"]或include = ["src/**"]
别信“一键全局”，动态访问和字符串拼接永远绕不开
Rename Symbol 再强，也处理不了静态分析无法覆盖的情况。比如：obj[variable_name]、getattr(obj, "user" + "name")、eval("user_name = 42")——这些地方不会出现在重命名预览里，也不会被自动更新。
遇到这类代码，必须手动处理：
- 先用
Rename Symbol更新所有静态引用 - 再用
Ctrl+Shift+F全局搜旧变量名，人工核对每处是否属于动态访问 - 搜的时候加引号限定上下文，例如搜
"user_name"或\.get\("user_name"\)，避免误伤
真正麻烦的从来不是怎么点 F2，而是你得先判断哪些地方根本不能靠点 F2。
