探索智能体开发 -

Python 设置参考

Visual Studio Code 的 Python 扩展具有高度可配置性。本页面介绍了您可以使用的关键设置。

有关在 VS Code 中使用设置的通用信息，请参阅用户和工作区设置，以及有关预定义变量支持的变量参考。

通用 Python 设置

设置 (python.) 默认值 描述
condaPath "conda" conda 可执行文件的路径。
defaultInterpreterPath "python" Python 扩展在首次为工作区加载时所使用的默认 Python 解释器路径，或者是包含 Python 解释器的文件夹路径。可以使用 ${workspaceFolder} 和 ${workspaceFolder}/.venv 等变量。使用文件夹路径允许任何处理项目的人员根据其操作系统在 .venv 文件夹中创建环境，而无需指定与平台相关的精确路径。随后可以将 settings.json 文件包含在源代码存储库中。注意：如果在工作区选择了解释器之后更改此设置，Python 扩展将不会应用或考虑这些更改。Python 扩展不会自动添加或更改此设置。
envFile "${workspaceFolder}/.env" 包含环境变量定义的文件的绝对路径。请参阅 .env 文件支持。
experiments.enabled true 启用 Python 扩展中的 A/B 实验。如果启用，您可能会获得建议的增强功能和/或特性。
globalModuleInstallation false 指定是仅使用 --user 命令行参数（默认）为当前用户安装包，还是在全局环境中为所有用户安装包（设置为 true 时）。使用虚拟环境时此设置将被忽略。有关 --user 参数的更多信息，请参阅 pip - 用户安装。
interpreter.infoVisibility "onPythonRelated" 控制何时在状态栏上显示选定的解释器信息。默认情况下，仅在编辑器中打开了与 Python 相关的文件时才会显示。如果您希望它始终显示在状态栏上，可以将其设置为 "always"；或者将其设置为 "never" 以完全隐藏它。
pipenvPath "pipenv" 用于激活的 pipenv 可执行文件路径。
poetryPath "poetry" 指定 Poetry 依赖管理器可执行文件的位置（如果已安装）。默认值 "poetry" 假定可执行文件在当前路径中。当 Poetry 可用且工作区文件夹中存在 poetry.lock 文件时，Python 扩展会使用此设置来安装包。
REPL.enableREPLSmartSend true 指定 Shift+Enter 是否利用智能发送（Smart Send）。智能发送会查看光标所在的代码，将最小的可运行代码块发送到 Python REPL，然后将光标置于下一行代码。
terminal.activateEnvInCurrentTerminal false 指定当 Python 扩展激活时，是否使用选定的虚拟环境来激活当前打开的终端。
terminal.activateEnvironment true 指示创建新终端时，是否自动激活使用 Python: 选择解释器 命令选择的环境。例如，当此设置设为 true 且您选择了一个虚拟环境时，扩展在创建新终端时会自动运行环境的 activate 命令（macOS/Linux 上为 source env/bin/activate；Windows 上为 env\scripts\activate）。注意：如果配置了 python-envs.terminal.autoActivationType，则此设置将被该设置覆盖。
terminal.executeInFileDir false 指示是在文件的目录中运行文件，而不是在当前文件夹中运行。
terminal.focusAfterLaunch false 启动 Python 终端时是否将光标焦点切换到终端。
terminal.launchArgs [] 当使用诸如 Python: 在终端中运行 Python 文件 等命令运行文件时，传递给 Python 解释器的启动参数。在 launchArgs 列表中，每一项都是一个以空格分隔的顶级命令行元素（包含空格的带引号的值被视为单个顶级元素，因此在列表中作为一项）。例如，对于参数 --a --b --c {"value1" : 1, "value2" : 2}，列表项应该是 ["--a", "--b", "--c", "{\"value1\" : 1, \"value2\" : 2}\""]。注意，调试时 VS Code 会忽略此设置，因为它会改用 launch.json 中所选调试配置的参数。
terminal.useEnvFile false 控制 env 文件和 python.envFile 设置中的环境变量是否注入到终端中。
venvFolders [] 创建虚拟环境的文件夹路径。根据使用的虚拟化工具，它可以是项目本身：${workspaceFolder}，或者并排放置所有虚拟环境的单独文件夹：.\envs, ~/.virtualenvs 等。注意：此设置会自动与 python-envs.globalSearchPaths 合并。请考虑迁移到新设置以获取更多功能。

Python 环境扩展设置

Python 环境扩展在 VS Code UI 中提供环境和包管理。这些设置控制环境发现、创建和终端激活。

有关环境管理的更多信息，请参阅 Python 环境。

环境管理设置

设置 (python-envs.) 默认值 描述
defaultEnvManager "ms-python.python:venv" 用于创建和管理环境的默认环境管理器。
defaultPackageManager "ms-python.python:pip" 用于在环境中安装包的默认包管理器。
pythonProjects [] Python 项目列表。每个项目都是一个包含以下属性的对象：path（字符串）、envManager（字符串）、packageManager（字符串）。在多根工作区中使用此设置来配置每个文件夹的环境。
workspaceSearchPaths ["./**/.venv"] 用于搜索此工作区中环境的 Glob 模式。默认情况下，它会搜索工作区中任何名为 .venv 的文件夹。注意：此设置必须在工作区或文件夹级别配置，不能在用户级别配置。
globalSearchPaths [] 用于跨所有工作区搜索 Python 环境的绝对路径。用于像 ~/envs 这样的共享环境文件夹。注意：旧设置 python.venvPath 和 python.venvFolders 会自动与此设置合并。
alwaysUseUv true 设置为 true 时，如果可用，将使用 uv 来管理所有虚拟环境。设置为 false 时，uv 将仅管理由 uv 明确创建的虚拟环境。

终端设置

设置 (python-envs.terminal.) 默认值 描述
autoActivationType "command" 指定扩展如何在终端中激活环境。可用值：command（通过在终端中执行命令来激活）、shellStartup（使用 shell 集成或修改终端 shell 启动脚本来激活，支持 zsh、fish、pwsh、bash、cmd）、off（无自动激活）。注意：此设置优先于 python.terminal.activateEnvironment。
showActivateButton false (实验性) 是否在终端菜单中显示“激活”按钮。

旧设置迁移

如果您正在从旧的 Python 扩展设置进行迁移，下表显示了与新设置的映射

旧设置 新设置 备注
python.venvPath python-envs.globalSearchPaths 或 python-envs.workspaceSearchPaths 旧设置仍然有效并自动合并。请考虑迁移到使用 Glob 模式。
python.venvFolders python-envs.globalSearchPaths 或 python-envs.workspaceSearchPaths 旧设置仍然有效并自动合并。
python.terminal.activateEnvironment python-envs.terminal.autoActivationType 设置为 "off" 以禁用自动激活。配置后，新设置将优先使用。

调试器设置

通用调试

设置 (python.debugpy.) 默认值 描述 另请参阅
debugJustMyCode true 指定调试器是否应仅单步执行用户编写的代码。禁用此选项允许您同时也单步执行库代码。 调试

测试设置

通用测试

设置 (python.testing.) 默认值 描述 另请参阅
autoTestDiscoverOnSaveEnabled true 指定在保存测试文件时是否启用或禁用自动运行测试发现。 测试
cwd null 指定测试的可选工作目录。 测试
debugPort 3000 用于调试 unittest 测试的端口号。 测试
promptToConfigure true 指定如果发现潜在测试，VS Code 是否提示配置测试框架。 测试

unittest 框架

设置 (python.testing.) 默认值 描述 另请参阅
unittestArgs ["-v", "-s", ".", "-p", "*test*.py"] 传递给 unittest 的参数，其中每个由空格分隔的顶级元素都是列表中的一个独立项目。 测试
unittestEnabled false 指定是否启用 unittest 进行测试。 测试

pytest 框架

设置 (python.testing.) 默认值 描述 另请参阅
pytestArgs [] 传递给 pytest 的参数，其中每个由空格分隔的顶级元素都是列表中的一个独立项目。在安装了 pytest-cov 的情况下调试测试时，请在这些参数中包含 --no-cov。 测试
pytestEnabled false 指定是否启用 pytest 进行测试。 测试
pytestPath "pytest" pytest 的路径。如果 pytest 位于当前环境之外，请使用完整路径。 测试

代码分析设置

IntelliSense 引擎设置

注意： 如果您从未更改过语言服务器设置，则您的语言服务器通过“默认”设置值设为 Pylance。

设置 (python.) 默认值 描述
languageServer 默认值 定义语言服务器的类型（Default、Pylance、Jedi 和 None）。

Python 语言服务器设置

Pylance 语言服务器

当 python.languageServer 为 Pylance 或 Default 时，语言服务器设置适用。如果您在使用语言服务器时遇到困难，请参阅语言服务器存储库中的故障排除。

设置 (python.analysis.) 默认值 描述
aiCodeActions true 是否启用特定的 AI 辅助代码操作。需要启用 GitHub Copilot Chat 扩展。接受的值是一个对象，其中键为代码操作，值为布尔值。可用的代码操作：implementAbstractClasses（启用代码操作以实现从抽象类继承的类的方法，使用 GitHub Copilot 的 AI 建议来填充方法体）。使用示例：{"implementAbstractClasses": true}
autoFormatStrings false 在字符串内输入 "{" 时，是否自动为其添加 "f" 前缀。
autoImportCompletions false 控制补全中自动导入的提供。可用值为 true 和 false。
autoIndent true 在输入 Python 代码时，是否根据语言语义自动调整缩进。接受的值为 true 或 false。
autoSearchPaths true 指示是否根据某些预定义名称（如 src）自动添加搜索路径。可用值为 true 和 false。
completeFunctionParens false 在函数补全中添加括号。接受的值为 true 和 false。
diagnosticMode openFilesOnly 指定语言服务器分析哪些代码文件以查找问题。可用值为 workspace 和 openFilesOnly。
diagnosticSeverityOverrides {} 允许用户覆盖单个诊断的严重性级别。对于每个规则，可用的严重性级别为 error（红色波浪线）、warning（黄色波浪线）、information（蓝色波浪线）和 none（规则已禁用）。有关用于诊断严重性规则的键的信息，请参阅下方的诊断严重性规则部分。
enableEditableInstalls false 通过解析以可编辑模式（pip install -e .）安装的包的导入路径（如 PEP 660 所定义），启用改进的 IntelliSense 支持。
exclude [] 不应包含在分析中的目录或文件的路径。这些设置会覆盖 python.analysis.include 设置下列出的目录，从而允许排除特定的子目录。注意，如果此 exclude 设置中列出的文件被不在排除列表中的源文件引用/导入，它们仍可能被包含在分析中。路径可以包含通配符，例如 **（一个目录或多级目录）、*（零个或多个字符的序列）或 ?（单个字符）。如果未指定排除路径，Pylance 会自动排除以下内容：**/node_modules、**/__pycache__、.git 以及任何虚拟环境目录。
extraPaths [] 指定用于导入解析的额外搜索路径。接受以字符串形式指定的路径，如果有多个路径则用逗号分隔。例如：["path 1","path 2"]。
importFormat absolute 定义自动导入模块时的默认格式。接受的值为 absolute 或 relative。
include [] 应包含在分析中的目录或文件的路径。如果未指定路径，Pylance 默认为包含工作区根目录的目录。路径可以包含通配符，例如 **（一个目录或多级目录）、*（零个或多个字符的序列）或 ?（单个字符）。
fixAll [] 运行 全部修复 命令或 source.fixAll 代码操作时要运行的代码操作列表。接受的值：source.unusedImports（删除打开文件中所有未使用的导入）、source.convertImportFormat（根据 python.analysis.importFormat 设置转换导入）。
includeAliasesFromUserFiles false 是否在自动导入建议和添加导入快速修复中包含用户文件中的别名符号。禁用时，Pylance 将提供定义该符号位置的导入建议。启用时，它还将提供符号导入（即别名）位置的导入建议。可用值为 true 和 false。
ignore [] 应抑制其诊断输出（错误和警告）的目录或文件的路径，即使它们是包含的文件或在包含文件的传递闭包内。路径可以包含通配符，例如 **（一个目录或多级目录）、*（零个或多个字符的序列）或 ?（单个字符）。如果未提供值，将使用 python.linting.ignorePatterns 的值（如果已设置）。
indexing true 用于指定 Pylance 是否应在启动时索引用户文件以及已安装的第三方库，以便在自动导入、快速修复、自动补全等功能中提供更完整的符号集。接受的值为 true 或 false。设置为 true 时，默认情况下 Pylance 会索引已安装包的顶级符号（即 package/__init__.py 下的 __all__ 中的符号），以及最多 2000 个用户文件的所有符号。设置为 false 时，Pylance 将仅显示在编辑器之前打开或加载的文件中已引用或使用的符号。
inlayHints.callArgumentNames off 控制调用参数名称内嵌提示的显示。可用值为 off、partial 和 all。设置为 off 时，不显示内嵌提示。设置为 partial 时，禁用位置参数和关键字参数的提示。设置为 all 时，显示所有参数的提示。
inlayHints.functionReturnTypes false 是否显示函数返回类型的内嵌提示。接受的值为 true 或 false。
inlayHints.pytestParameters false 是否显示 pytest 固件参数类型的内嵌提示。接受的值为 true 或 false。
inlayHints.variableTypes false 是否显示变量类型的内嵌提示。接受的值为 true 或 false。
languageServerMode default 提供预定义配置，根据开发需求优化 Pylance 的性能。可用值为 default 和 light。设置为 default 时，语言服务器为大多数机器提供足够的功能，而不会使系统超载。设置为 light 时，它启用轻量级、内存高效的设置。此模式会禁用各种功能，使 Pylance 的功能更像一个精简的文本编辑器，对于那些不需要全部 IntelliSense 功能并希望 Pylance 尽可能节省资源的用户来说非常理想。在 light 模式下，以下设置会被覆盖：python.analysis.exclude 设置为 ["**"]，python.analysis.useLibraryCodeForTypes 设置为 false，python.analysis.enablePytestSupport 设置为 false，python.analysis.indexing 设置为 false。
logLevel Error 指定语言服务器执行的日志记录级别。可能的日志记录级别按提供的信息量增加排列为：Error、Warning、Information 和 Trace。
nodeArguments "--max-old-space-size=8192" 指定直接传递给 python.analysis.nodeExecutable 定义的自定义 Node.js 可执行文件的自定义参数。这可用于分配更多内存或配置 Node.js 行为。接受 Node.js 支持的参数列表。列表中的每个 "arg=value" 都应以逗号分隔。使用示例："python.analysis.nodeArguments": ["--max-old-space-size=8192"]
nodeExecutable "" 指定要使用的 Node.js 可执行文件，这允许 Pylance 分配更多内存。接受的值为带有可执行文件路径的字符串、空字符串或 "auto"。当设置为空字符串时，Pylance 将使用 VS Code 的 node 可执行文件。设置为 "auto" 时，它将自动下载 Node.js。
packageIndexDepths [] 用于覆盖在每个包的基础上索引已安装包下的深度。默认情况下，仅索引顶级模块（深度 = 1）。要索引子模块，请为您要索引的每一层子模块将深度增加 1。接受的对象元组格式如下：{"name": "包名 (str)", "depth": "扫描深度 (int)", "includeAllSymbols": "是否包含所有符号 (bool)"}。如果 includeAllSymbols 设置为 false，则仅包含每个包的 __all__ 中的符号。设置为 true 时，Pylance 将索引文件中的每个模块/顶级符号声明。使用示例：[{"name": "sklearn", "depth": 2, "includeAllSymbols": true}, {"name": "matplotlib", "depth": 3, "includeAllSymbols": false}]
stubPath ./typings 指定包含自定义类型存根的目录路径。每个包的类型存根文件应位于其自己的子目录中。
typeCheckingMode off 指定要执行的类型检查分析级别。可用值为 off、basic 和 strict。设置为 off 时，不进行类型检查分析；会产生未解析导入/变量的诊断。设置为 basic 时，使用非类型检查相关的规则（off 中的所有规则）以及基本的类型检查规则。设置为 strict 时，使用最高严重级别为 error 的所有类型检查规则（包括 off 和 basic 类别中的所有规则）。
useLibraryCodeForTypes true 在未找到类型存根时解析包的源代码。可用值为 true 和 false。
userFileIndexingLimit 2000 设置 Pylance 在工作区中索引的用户文件的最大数量。设置为 -1 时，Pylance 将索引所有文件。注意，索引文件是一项性能密集型任务。

诊断严重性规则

本节详细介绍了可以使用 python.analysis.diagnosticSeverityOverrides 设置进行自定义的所有可用规则，如下例所示。

{
  "python.analysis.diagnosticSeverityOverrides": {
    "reportUnboundVariable": "information",
    "reportImplicitStringConcatenation": "warning"
  }
}
值 描述
reportAssertAlwaysTrue 对于可能总是为真的 'assert' 语句的诊断。这可能预示着编程错误。
reportCallInDefaultInitializer 对默认值初始化表达式中函数调用的诊断。此类调用可能掩盖在模块初始化时执行的昂贵操作。
reportConstantRedefinition 对尝试重新定义名称为全大写且包含下划线和数字的变量的诊断。
reportDuplicateImport 对被导入多次的已导入符号或模块的诊断。
reportFunctionMemberAccess 对函数成员访问的诊断。
reportGeneralTypeIssues 对一般类型不一致、不支持的操作、参数/参数不匹配等的诊断。这涵盖了其他规则未涵盖的所有基本类型检查规则。它不包括语法错误。
reportImportCycles 对循环导入链的诊断。这些在 Python 中不是错误，但它们确实会减慢类型分析速度，并通常暗示架构分层问题。通常应避免使用它们。
reportImplicitStringConcatenation 对彼此相邻的两个或多个字符串文字的诊断，指示隐式拼接。这被认为是不好的做法，通常会掩盖如缺少逗号等错误。
reportIncompatibleMethodOverride 对以不兼容方式重写基类中同名方法的诊断（参数数量错误、不兼容的参数类型或不兼容的返回类型）。
reportIncompatibleVariableOverride 对重写基类中同名符号但类型与基类符号类型不兼容的类变量声明的诊断。
reportInvalidStringEscapeSequence 对字符串文字中使用的无效转义序列的诊断。Python 规范指出，此类序列将在未来的版本中产生语法错误。
reportInvalidStubStatement 对不应出现在存根文件中的语句的诊断。
reportInvalidTypeVarUse 对函数签名中类型变量使用不当的诊断。
reportMissingImports 对没有相应导入的 python 文件或类型存根文件的导入的诊断。
reportMissingModuleSource 对没有相应源文件的导入的诊断。这种情况发生在找到类型存根但未找到模块源文件时，表明在使用此执行环境时代码可能会在运行时失败。将使用类型存根进行类型检查。
reportMissingTypeArgument 对在不提供显式或隐式类型参数的情况下使用泛型类的诊断。
reportMissingTypeStubs 对没有相应类型存根文件（typeshed 文件或自定义类型存根）的导入的诊断。类型检查器需要类型存根才能最大限度地完成分析工作。
reportOptionalCall 对尝试调用 Optional 类型变量的诊断。
reportOptionalContextManager 对尝试将 Optional 类型用作上下文管理器（作为 with 语句的参数）的诊断。
reportOptionalIterable 对尝试将 Optional 类型用作可迭代值的诊断（例如在 for 语句中）。
reportOptionalMemberAccess 对尝试访问 Optional 类型变量成员的诊断。
reportOptionalOperand 对尝试将 Optional 类型用作二元或一元运算符（如 '+'、'=='、'or'、'not'）操作数的诊断。
reportOptionalSubscript 对尝试下标（索引）Optional 类型变量的诊断。
reportPrivateUsage 对不正确使用私有或受保护变量或函数的诊断。受保护的类成员以单个下划线 _ 开头，并且只能由子类访问。私有类成员以双下划线开头但不以双下划线结尾，并且只能在声明它的类中访问。在类之外声明的变量和函数，如果其名称以单个或双下划线开头，则被视为私有，并且不能在声明它们的模块之外访问。
reportPropertyTypeMismatch 对属性的诊断，其中传递给 setter 的值的类型不可分配给 getter 返回的值。此类不匹配违反了属性的预期用途，因为属性旨在像变量一样工作。
reportSelfClsParameterName 对实例方法中丢失或命名错误的“self”参数，以及类方法中“cls”参数的诊断。元类（派生自“type”的类）中的实例方法被允许在实例方法中使用“cls”。
reportUndefinedVariable 对未定义变量的诊断。
reportUnboundVariable 对未绑定和可能未绑定变量的诊断。
reportUnknownArgumentType 对具有未知类型的函数或方法的调用参数的诊断。
reportUnknownLambdaType 对具有未知类型的 lambda 输入或返回参数的诊断。
reportUnknownMemberType 对具有未知类型的类或实例变量的诊断。
reportUnknownParameterType 对具有未知类型的函数或方法的输入或返回参数的诊断。
reportUnknownVariableType 对具有未知类型的变量的诊断。
reportUnnecessaryCast 对静态确定为不必要的 'cast' 调用的诊断。此类调用有时预示着编程错误。
reportUnnecessaryIsInstance 对结果静态确定为始终为真或始终为假的 'isinstance' 或 'issubclass' 调用的诊断。此类调用通常预示着编程错误。
reportUnusedCallResult 对结果未被使用且不为 None 的调用表达式的诊断。
reportUnusedClass 对未被访问的具有私有名称（以单个下划线开头）的类的诊断。
reportUnusedCoroutine 对返回协程且结果未被使用的调用表达式的诊断。
reportUnusedFunction 对未被访问的具有私有名称（以单个下划线开头）的函数或方法的诊断。
reportUnusedImport 对在该文件中未被引用的已导入符号的诊断。
reportUnusedVariable 对未被访问的变量的诊断。
reportUnsupportedDunderAll 对在 __all__ 上执行的不支持操作的诊断。
reportWildcardImportFromLibrary 对来自外部库的通配符导入的诊断。

自动补全设置

设置 (python.autoComplete.) 默认值 描述 另请参阅
extraPaths [] 指定要加载自动补全数据的其他包的位置。 编辑

预定义变量

Python 扩展设置支持预定义变量。与通用 VS Code 设置类似，变量使用 ${variableName} 语法。具体来说，扩展支持以下变量

  • ${cwd} - 任务运行程序启动时的当前工作目录

  • ${workspaceFolder} - VS Code 中打开的文件夹的路径

  • ${workspaceRootFolderName} - VS Code 中打开的文件夹的名称，不带任何斜杠 (/)

  • ${workspaceFolderBasename} - VS Code 中打开的文件夹的名称，不带任何斜杠 (/)

  • ${file} - 当前打开的文件

  • ${relativeFile} - 相对于 workspaceFolder 的当前打开文件

  • ${relativeFileDirname} - 相对于 workspaceFolder 的当前打开文件的目录名

  • ${fileBasename} - 当前打开文件的基本名称

  • ${fileBasenameNoExtension} - 不带文件扩展名的当前打开文件的基本名称

  • ${fileDirname} - 当前打开文件的目录名

  • ${fileExtname} - 当前打开文件的扩展名

  • ${lineNumber} - 活动文件中当前选定的行号

  • ${selectedText} - 活动文件中当前选定的文本

  • ${execPath} - 正在运行的 VS Code 可执行文件的路径

有关预定义变量和示例用法的更多信息，请参阅通用 VS Code 文档中的变量参考。

后续步骤

  • Python 环境 - 控制用于编辑和调试的 Python 解释器。
  • 编辑代码 - 了解 Python 的自动完成、IntelliSense、格式设置和重构。
  • Linting - 启用、配置和应用各种 Python linter。
  • 调试 - 了解如何在本地和远程调试 Python。
  • 测试 - 配置测试环境以及发现、运行和调试测试。
02/04/2026
English 한국어 中文(简体) 中文(繁體)
© . This site is unofficial and not affiliated with Microsoft.