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: Select Interpreter 命令選擇的環境。例如，當此設定為 `true` 並且您選擇了一個虛擬環境時，擴充套件程式會在建立新終端時自動執行環境的 activate 命令（macOS/Linux 上為 `source env/bin/activate`；Windows 上為 `env\scripts\activate`）。
terminal.executeInFileDir	`false`	指示是將在檔案的目錄中執行檔案，還是在當前資料夾中執行。
terminal.focusAfterLaunch	`false`	啟動 Python 終端時是否將游標焦點切換到終端。
terminal.launchArgs	`[]`	使用 Python: Run Python File in Terminal 等命令執行檔案時，傳遞給 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 引擎設定

注意：如果您從未更改過語言伺服器設定，您的語言伺服器將透過“預設”設定值設定為 Pylance。

設定 (python.)	預設值	描述
languageServer	預設值	定義語言伺服器的型別（預設、Pylance、Jedi 和 None）。

Python 語言伺服器設定

Pylance 語言伺服器

當 python.languageServer 設定為 Pylance 或 Default 時，語言伺服器設定將生效。如果您在使用語言伺服器時遇到問題，請參閱語言伺服器儲存庫中的故障排除。

設定
(python.analysis.) 預設值描述

aiCodeActions

true

是否啟用特定的人工智慧輔助程式碼操作。需要啟用 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

[]

執行 **Fix All** 命令或 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` 模式	`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	對 `isinstance` 或 `issubclass` 呼叫結果靜態確定為始終為 true 或始終為 false 的診斷。此類呼叫通常表明存在程式設計錯誤。
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。
測試 - 配置測試環境以及發現、執行和除錯測試。

3/6/2023