必须装pylance，仅python扩展不支持跨文件重命名和提取函数；需配置"python.languageserver": "pylance"、存在pyproject.toml或pyrightconfig.json，并确保光标停在声明处触发语义重构。

必须装 Pylance，只装 Python 扩展不够——Pylance 是当前唯一能稳定支持跨文件重命名、提取函数和变量语义分析的 Python 语言服务器。Jedi 或其他后端在 VSCode 中已基本退居备用角色，尤其对类型提示、作用域判断和引用追踪支持不足。

确认 Pylance 是否真正就位

右下角状态栏显示 Python 不代表语言服务就绪；常见失效现象包括：F2 只改当前文件、Ctrl+. 没有 Extract to function、右键无 Refactor 子菜单。

• 打开一个 .py 文件，将光标停在函数名上，按 F2 —— 若弹出输入框且预览列出多个文件中的引用，说明 OK
• 若只改当前文件或报 Renaming 'xxx' is not available here，检查：settings.json 中是否设置了 "python.languageServer": "Pylance"
• 确保项目根目录存在 pyproject.toml 或 pyrightconfig.json（哪怕为空），否则 Pylance 无法启用完整语义分析
• 打开开发者工具（Ctrl+Shift+P → Developer: Toggle Developer Tools），看 Console 是否有 Pylance initialization failed 或路径解析错误

提取函数时选区必须“语法合法且自包含”

VSCode 不做逻辑校验，只把选中内容原样包裹进新函数体，因此失败几乎全是选区问题。

python全能编程助手

SkillSub Pro - Python 题解与代码注释双功能技能功能概述SkillSub Pro - Python 题解与代码注释双功能技能是一项面向实际任务的技能，主要用于SkillSub Pro 是一个 Python 题解生成与代码注释的 双功能合体技能 ，专为学生、算法学习者和开发者设计；✅ 一个技能，两种用途 ：；核心要点📝 题解模式 ：输入题目/题号，自动生成完整 Python 题解（含详细注释、解题思路、复杂度分析）；💬 注释模式 ：输入 Python 代码，自动添加详细中。它将相关步骤、

下载

• 不能以 return 开头（顶层 return 会被忽略，导致签名错乱）
• 不能跨缩进层级：比如选中 if 块内一部分 + 外层代码，会报 Cannot extract to function
• Python 中不能含未赋值的局部变量（如 count += 1 但前面没 count = 0），Pylance 推不出参数
• 提取后立即检查：新函数是否带 async？外层 self 或闭包变量是否被自动识别为参数？参数名是 arg0 还是合理命名？

重命名不是文本替换，依赖符号定义位置

光标必须落在变量/函数的**声明处**（如 def foo(): 的 foo 上），而非调用处。否则 Pylance 无法定位符号定义，只会退化为局部替换。

• 对类成员重命名，需光标停在 def method(self): 的 method 上，不能停在 obj.method() 的 method
• 预览窗口里列出的修改项可取消勾选——特别适用于模板字符串中同名变量、日志字段等非代码引用
• 别用 Ctrl+H 替换短名（如 data、res），极易误改字符串和注释；F2 / Shift+F6 才走语义路径
• 动态属性访问（如 getattr(obj, var_name)）永远不会被重命名覆盖，这是设计使然，不是 bug

最易被忽略的是：Pylance 的重构能力高度依赖项目配置文件的存在与位置。没有 pyproject.toml，它默认关闭跨文件引用索引；即使插件装了、设置开了，也只当单文件编辑器用。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！