參加你附近的 ，瞭解 VS Code 中的 AI 輔助開發。

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 是否利用智慧傳送（Smart Send）。智慧傳送會檢視游標所在位置的程式碼，將最小的可執行程式碼塊傳送到 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 引擎設定

注意：如果您從未更改過語言伺服器設定，則您的語言伺服器透過“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 [] 執行 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 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": "包名 (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 時，使用最高錯誤嚴重性的所有型別檢查規則（包括 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 針對返回 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