在 Visual Studio Code 中編輯 Python

Name: Visual Studio Code
Author: Microsoft

Visual Studio Code 是功能強大的 Python 原始碼編輯工具。此編輯器包含各種功能，可協助您在撰寫程式碼時提高生產力。如需 Visual Studio Code 中編輯的詳細資訊，請參閱基本編輯和程式碼導覽。

在此概觀中，我們將說明 Python 擴充功能提供的特定編輯功能，包括如何透過使用者和工作區設定自訂這些功能的步驟。

自動完成和 IntelliSense

IntelliSense 是程式碼編輯功能的通用術語，與程式碼完成相關。花點時間查看以下範例。當輸入 print 時，請注意 IntelliSense 如何填入自動完成選項。當使用者開始輸入名為 greeting 的變數時，也會提供選項清單。

Hello World Example for IntelliSense

自動完成和 IntelliSense 功能適用於目前工作資料夾中的所有檔案。它們也適用於安裝在標準位置的 Python 套件。

Pylance 是 VS Code 中 Python 的預設語言伺服器，與 Python 擴充功能一起安裝，以提供 IntelliSense 功能。

Pylance 以 Microsoft 的 Pyright 靜態類型檢查工具為基礎，利用類型 Stub (.pyi 檔案) 和延遲類型推斷，以提供高效能的開發體驗。

如需 IntelliSense 的一般資訊，請參閱IntelliSense。

提示：查看適用於 VS Code 的 IntelliCode 擴充功能。IntelliCode 為 Python 中的 IntelliSense 提供一組 AI 輔助功能，例如根據目前的程式碼內容推斷最相關的自動完成。如需詳細資訊，請參閱適用於 VS Code 的 IntelliCode 常見問題集。

自訂 IntelliSense 行為

預設啟用完整 IntelliSense 功能集可能會讓您的開發體驗感覺變慢，因此 Python 擴充功能會啟用一組最少的功能，讓您在保持高效能體驗的同時仍能提高生產力。不過，您可以透過多個設定，根據您的喜好自訂分析引擎的行為。

啟用自動匯入

Pylance 為您的工作區中的模組以及您在環境中安裝的套件提供自動匯入建議。當您在編輯器中輸入時，可能會收到完成建議。當您接受建議時，自動匯入會自動將對應的 import 陳述式新增至您的檔案。

您可以將設定中的 python.analysis.autoImportCompletions 設定為 true 來啟用自動匯入。依預設，自動匯入會停用。

Completion with auto import displayed on the suggestion list

為自訂套件位置啟用 IntelliSense

若要為安裝在非標準位置的套件啟用 IntelliSense，請將這些位置新增至 settings.json 檔案中的 python.analysis.extraPaths 集合 (預設集合為空白)。例如，如果您使用 Flask，您的 Google App Engine 可能安裝在 app.yaml 中指定的自訂位置。在此情況下，您會如下所示指定這些位置

Windows

"python.analysis.extraPaths": [
    "C:/Program Files (x86)/Google/google_appengine",
    "C:/Program Files (x86)/Google/google_appengine/lib/flask-0.12"]

macOS/Linux

"python.analysis.extraPaths": [
    "~/.local/lib/Google/google_appengine",
    "~/.local/lib/Google/google_appengine/lib/flask-0.12" ]

如需可用的 IntelliSense 控制項完整清單，您可以參考 Python 擴充功能程式碼分析設定和自動完成設定。

您也可以自訂自動完成和 IntelliSense 的一般行為，甚至完全停用這些功能。您可以在自訂 IntelliSense中深入了解。

使用 AI 增強完成

GitHub Copilot 是一種 AI 驅動的程式碼完成工具，可協助您更快、更聰明地撰寫程式碼。您可以使用 VS Code 中的 GitHub Copilot 擴充功能來產生程式碼，或從其產生的程式碼中學習。

GitHub Copilot 為多種語言和各種架構提供建議，而且對於 Python、JavaScript、TypeScript、Ruby、Go、C# 和 C++ 特別有效。

您可以在Copilot 文件中深入了解如何開始使用 Copilot。

導覽

編輯時，您可以按一下滑鼠右鍵不同的識別項，以利用幾個方便的命令

前往定義 (F12) 從您的程式碼跳到定義物件的程式碼。當您使用程式庫時，此命令很有用。
查看定義 (⌥F12 (Windows Alt+F12、Linux Ctrl+Shift+F10)) 類似，但會直接在編輯器中顯示定義 (在編輯器視窗中騰出空間，以避免遮蔽任何程式碼)。按 Escape 鍵關閉 [查看] 視窗，或使用右上角的 x。
前往宣告 跳到程式碼中宣告變數或其他物件的點。
查看宣告 類似，但會直接在編輯器中顯示宣告。同樣地，使用 Escape 鍵或右上角的 x 關閉 [查看] 視窗。

快速修正

新增匯入

使用 Pylance 時，「新增匯入」快速修正可讓您快速完成環境中安裝的模組的 import 陳述式。當您開始在編輯器中輸入套件名稱時，「程式碼動作」可用於自動完成原始碼行。將滑鼠停留在文字 (以波浪線標示) 上，然後選取 [程式碼動作] 燈泡。然後，您可以從潛在的匯入清單中選取。

Add import code action

此「程式碼動作」也辨識下列常見 Python 套件的一些常用縮寫：numpy 為 np、tensorflow 為 tf、pandas 為 pd、matplotlib.pyplot 為 plt、matplotlib 為 mpl、math 為 m、scipi.io 為 spio、以及 scipy 為 sp、panel 為 pn 和 holoviews 為 hv。

Common package abbreviations

匯入建議清單會顯示前 3 個高信賴度匯入選項，其優先順序依據：最近使用的匯入、來自相同模組的符號、來自標準程式庫的符號、來自使用者模組的符號、來自協力廠商套件的符號，最後依模組和符號名稱排序。

搜尋其他匯入相符項目

依預設，「新增匯入」快速修正只會顯示 3 個高信賴度匯入選項。如果它們未列出您要尋找的項目，您可以使用 Pylance 的搜尋其他匯入相符項目快速修正來修正遺失的匯入錯誤。此快速修正會顯示快速挑選功能表，讓您可以搜尋與遺失的匯入符號前置詞相符的匯入選項。

變更拼字

當未解析的變數或遺失的匯入診斷可能由錯字造成時，Pylance 會顯示變更拼字快速修正。此「程式碼動作」會根據工作區中找到的最接近相符項目，建議符號的正確拼字。

Change spelling code action on missing import due to a typo

注意：對於使用者符號，這些快速修正只會建議從定義它們的檔案匯入。不支援從使用者符號為外部/匯入的檔案匯入建議。

另請注意，對於來自已安裝套件的符號 (通常位於 Python 環境的 site-packages 資料夾下)，快速修正只會建議套件根資料夾中定義的符號，例如其 __init__.py 檔案中的符號。您可以透過 python.analysis.packageIndexDepths 設定自訂特定套件的此行為，但請注意，這可能會影響 Pylance 的效能。

重構

Python 擴充功能透過 Pylance 擴充功能新增下列重構功能：提取變數、提取方法、重新命名模組、移動符號和實作所有繼承的抽象類別。它也支援實作其他重構功能的擴充功能，例如排序匯入。

提取變數

提取目前範圍內選取文字的所有類似出現次數，並以新的變數取代。

您可以選取您要提取為變數的程式碼行，來叫用此命令。然後選取程式碼行旁邊顯示的燈泡。

Refactoring a variable

提取方法

提取目前範圍內選取運算式或區塊的所有類似出現次數，並以方法呼叫取代。

您可以選取您要提取為方法的程式碼行，來叫用此命令。然後選取程式碼行旁邊顯示的燈泡。

Refactoring code into a method

重新命名模組

在 Python 檔案/模組重新命名後，Pylance 可以找到可能需要更新的所有執行個體，並為您提供所有變更的預覽。

若要自訂需要更新的參考，您可以在重構預覽中切換行或檔案層級的核取方塊。在您做出選取之後，您可以選取套用重構或捨棄重構。

Renaming a module

移動符號

Pylance 擴充功能提供兩個「程式碼動作」，以簡化將符號移動到不同檔案的程序

將符號移動到...：顯示檔案選取器，以選取要將符號移動到的目的地檔案。
將符號移動到新檔案：建立一個新的檔案，其中包含符號名稱，位於叫用 [程式碼動作] 的來源檔案所在的相同目錄中。

您可以將滑鼠停留在您要移動的符號上，然後選取所需動作旁邊出現的燈泡，來存取這些「程式碼動作」。或者，您可以按一下滑鼠右鍵符號，然後從操作功能表中選取重構...。

Move Symbol refactoring options

實作所有繼承的抽象類別

在 Python 中，抽象類別作為其他類別的「藍圖」，並藉由促進子類別遵守的明確結構和需求，協助組建模組化、可重複使用的程式碼。若要在 Python 中定義抽象類別，您可以建立一個從 abc 模組中的 ABC 類別繼承的類別，並使用 @abstractmethod 裝飾器註釋其方法。然後，您可以建立從此抽象類別繼承的新類別，並定義基底方法的實作。

Pylance 提供「程式碼動作」，以簡化建立這些類別的程序。當您定義從抽象類別繼承的新類別時，您現在可以使用實作所有繼承的抽象類別「程式碼動作」，自動實作父類別中的所有抽象方法和屬性

Implement inherited abstract classes

排序匯入

Python 擴充功能支援 isort 和 Ruff 等擴充功能，這些擴充功能實作排序匯入功能。此命令會將來自相同模組的特定匯入合併成單一 import 陳述式，並依字母順序組織 import 陳述式。

您可以透過安裝支援排序匯入的擴充功能來叫用此功能，然後開啟 [命令面板] (⇧⌘P (Windows、Linux Ctrl+Shift+P)) 並執行組織匯入。

提示：您可以將鍵盤快速鍵指派給 editor.action.organizeImports 命令。

Sorting import statements

疑難排解

如需有關常見 IntelliSense 和 Python 編輯問題的說明，請查看下表

問題	原因	解決方案
Pylance 在新增匯入時只提供最上層符號選項。	依預設，只會編製最上層模組的索引 (深度 = 1)。例如，您可能會看到 `import matplotlib` 作為建議，但依預設不會看到 `import matplotlib.pyplot`。	嘗試透過 `python.analysis.packageIndexDepths` 增加 Pylance 可以為您安裝的程式庫編製索引的深度。查看程式碼分析設定。
Pylance 未自動新增遺失的匯入	自動匯入完成設定可能已停用。	查看啟用自動匯入章節。
自動匯入已啟用，但 Pylance 未自動匯入工作區中其他檔案中定義的符號。	使用者定義的符號 (不是來自已安裝的套件或程式庫的符號) 只有在編輯器中開啟的檔案中已使用過時，才會自動匯入。否則，它們只會透過新增匯入快速修正提供。	使用新增匯入快速修正，或確保先開啟工作區中的相關檔案。
在大型工作區上工作時，Pylance 似乎速度緩慢或消耗太多記憶體。	Pylance 分析是在指定工作區中存在的所有檔案上完成的。	如果有些子資料夾您知道可以從 Pylance 的分析中排除，您可以將它們的路徑新增至 `python.analysis.exclude` 設定。或者，您可以嘗試將 `python.analysis.indexing` 設定為 `false` 以停用 Pylance 的索引器 (注意：這也會影響完成和自動匯入的體驗。在程式碼分析設定中深入了解索引編製)。
您無法將自訂模組安裝到您的 Python 專案中。	自訂模組位於非標準位置 (未使用 pip 安裝)。	將位置新增至 `python.autoComplete.extraPaths` 設定，並重新啟動 VS Code。

Pylance 診斷

依預設，Pylance 會在 [問題] 面板中提供 Python 檔案的診斷。

以下清單是 Pylance 提供的一些最常見診斷，以及如何修正它們。

importResolveSourceFailure

當 Pylance 能夠找到匯入套件的類型 Stub，但無法找到套件本身時，就會發生此錯誤。當您嘗試匯入的套件未安裝在選取的 Python 環境中時，可能會發生這種情況。

修正方法

如果套件已安裝在不同的解譯器或核心中，請選取正確的解譯器。
如果未安裝套件，您可以透過在已啟用的終端機中執行下列命令來安裝它：python -m pip install {package_name}。

importResolveFailure

當 Pylance 無法找到您要匯入的套件或模組，也找不到其類型 Stub 時，就會發生此錯誤。

修正方法

如果您要匯入模組，請確定它存在於您的工作區中，或存在於 python.autoComplete.extraPaths 設定中包含的位置中。
如果您要匯入未安裝的套件，您可以透過在已啟用的終端機中執行下列命令來安裝它：python -m pip install {package_name}。
如果套件已安裝在不同的解譯器或核心中，請選取正確的解譯器。
如果您使用可編輯的安裝，且目前設定為使用匯入 Hook，請考慮切換為只包含檔案路徑的 .pth 檔案，以增強相容性並確保更順暢的匯入行為。在 Pyright 文件中深入了解。

importCycleDetected

當 Pylance 偵測到兩個或多個模組之間的循環相依性時，就會發生此錯誤。

修正方法

嘗試重新排序您的 import 陳述式，以中斷循環相依性。

Pylance 診斷的嚴重性可以透過 python.analysis.diagnosticSeverityOverrides 設定自訂。查看設定參考以取得更多資訊。

後續步驟

程式碼檢查 - 啟用、設定和套用各種 Python 程式碼檢查器。
偵錯 - 學習在本機和遠端偵錯 Python。
測試 - 設定測試環境，並探索、執行和偵錯測試。
基本編輯 - 了解功能強大的 VS Code 編輯器。
程式碼導覽 - 快速瀏覽您的原始碼。
IntelliSense - 了解 IntelliSense 功能。
Jupyter 支援 - 了解如何開始使用 Jupyter Notebooks。
Python 擴充功能範本 - 建立擴充功能以整合您最愛的 Python 工具。

04/03/2025