检查扩展与基础设置

VSCode 的 Python 自动 import 补全依赖官方扩展（Pylance 或 Python 插件）。打开扩展面板，搜索并安装 Microsoft 发布的 Python 扩展。安装后打开任意 .py 文件，输入标准库名称如 os 或 json，如果下拉提示自动出现并附带 import 语句，说明基础功能正常。如果补全没出来，先确认扩展是否已启用，然后检查设置项 python.analysis.autoImportCompletions 是否为 true。这个选项默认是开启的，但如果你之前手动关闭过或使用过旧版设置，可能被覆盖。另外，确保 VSCode 状态栏左下角显示了你期望的 Python 解释器版本，如果显示的是“选择解释器”，说明还没指定工作区环境，自动补全可能找不到模块。

要确认 VSCode 的 Python 自动 import 补全是否可用，首先检查是否安装了 Python 扩展（如 Pylance 或 Python 插件）。在扩展面板中搜索并安装 Microsoft 官方 Python 扩展后，打开任意 Python 文件，输入一个标准库或已安装第三方库的名称（如 `os` 或 `numpy`），观察是否出现下拉提示并自动添加 import 语句。若未出现，则需检查设置中 `python.analysis.autoImportCompletions` 是否已启用，该选项默认开启。此外，确保工作区已正确选择 Python 解释器，可通过状态栏左下角的解释器版本标识确认。

在 VSCode 中启用 Python 自动 import 补全的核心配置是设置 `python.analysis.autoImportCompletions` 为 `true`。打开设置（Ctrl+,），搜索“auto import”，找到“Auto Import Completions”项并勾选。若需要更细粒度控制，可编辑 `settings.json` 添加 `"python.analysis.autoImportCompletions": true`。同时建议开启 `"python.analysis.typeCheckingMode": "basic"` 以获得更准确的类型推断，从而提升补全质量。配置后重启 VSCode 或重新加载窗口使设置生效。

核心配置：启用自动 import

在 VSCode 中启用 Python 自动 import 补全的核心配置是设置 python.analysis.autoImportCompletions 为 true。打开设置（Ctrl+,），搜索“auto import”，找到“Auto Import Completions”项并勾选。若需要更细粒度控制，可编辑 settings.json 添加 "python.analysis.autoImportCompletions": true。同时建议开启 "python.analysis.typeCheckingMode": "basic" 以获得更准确的类型推断，从而提升补全质量。配置后重启 VSCode 或重新加载窗口使设置生效。

这段配置适用于大多数场景，但如果你使用远程开发容器或 WSL，需要确认远程机器上的设置也同步更新。有些团队会通过工作区 .vscode/settings.json 统一管理，这种情况下每个成员打开项目都会自动应用。另外，Pylance 扩展还会读取 pyproject.toml 或 setup.cfg 中的类型检查配置，但自动 import 不受影响。

验证补全是否生效

配置完成后，可通过一个简单测试验证自动 import 补全是否正常工作。创建一个新的 Python 文件，输入 pathlib.Path，如果补全弹出并自动在文件顶部生成 from pathlib import Path 语句，则说明配置成功。若补全未触发，检查文件是否为 Python 语言模式（右下角显示“Python”），并且已安装的 Python 环境包含目标模块。另外，在输入导入语句后，注意观察是否有多余的逗号或空行，若文件编码非 UTF-8 可能导致解析异常，应确保文件以 UTF-8 保存。

这个测试案例使用了标准库 pathlib，所以不需要额外安装第三方包。如果你测试第三方库（比如 pandas.DataFrame），需要先确认环境中确实安装了该库。补全提示时可能会列出多个同名模块（例如 os.path 和 pathlib 都有的 Path），你需要手动选择正确的来源。如果补全没弹出，可以按 Ctrl+Space 手动触发，仍无效则回到上一步检查设置。

处理虚拟环境与自定义路径

一个常见的问题是虚拟环境中的模块无法被自动补全识别。此时需确认 VSCode 已选中正确的虚拟环境：通过命令面板（Ctrl+Shift+P）执行“Python: Select Interpreter”，选择对应虚拟环境下的 Python 解释器。另外，如果模块安装在自定义路径（如 site-packages 的子目录），需要在 settings.json 中添加 "python.autoComplete.extraPaths": ["自定义路径"]。注意，若使用 Pylance，还需要确保 python.analysis.extraPaths 设置一致。还有一个陷阱：自动 import 可能同时推荐多个同名模块，需手动选择正确的来源。

比如你在项目里用了 venv，激活后通过 pip 安装了 requests，但补全时找不到。这时候去状态栏点击解释器版本，选择 ./venv/bin/python 即可。如果项目使用了 conda 环境，同样需要先激活对应环境。对于自定义路径，比如你把一些库放在 lib/mylibs 下，那么在 settings.json 里添加 "python.analysis.extraPaths": ["lib/mylibs"]，同时也要确认 python.autoComplete.extraPaths 一致，因为有些旧版本扩展只认后者。注意这两个设置的区别：python.analysis.extraPaths 是 Pylance 使用的路径，而 python.autoComplete.extraPaths 是旧版 Jedi 语言服务器的配置。如果你同时安装了 Pylance，建议两边都配置，避免遗漏。

避免导入冗余与维护一致性

自动 import 补全虽然便捷，但过度依赖可能导致代码中出现不必要或未使用的 import 语句。例如，输入 os.path.join 时，VSCode 可能同时建议 from os.path import join 和 import os.path，若选择前者，后续使用 os 的其他功能又需额外 import，造成冗余。建议在代码提交前运行 linter（如 flake8）检查未使用的 import，或使用 VSCode 内置的“组织导入”功能（右键菜单）自动清理。另外，自动 import 不会处理相对导入与绝对导入的混用，需开发者自行维护导入风格的一致性。

如果你有团队统一的导入风格（比如绝对导入优先），可以在项目根目录配置 pyproject.toml 或 isort.cfg，然后配合 isort 插件在保存时自动整理 import。VSCode 也可以配置保存时执行 editor.codeActionsOnSave 来运行 source.organizeImports，但要注意这个操作是全局的，可能会覆盖手动调整的顺序。另一种做法是只在提交前手动执行一次整理，减少意外改动。

补充检查项与故障排除

如果以上步骤都做了但补全仍然不生效，可以检查 VSCode 输出面板（Ctrl+Shift+U）中 Python 或 Pylance 的日志。常见错误包括：Pylance 崩溃、设置文件格式错误（多了一个逗号导致 JSON 解析失败）、或者工作区包含多个根文件夹时解释器选择冲突。你可以尝试重新加载窗口（Ctrl+Shift+P -> Developer: Reload Window）或者禁用并重新启用 Python 扩展。对于特别复杂的环境，比如 Docker 容器或 SSH 远程，确保远程主机上也安装了扩展且设置正确。另外，注意 VSCode 的“python.analysis.importFormat”设置可以控制导入格式（absolute 或 relative），默认通常是绝对导入，如果你项目要求相对导入，需要手动修改。