🚀 在 VS Code 中取得！

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 且您選取虛擬環境時，擴充功能會在建立新終端機時自動執行環境的啟動命令 (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 引擎設定

注意：如果您從未變更語言伺服器設定，則您的語言伺服器會透過「預設」設定值設定為 Pylance。

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

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 夾具引數類型的內嵌提示。接受的值為 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 的節點可執行檔。設定為 "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 指定包含自訂類型 Stub 的目錄路徑。每個套件的類型 Stub 檔案預期都位於其自己的子目錄中。
typeCheckingMode off 指定要執行的類型檢查分析層級。
可用的值為 off、basic 和 strict。
設定為 off 時，不會執行任何類型檢查分析；會產生未解析的匯入/變數診斷。
設定為 basic 時，會使用非類型檢查相關規則 (off 中的所有規則) 以及基本類型檢查規則。
設定為 strict 時，會使用最高錯誤嚴重性的所有類型檢查規則 (包括 off 和 basic 類別中的所有規則)。
useLibraryCodeForTypes true 在找不到類型 Stub 時，剖析套件的原始碼。可用的值為 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 診斷不應出現在 Stub 檔案中的陳述式。
reportInvalidTypeVarUse 函式簽章中類型變數不當使用的診斷。
reportMissingImports 診斷沒有對應匯入的 Python 檔案或類型 Stub 檔案的匯入。
reportMissingModuleSource 診斷沒有對應原始檔的匯入。當找到類型 Stub，但找不到模組原始檔時，就會發生這種情況，表示在使用此執行環境時，程式碼在執行階段可能會失敗。將使用類型 Stub 執行類型檢查。
reportMissingTypeArgument 診斷在未使用明確或隱含類型引數的情況下使用泛型類別時。
reportMissingTypeStubs 診斷沒有對應類型 Stub 檔案 (typeshed 檔案或自訂類型 Stub) 的匯入。類型檢查器需要類型 Stub 才能盡可能做好分析工作。
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 程式碼檢查工具。
  • 偵錯 - 學習在本機和遠端偵錯 Python。
  • 測試 - 設定測試環境，以及探索、執行和偵錯測試。
3/6/2023