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"`	包含环境变量定义文件的绝对路径。请参阅配置 Python 环境 - 环境变量定义文件。
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` 是否利用智能发送。智能发送会查看光标所在的代码，将最小的可运行代码块发送到 Python REPL，然后将光标定位到下一行代码。
terminal.activateEnvInCurrentTerminal	`false`	指定在激活 Python 扩展时是否激活当前打开的终端，使用选定的虚拟环境。
terminal.activateEnvironment	`true`	指示在使用 Python: 选择解释器命令创建新终端时是否自动激活你选择的环境。例如，当此设置为 `true` 并且你选择了一个虚拟环境时，扩展会在创建新终端时自动运行环境的 activate 命令（在 macOS/Linux 上是 `source env/bin/activate`；在 Windows 上是 `env\scripts\activate`）。
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` 中选定的调试配置中的参数。
venvFolders	`[]`	创建虚拟环境的文件夹路径。根据使用的虚拟化工具，它可以是项目本身：`${workspaceFolder}`，或者所有虚拟环境并排放置的单独文件夹：`.\envs`、`~/.virtualenvs` 等等。

调试器设置

通用调试

设置 (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 引擎设置

注意：如果你从未更改过语言服务器设置，则你的语言服务器通过“Default”设置值设置为 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 .）安装的包的导入路径，从而改进 IntelliSense 支持，如PEP 660 中所定义。

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 false 是否为调用参数名称显示内嵌提示。可接受的值是 true 或 false。

inlayHints.functionReturnTypes false 是否为函数返回类型显示内嵌提示。可接受的值是 true 或 false。

inlayHints.pytestParameters false 是否为 pytest fixture 参数类型显示内嵌提示。可接受的值是 true 或 false。

inlayHints.variableTypes false 是否为变量类型显示内嵌提示。可接受的值是 true 或 false。

languageServerMode

default

提供预定义配置，以根据开发需求优化 Pylance 的性能。
可用值包括 default 和 light。
设置为 default 时，语言服务器为大多数机器提供足够的功能，而不会使系统过载。
设置为 light 时，启用轻量级、内存高效的设置。此模式禁用各种功能，使 Pylance 更像一个精简的文本编辑器，对于不需要 IntelliSense 的全部功能并且希望 Pylance 尽可能地节省资源的人来说，它是理想的选择。
每个模式会覆盖以下默认设置值

设置	`light` 模式	`default` 模式
python.analysis.exclude	["**"]	[]
python.analysis.useLibraryCodeForTypes	false	true
python.analysis.enablePytestSupport	false	true
python.analysis.indexing	false	true

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": "package name (str)", "depth": "depth to scan (int)", "includeAllSymbols": "whether to include all symbols (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 时，使用最高错误严重级别的所有类型检查规则（包括 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	针对被静态确定为始终为 true 或始终为 false 的“isinstance”或“issubclass”调用的诊断。此类调用通常表明存在编程错误。
reportUnusedCallResult	针对其结果未被使用且不为 None 的调用表达式的诊断。
reportUnusedClass	针对名称以（下划线开头）且未被访问的私有类的诊断。
reportUnusedCoroutine	针对返回 Coroutine 且其结果未被使用的调用表达式的诊断。
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。
测试 - 配置测试环境并发现、运行和调试测试。

3/6/2023