VS Code配置Python自动补全：安装Pylance与基础设置

图 0：VS Code Python 智能感知与 Pylance 补全环境

一、Pylance 与 Python 扩展的协作机制

VS Code 本身是一个通用代码编辑器，并不内置针对 Python 语言的静态语法树分析器。要获得高效的代码补全，编辑器依赖于微软官方制定的语言服务器协议（Language Server Protocol，简称 LSP）。

在实际运作中，Python 的补全体验由两个扩展协同提供：

• Python 核心扩展（ms-python.python）：主要作为“调度中枢”，负责检测系统中的虚拟环境（如 .venv、Conda、pyenv）、选择解释器、调度调试器（Debug Adapter）以及管理单元测试。
• Pylance 扩展（ms-python.vscode-pylance）：作为实际的“语言服务器（Language Server）”，它内嵌基于 TypeScript 开发的高性能 Pyright 分析引擎，负责快速构建抽象语法树（AST）、索引已安装的第三方库（site-packages）、结合 Typeshed 类型存根实现推断与补全。

图 1：VS Code、Python 核心扩展与 Pylance 语言服务器的分工协同架构

理解两者的分工有助于明确配置目标：Python 扩展负责把正确的 Python 环境路径告诉 Pylance，而 Pylance 负责根据该环境中的包结构产出实时的补全候选列表与类型警告。

二、安装 Pylance 与指定语言服务器

配置自动补全不需要复杂的外部工具链，按照标准流程分为四个明确步骤：

图 2：Pylance 安装与环境启用四步操作流程

1. 在扩展市场安装 Pylance

打开 VS Code，使用快捷键 Ctrl+Shift+X（macOS 为 Cmd+Shift+X）进入扩展面板。在搜索框中输入 Pylance，找到由 Microsoft 发布的插件（标识符为 ms-python.vscode-pylance），点击 Install 完成安装。若尚未安装官方 Python 扩展，通常在安装 Pylance 时会自动引导安装。

2. 选择 Python 解释器（关键步骤）

Pylance 必须知道当前项目依赖哪个 Python 环境才能正确定位标准库和第三方模块。

1. 使用快捷键 Ctrl+Shift+P（macOS 为 Cmd+Shift+P）调出全局命令面板。
2. 输入并选择 Python: Select Interpreter。
3. 在弹出的列表中，优先选择当前项目工作区下的虚拟环境（通常标记为 ./.venv/bin/python 或 .\.venv\Scripts\python.exe）。若当前项目未创建虚拟环境，则选择系统的全局 Python 解释器。
4. 选定后，VS Code 右下角状态栏会显示当前所使用的 Python 版本及环境名称。

3. 在设置中显式指定语言服务器

尽管当前版本的 Python 扩展在检测到 Pylance 时会自动将其设为默认引擎，但显式声明能够避免因旧配置残留或多插件冲突导致的退化（如回退至 Jedi 或 None）。

按 Ctrl+, 打开设置面板，在搜索栏输入 python.languageServer，将下拉选项设置为 Pylance。

三、优化补全体验的关键基础设置

Pylance 开箱即可工作，但通过对 settings.json 进行针对性调优，可以显著改善日常开发的流畅度。打开设置文件的方式为：按 Ctrl+Shift+P，输入 Preferences: Open User Settings (JSON) 打开全局配置，或输入 Preferences: Open Workspace Settings (JSON) 仅对当前项目生效。

图 3：Pylance 核心参数设置与应用场景

1. 设置类型检查严格度：typeCheckingMode

Pylance 继承了 Pyright 强大的静态类型检查能力，提供了三个级别：

2. 开启自动导入补全：autoImportCompletions

将 python.analysis.autoImportCompletions 设置为 true。当你在编写代码时键入一个尚未在当前文件导入的模块或函数名（例如 Path、requests），Pylance 会在补全列表中提示该符号来源，并在你回车选择后，自动在文件顶部插入对应的 from pathlib import Path 语句，减少频繁来回滚动光标的时间。

3. 指定附加寻包路径：extraPaths

在很多工程中，源码往往放在 src 或 lib 等子目录下，直接 import my_module 时 Pylance 可能会报 reportMissingImports 警告，且无法提示该模块内的函数。通过 python.analysis.extraPaths 显式添加子目录，可彻底解决该问题：

"python.analysis.extraPaths": [
    "./src",
    "./common"
]

4. 启用内联类型批注提示：inlayHints

Pylance 支持在编辑器文本中间以浅灰色字体展示编译器推断出来的类型：

• python.analysis.inlayHints.variableTypes: true：展示未经显式声明变量的推断类型。
• python.analysis.inlayHints.functionReturnTypes: true：展示函数的推断返回值类型。

推荐的基础配置模板

将以下配置片段加入工作区 .vscode/settings.json 文件中即可生效：

{
    "python.languageServer": "Pylance",
    "python.analysis.typeCheckingMode": "basic",
    "python.analysis.autoImportCompletions": true,
    "python.analysis.indexing": true,
    "python.analysis.inlayHints.variableTypes": true,
    "python.analysis.inlayHints.functionReturnTypes": true,
    "editor.suggestSelection": "first",
    "editor.quickSuggestions": {
        "other": true,
        "comments": false,
        "strings": true
    }
}

四、验证补全效果与快捷交互

完成上述安装与配置后，可通过建立测试文件 test_completion.py 验证补全工作状态：

1. 标准库补全验证：输入 import math，换行后输入 math.，应立即弹出包含 isqrt、sin、pi 等方法和属性的浮窗，并附带函数签名与官方 Docstring 说明。
2. 第三方库验证：在已安装相应依赖的虚拟环境中输入 import requests，换行输入 requests.，应正确列出 get、post 等方法及参数提示。
3. 常用辅助快捷键：
   • 手动唤出补全列表：Ctrl+Space（Windows/Linux）或 Cmd+I（macOS）。
   • 查看当前光标处符号的文档提示：Ctrl+K Ctrl+I（Windows/Linux）或鼠标悬停（Hover）。
   • 重新唤起参数签名提示：Ctrl+Shift+Space。

五、补全失效与异常排查指南

如果在实际使用中发现补全没有弹出、一直显示“Loading...”或者提示出现偏差，可依序排查以下常见根因：

图 4：Python 自动补全失效排查决策流程