VS Code Python 自动导包失效排查笔记

问题现象

在 Python 文件中输入未导入的模块名，例如 os，补全列表能够出现 os，但选中后文件顶部没有自动添加：

python 复制代码

import os

原因

VS Code 中可能同时存在两类外观相似的补全候选：

普通单词补全
- 根据当前文件或其他已打开文件中的文字生成候选。
- 只插入选中的文本，例如 os。
- 不理解 Python 的模块和导入关系，因此不会添加 import。
Pylance 语义补全
- 由 Python 语言服务器根据代码语义生成。
- 接受候选时既插入模块名，又在文件顶部添加导入语句。
- 候选旁通常会显示模块图标、来源路径或自动导入提示。

本次问题中，自动导入功能本身已经开启，但普通单词候选与 Pylance 候选重名。实际选中的是普通单词候选，所以只补全了 os，没有添加 import os。

解决方法

在项目的 .vscode/settings.json 中启用 Pylance 自动导入和索引，并只对 Python 文件关闭普通单词补全：

json 复制代码

{
    "python.analysis.autoImportCompletions": true,
    "python.analysis.indexing": true,
    "[python]": {
        "editor.wordBasedSuggestions": "off",
        "editor.suggest.showWords": false,
        "editor.quickSuggestions": {
            "other": "on",
            "comments": "off",
            "strings": "off"
        },
        "editor.suggestOnTriggerCharacters": true,
        "editor.acceptSuggestionOnEnter": "on",
        "editor.inlineSuggest.suppressSuggestions": false
    }
}

关键配置说明

python.analysis.autoImportCompletions：让 Pylance 在补全未导入的模块、类或函数时提供自动导入操作。

python.analysis.indexing：让 Pylance 索引项目代码、Python 标准库以及当前解释器环境中的第三方包。

editor.wordBasedSuggestions: "off"：关闭普通单词补全，防止它排在同名的 Pylance 候选前面。

editor.suggest.showWords: false：隐藏单词类型的候选，进一步避免误选。

[python]：表示这些编辑器设置只对 Python 文件生效，不影响项目中的其他语言。

editor.inlineSuggest.suppressSuggestions: false：出现 AI 灰色行内建议时，仍允许显示正常的 Pylance 补全列表。

为什么接受候选后能自动导包

Pylance 的自动导入候选包含两个编辑动作：

text 复制代码

光标位置：插入 os
文件顶部：插入 import os

普通单词补全只有第一个动作，因此两种候选虽然显示的文字相同，行为却不同。

验证方法

新建或打开一个 Python 文件，确保文件中没有 import os。
输入 os；如果补全列表没有出现，按 Ctrl+Space。
选择带模块图标或模块来源的 os 候选。
按 Enter 接受候选。
检查文件顶部是否自动出现 import os。

如果设置没有立即生效，可以按 Ctrl+Shift+P，执行：

text 复制代码

Developer: Reload Window

也可以执行：

text 复制代码

Python: Restart Language Server

仍然无法自动导入时的排查顺序

确认已安装并启用 Microsoft Python 和 Pylance 扩展。
确认当前文件的语言模式是 Python。
确认 VS Code 选择了正确的 Python 解释器。
确认需要导入的第三方包安装在当前解释器环境中。
在"输出"面板选择 Pylance，确认索引已经完成且没有启动错误。
使用 Ctrl+. 检查是否存在"添加导入"快速修复。
区分 Pylance 弹出候选和 AI 灰色行内补全；AI 补全通常只插入代码文本，不会可靠地添加导入语句。

恢复普通单词补全

如果以后希望重新启用普通单词补全，可以删除下面两项：

json 复制代码

"editor.wordBasedSuggestions": "off",
"editor.suggest.showWords": false

或者改成：

json 复制代码

"editor.wordBasedSuggestions": "currentDocument",
"editor.suggest.showWords": true

恢复后，普通单词候选可能再次与 Pylance 候选重名。选择候选时需要确认它是否显示模块来源或自动导入提示。

作用范围

本次配置写在项目的 .vscode/settings.json 中，因此只影响当前项目；其中 [python] 内的设置只影响 Python 文件。其他 VS Code 项目和其他编程语言不会受到影响。