🚀 在 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 擴充功能不會自動新增或變更此設定。
interpreter.infoVisibility "onPythonRelated" 控制何時在狀態列上顯示選取的直譯器資訊。
依預設，僅當編輯器中開啟 Python 相關檔案時才會顯示。
如果您希望它始終顯示在狀態列上，可以將其設定為 "always"，或設定為 "never" 以完全隱藏它。
pipenvPath "pipenv" 用於啟用的 pipenv 可執行檔路徑。
venvFolders [] 建立虛擬環境的資料夾路徑。
根據使用的虛擬化工具，它可以是專案本身：${workspaceFolder}，或是所有虛擬環境並排的個別資料夾：.\envs、~/.virtualenvs 等。
envFile "${workspaceFolder}/
.env"		 包含環境變數定義的檔案絕對路徑。
請參閱設定 Python 環境 - 環境變數定義檔。
globalModuleInstallation false 指定是否僅使用 --user 命令列引數 (預設值) 為目前使用者安裝套件，或是在全域環境中為所有使用者安裝 (設定為 true 時)。使用虛擬環境時會忽略。
如需有關 --user 引數的詳細資訊，請參閱pip - 使用者安裝。
poetryPath "poetry" 指定 Poetry 相依性管理員可執行檔 (如果已安裝) 的位置。預設值 "poetry" 假設可執行檔位於目前路徑中。
當 Poetry 可用且工作區資料夾中有 poetry.lock 檔案時，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.executeInFileDir false 指出是否要在檔案的目錄中執行檔案，而不是在目前的資料夾中執行。
terminal.activateEnvironment true 指出在建立新的終端機時，是否要自動啟動您使用 Python: 選取直譯器 命令選取的環境。
例如，當此設定為 true 且您選取虛擬環境時，擴充功能會在建立新的終端機時自動執行環境的啟動命令 (macOS/Linux 上的 source env/bin/activate；Windows 上的 env\scripts\activate)。
terminal.activateEnvInCurrentTerminal false 指定在 Python 擴充功能啟動時，是否要使用選取的虛擬環境啟動目前開啟的終端機。
terminal.focusAfterLaunch false 啟動 Python 終端機時，是否要將游標焦點切換到終端機。
logging.level error 指定擴充功能要執行的記錄層級。
可能的記錄層級 (依提供的資訊量遞增順序排列) 為 off、error、warn、info 和 debug。
設定為 off (不建議) 時，仍會顯示基本資訊，例如啟動資訊和 Python 擴充功能執行的命令。
在 error 層級，會顯示基本資訊和錯誤。
在 warn 層級，會顯示基本、錯誤和警告資訊。在 info 層級，會顯示基本、錯誤、警告和其他資訊，例如方法執行時間和傳回值。目前，debug 層級不會顯示其他資訊。
experiments.enabled true 啟用 Python 擴充功能中的 A/B 實驗。如果啟用，您可能會收到建議的增強功能和/或功能。

程式碼分析設定

IntelliSense 引擎設定

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

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

Python 語言伺服器設定

Pylance 語言伺服器

當 python.languageServer 為 Pylance 或 預設值 時，語言伺服器設定會套用。如果您在使用語言伺服器時遇到困難，請參閱語言伺服器存放庫中的疑難排解。

設定
(python.analysis.)		 預設值 描述
typeCheckingMode off 指定要執行的類型檢查分析層級。
可用的值為 off、basic 和 strict。
設定為 off 時，不會執行任何類型檢查分析；會產生未解決的匯入/變數診斷。
設定為 basic 時，會使用非類型檢查相關規則 (off 中的所有規則) 以及基本類型檢查規則。
設定為 strict 時，會使用最高嚴重性錯誤的所有類型檢查規則 (包括 off 和 basic 類別中的所有規則)。
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
diagnosticMode openFilesOnly 指定語言伺服器分析哪些程式碼檔案是否有問題。
可用的值為 workspace 和 openFilesOnly。
include [] 應該包含在分析中的目錄或檔案路徑。
如果未指定路徑，Pylance 預設為包含工作區根目錄的目錄。
路徑可能包含萬用字元，例如 ** (目錄或多個層級的目錄)、* (零個或多個字元的序列) 或 ? (單一字元)。
exclude [] 不應包含在分析中的目錄或檔案路徑。
這些路徑會覆寫 python.analysis.include 設定下所列的目錄，允許排除特定子目錄。
請注意，如果此 exclude 設定中列出的檔案是由未在排除清單中的原始檔參考/匯入，則這些檔案仍可能包含在分析中。
路徑可能包含萬用字元，例如 ** (目錄或多個層級的目錄)、* (零個或多個字元的序列) 或 ? (單一字元)。
如果未指定排除路徑，Pylance 會自動排除下列項目：**/node_modules、**/\_\_pycache\_\_、.git 和任何虛擬環境目錄。
ignore [] 應該隱藏其診斷輸出 (錯誤和警告) 的目錄或檔案路徑，即使它們是包含的檔案，或位於包含檔案的可轉移封閉中。
路徑可能包含萬用字元，例如 ** (目錄或多個層級的目錄)、* (零個或多個字元的序列) 或 ? (單一字元)。
如果未提供值，則會使用 python.linting.ignorePatterns 的值 (如果已設定)。
stubPath ./typings 指定包含自訂類型 Stub 的目錄路徑。每個套件的類型 Stub 檔案預期都會在其自己的子目錄中。
autoSearchPaths true 指出是否要根據一些預先定義的名稱 (例如 src) 自動新增搜尋路徑。可用的值為 true 和 false。
extraPaths [] 指定匯入解析的其他搜尋路徑。
接受指定為字串的路徑，如果有多個路徑，則以逗號分隔。例如：["path 1","path 2"]。
indexing true 用於指定 Pylance 是否應在啟動時編製使用者檔案以及已安裝的協力廠商程式庫的索引，以便在自動匯入、快速修正、自動完成等功能中提供更完整的符號集。
接受的值為 true 或 false。
設定為 true 時，依預設，Pylance 會編製已安裝套件的最上層符號索引 (亦即 package/__init__.py 下的 __all__ 中的符號)，以及最多 2000 個使用者檔案中的所有符號。
設定為 false 時，Pylance 只會顯示先前在編輯器中開啟或載入的檔案中已參考或使用的符號。
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}]
userFileIndexingLimit 2000 設定 Pylance 在工作區中要編製索引的使用者檔案數目上限。設定為 -1 時，Pylance 會編製所有檔案的索引。
請注意，編製檔案索引是一項效能密集型工作。
autoFormatStrings false 在字串內輸入 "{" 時，是否要自動在其前面加上 "f"。
completeFunctionParens false 將括弧新增至函式完成。接受的值為 true 和 false。
useLibraryCodeForTypes true 在找不到類型 Stub 時，剖析套件的原始碼。可用的值為 true 和 false。
includeAliasesFromUserFiles false 是否要在自動匯入建議和新增匯入快速修正中包含來自使用者檔案的別名符號。停用時，Pylance 會提供從定義符號的位置匯入建議。啟用時，它也會提供從匯入符號 (亦即別名) 的檔案匯入建議。可用的值為 true 和 false。
autoImportCompletions false 控制在完成中提供自動匯入。可用的值為 true 和 false。
importFormat absolute 定義自動匯入模組時的預設格式。接受的值為 absolute 或 relative。
aiCodeActions true 是否啟用特定的 AI 輔助程式碼動作。需要啟用 GitHub Copilot Chat 擴充功能。
接受的值是以程式碼動作為索引鍵，布林值為值的物件。
可用於作為索引鍵的程式碼動作
  • implementAbstractClasses：啟用程式碼動作以實作從抽象類別繼承之類別的方法，並使用來自 GitHub Copilot 的 AI 建議來填入方法主體。
使用範例：{"implementAbstractClasses": true}
inlayHints.variableTypes false 是否顯示變數類型的內嵌提示。接受的值為 true 或 false。
inlayHints.functionReturnTypes false 是否顯示函式傳回類型的內嵌提示。接受的值為 true 或 false。
inlayHints.callArgumentNames false 是否顯示呼叫引數名稱的內嵌提示。接受的值為 true 或 false。
inlayHints.pytestParameters false 是否顯示 pytest 夾具引數類型的內嵌提示。接受的值為 true 或 false。
diagnosticSeverityOverrides {} 允許使用者覆寫個別診斷的嚴重性層級。
針對每個規則，可用的嚴重性層級為 error (紅色波浪線)、warning (黃色波浪線)、information (藍色波浪線) 和 none (已停用規則)。
如需有關用於診斷嚴重性規則的索引鍵資訊，請參閱下方的 診斷嚴重性規則 區段。
fixAll [] 執行 全部修正 命令或 source.fixAll 程式碼動作時要執行的程式碼動作清單。
此清單中接受的值
  • source.unusedImports：移除開啟檔案中的所有未使用匯入
  • source.convertImportFormat：根據 python.analysis.importFormat 設定轉換匯入
logLevel Error 指定語言伺服器要執行的記錄層級。
可能的記錄層級 (依提供的資訊量遞增順序排列) 為 Error、Warning、Information 和 Trace。
autoIndent true 在輸入 Python 程式碼時，是否要根據語言語意自動調整縮排。
接受的值為 true 或 false。

診斷嚴重性規則

本節詳細說明所有可使用 python.analysis.diagnosticSeverityOverrides 設定自訂的可用規則，如下列範例所示。

{
  "python.analysis.diagnosticSeverityOverrides": {
    "reportUnboundVariable": "information",
    "reportImplicitStringConcatenation": "warning"
  }
}
值 描述
reportGeneralTypeIssues 一般類型不一致、不支援的作業、引數/參數不符等診斷。這涵蓋未由其他規則涵蓋的所有基本類型檢查規則。不包含語法錯誤。
reportPropertyTypeMismatch 屬性的診斷，其中傳遞至 setter 的值的類型無法指派給 getter 傳回的值。此類不符會違反屬性的預期用途，屬性旨在像變數一樣運作。
reportFunctionMemberAccess 函式成員存取的診斷。
reportMissingImports 沒有對應匯入的 Python 檔案或類型 Stub 檔案的匯入診斷。
reportMissingModuleSource 沒有對應原始檔的匯入診斷。當找到類型 Stub，但找不到模組原始檔時，就會發生這種情況，表示程式碼在使用此執行環境時可能會在執行階段失敗。類型檢查將會使用類型 Stub 執行。
reportMissingTypeStubs 沒有對應類型 Stub 檔案 (Typeshed 檔案或自訂類型 Stub) 的匯入診斷。類型檢查器需要類型 Stub 才能盡力執行分析。
reportImportCycles 循環匯入鏈的診斷。這些在 Python 中不是錯誤，但它們確實會減慢類型分析速度，而且通常暗示架構分層問題。一般而言，應避免使用。
reportUnusedImport 在檔案中未參考的匯入符號診斷。
reportUnusedClass 未存取的私用名稱 (以下底線開頭) 類別診斷。
reportUnusedFunction 未存取的私用名稱 (以下底線開頭) 函式或方法診斷。
reportUnusedVariable 未存取的變數診斷。
reportDuplicateImport 多次匯入的匯入符號或模組診斷。
reportWildcardImportFromLibrary 從外部程式庫進行萬用字元匯入的診斷。
reportOptionalSubscript 嘗試為具有 Optional 類型的變數建立註標 (索引) 的診斷。
reportOptionalMemberAccess 嘗試存取具有 Optional 類型的變數成員的診斷。
reportOptionalCall 嘗試呼叫具有 Optional 類型的變數的診斷。
reportOptionalIterable 嘗試將 Optional 類型用作可迭代值 (例如，在 for 陳述式中) 的診斷。
reportOptionalContextManager 嘗試將 Optional 類型用作內容管理員 (作為 with 陳述式的參數) 的診斷。
reportOptionalOperand 嘗試將 Optional 類型用作二元或一元運算子 (例如 '+'、'=='、'or'、'not') 的運算元的診斷。
reportUntypedFunctionDecorator 沒有類型註釋的函式裝飾器診斷。這些會模糊函式類型，從而破壞許多類型分析功能。
reportUntypedClassDecorator 沒有類型註釋的類別裝飾器診斷。這些會模糊類別類型，從而破壞許多類型分析功能。
reportUntypedBaseClass 無法靜態判斷其類型的基底類別診斷。這些會模糊類別類型，從而破壞許多類型分析功能。
reportUntypedNamedTuple 使用 "namedtuple" 而非 "NamedTuple" 時的診斷。前者不包含類型資訊，而後者則包含。
reportPrivateUsage 不正確使用私用或受保護變數或函式的診斷。受保護的類別成員以下底線 _ 開頭，且只能由子類別存取。私用類別成員以雙底線開頭，但不以雙底線結尾，且只能在宣告類別中存取。在類別外部宣告的變數和函式，如果其名稱以單一下底線或雙底線開頭，則會被視為私用，且無法在宣告模組外部存取。
reportConstantRedefinition 嘗試重新定義名稱全為大寫字母、底線和數字的變數診斷。
reportIncompatibleMethodOverride 以不相容的方式覆寫基底類別中同名方法的診斷 (參數數量錯誤、參數類型不相容或傳回類型不相容)。
reportIncompatibleVariableOverride 類別變數宣告的診斷，其覆寫基底類別中同名的符號，且類型與基底類別符號類型不相容。
reportInvalidStringEscapeSequence 字串常值中使用的無效逸出序列診斷。Python 規格指出，此類序列會在未來版本中產生語法錯誤。
reportUnknownParameterType 類型不明的函式或方法輸入或傳回參數診斷。
reportUnknownArgumentType 類型不明的函式或方法呼叫引數診斷。
reportUnknownLambdaType 類型不明的 Lambda 輸入或傳回參數診斷。
reportUnknownVariableType 類型不明的變數診斷。
reportUnknownMemberType 類型不明的類別或執行個體變數診斷。
reportMissingTypeArgument 在未使用明確或隱含類型引數的情況下使用泛型類別時的診斷。
reportInvalidTypeVarUse 函式簽章中不當使用類型變數的診斷。
reportCallInDefaultInitializer 預設值初始化運算式中函式呼叫的診斷。此類呼叫可能會遮罩在模組初始化時執行的昂貴作業。
reportUnnecessaryIsInstance 針對 'isinstance' 或 'issubclass' 呼叫的診斷，其中靜態判斷結果永遠為 true 或永遠為 false。此類呼叫通常表示程式設計錯誤。
reportUnnecessaryCast 針對靜態判斷為不必要的 'cast' 呼叫的診斷。此類呼叫有時表示程式設計錯誤。
reportAssertAlwaysTrue 針對可能永遠會判斷提示的 'assert' 陳述式診斷。這可能表示程式設計錯誤。
reportSelfClsParameterName 執行個體方法中遺失或命名錯誤的 "self" 參數，以及類別方法中遺失或命名錯誤的 "cls" 參數診斷。中繼類別 (衍生自 "type" 的類別) 中的執行個體方法允許針對執行個體方法使用 "cls"。
reportImplicitStringConcatenation 兩個或多個彼此相鄰的字串常值診斷，表示隱含串連。這被認為是不好的做法，而且通常會遮罩錯誤，例如遺失逗號。
reportUndefinedVariable 未定義變數的診斷。
reportUnboundVariable 未繫結和可能未繫結變數的診斷。
reportInvalidStubStatement 不應出現在 Stub 檔案中的陳述式診斷。
reportUnusedCallResult 結果未被使用且不是 None 的呼叫運算式診斷。
reportUnsupportedDunderAll 在 __all__ 上執行不支援作業的診斷。
reportUnusedCoroutine 傳回 Coroutine 且結果未被使用的呼叫運算式診斷。

自動完成設定

設定
(python.autoComplete.)		 預設值 描述 另請參閱
extraPaths [] 指定要載入自動完成資料的其他套件位置。 編輯

測試設定

一般測試

設定
(python.testing.)		 預設值 描述 另請參閱
cwd null 指定測試的選用工作目錄。 測試
promptToConfigure true 指定如果探索到潛在測試，VS Code 是否提示設定測試架構。 測試
debugPort 3000 用於偵錯 unittest 測試的連接埠號碼。 測試
autoTestDiscoverOnSaveEnabled true 指定在儲存測試檔案時是否啟用或停用自動執行測試探索。 測試

unittest 架構

設定
(python.testing.)		 預設值 描述 另請參閱
unittestEnabled false 指定是否啟用 unittest 以進行測試。 測試
unittestArgs ["-v", "-s", ".", "-p", "*test*.py"] 要傳遞至 unittest 的引數，其中以空格分隔的每個最上層元素都是清單中的個別項目。 測試

pytest 架構

設定
(python.testing.)		 預設值 描述 另請參閱
pytestEnabled false 指定是否啟用 pytest 以進行測試。 測試
pytestPath "pytest" pytest 的路徑。如果 pytest 位於目前環境之外，請使用完整路徑。 測試
pytestArgs [] 要傳遞至 pytest 的引數，其中以空格分隔的每個最上層元素都是清單中的個別項目。使用已安裝 pytest-cov 的 pytest 偵錯測試時，請在這些引數中包含 --no-cov。 測試

預先定義的變數

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、格式化和重構。
  • 程式碼檢查 - 啟用、設定和套用各種 Python 程式碼檢查工具。
  • 偵錯 - 學習在本機和遠端偵錯 Python。
  • 測試 - 設定測試環境，以及探索、執行和偵錯測試。
3/6/2023