在 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 靜態型別檢查工具為基礎，利用型別存根 (.pyi 檔案) 與延遲型別推論，提供高效能的開發體驗。

關於 IntelliSense 的一般資訊，請參閱 IntelliSense。

提示：請查看 VS Code 的 IntelliCode 擴充功能。IntelliCode 為 Python 的 IntelliSense 提供了一系列 AI 輔助功能，例如根據目前的程式碼內容推論出最相關的自動補全項目。如需詳細資訊，請參閱 VS Code 的 IntelliCode 常見問題集。

自訂 IntelliSense 行為

預設啟用整套 IntelliSense 功能可能會導致您的開發體驗變慢，因此 Python 擴充功能預設啟用了一組最低限度的功能，讓您在保持生產力的同時，也能享有高效能的體驗。不過，您可以透過多種設定，將分析引擎的行為自訂為您偏好的方式。

啟用自動匯入 (Auto Imports)

Pylance 可針對您工作區中的模組以及環境中安裝的套件提供自動匯入建議。當您在編輯器中輸入時，可能會獲得補全建議。當您接受該建議時，自動匯入功能會自動將對應的匯入敘述新增至您的檔案中。

您可以透過在設定中將 python.analysis.autoImportCompletions 設為 true 來啟用自動匯入。預設情況下，自動匯入功能為停用狀態。

Completion with auto import displayed on the suggestion list

為自訂套件位置啟用 IntelliSense

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

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 的入門資訊。

瀏覽導覽

編輯時，您可以對不同的識別碼按右鍵，以利用多種便利的指令：

移至定義 (Go to Definition) (F12) 可從您的程式碼跳轉至定義物件的程式碼。當您使用程式庫時，此指令非常實用。
預覽定義 (Peek Definition) (⌥F12 (Windows Alt+F12, Linux Ctrl+Shift+F10)) 的功能類似，但會直接在編輯器中顯示定義 (並在編輯器視窗中騰出空間，以免遮蔽任何程式碼)。按下 Escape 鍵或使用右上角的 x 即可關閉預覽視窗。
移至宣告 (Go to Declaration) 可跳轉至程式碼中宣告變數或其他物件的位置。
預覽宣告 (Peek Declaration) 的功能類似，但會直接在編輯器中顯示宣告。同樣地，請使用 Escape 鍵或右上角的 x 來關閉預覽視窗。

快速修復

新增匯入 (Add import)

使用 Pylance 時，「新增匯入」快速修正 (Quick Fix) 功能讓您可以快速補全環境中已安裝模組的匯入敘述。當您開始在編輯器中輸入套件名稱時，程式碼動作 (Code Action) 將自動補全該行原始碼。將滑鼠懸停在文字上 (標示有波浪線處) 並選擇程式碼動作燈泡圖示。接著，您可以從潛在的匯入清單中進行選擇。

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 的搜尋額外的匯入比對 (Search for additional import matches) 快速修正。此快速修正會顯示一個快速選擇選單，讓您搜尋與遺失的匯入符號前綴相符的匯入選項。

變更拼寫

當未解析的變數或遺失的匯入診斷很可能是由拼字錯誤引起時，Pylance 會顯示變更拼寫 (Change spelling) 快速修正。此程式碼動作會根據工作區中找到的最接近比對結果，建議正確的符號拼寫。

Change spelling code action on missing import due to a typo

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

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

重構

Python 擴充功能透過 Pylance 擴充功能新增了以下重構功能：提取變數 (Extract Variable)、提取方法 (Extract Method)、重新命名模組 (Rename Module)、移動符號 (Move Symbol) 以及 實作所有繼承的抽象類別 (Implement All Inherited Abstract Classes)。它也支援實作額外重構功能的擴充功能，例如排序匯入 (Sort Imports)。

提取變數

提取目前範圍內選定文字的所有相似出現項目，並將其替換為新變數。

您可以透過選取要提取為變數的程式碼行來呼叫此指令。接著，選擇顯示在旁邊的燈泡圖示即可。

Refactoring a variable

提取方法

提取目前範圍內選定運算式或區塊的所有相似出現項目，並將其替換為方法呼叫。

您可以透過選取要提取為方法的程式碼行來呼叫此指令。接著，選擇顯示在旁邊的燈泡圖示即可。

Refactoring code into a method

重新命名模組

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

若要自訂需要更新的參照，您可以在重構預覽 (Refactor Preview) 中勾選或取消勾選各行或檔案層級的核取方塊。確認選擇後，您可以選擇套用重構 (Apply Refactoring) 或捨棄重構 (Discard Refactoring)。

Renaming a module

移動符號

Pylance 擴充功能提供了兩種程式碼動作，以簡化將符號移動至不同檔案的程序：

移動符號至... (Move symbol to...)：顯示檔案選取器，以選擇符號要移動到的目標檔案。
移動符號至新檔案 (Move symbol to new file)：建立一個以符號命名的新檔案，位於執行程式碼動作的來源檔案所在目錄中。

您可以將滑鼠懸停在要移動的符號上，然後選擇出現在旁邊的燈泡圖示來存取這些程式碼動作。或者，您可以在符號上按右鍵並從內容選單中選擇重構... (Refactor...)。

Move Symbol refactoring options

實作所有繼承的抽象類別

在 Python 中，抽象類別作為其他類別的「藍圖」，透過提升子類別必須遵守的清晰結構與要求，有助於建構模組化且可重複使用的程式碼。若要在 Python 中定義抽象類別，您可以建立一個繼承自 abc 模組中 ABC 類別的類別，並使用 @abstractmethod 裝飾子來註釋其方法。接著，您可以建立繼承自此抽象類別的新類別，並為基底方法定義實作。

Pylance 提供了一項程式碼動作來簡化建立這些類別的過程。當您定義一個繼承自抽象類別的新類別時，現在可以使用實作所有繼承的抽象類別 (Implement all inherited abstract classes) 程式碼動作，自動實作父類別中的所有抽象方法與屬性。

Implement inherited abstract classes

排序匯入

Python 擴充功能支援如 isort 與 Ruff 等實作排序匯入功能的擴充功能。此指令會將來自同一模組的特定匯入項目合併為單一 import 敘述，並按字母順序排列 import 敘述。

您可以透過安裝支援排序匯入的擴充功能來呼叫此功能，接著開啟命令選擇區 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 並執行組織匯入 (Organize Imports)。

提示：您可以為 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 能找到已匯入套件的型別存根，但無法找到套件本身時，會發生此錯誤。當您嘗試匯入的套件未安裝在所選的 Python 環境中時，可能會發生這種情況。
如何修復

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

importResolveFailure
當 Pylance 無法找到您正在匯入的套件或模組，也找不到其型別存根時，會發生此錯誤。
如何修復

如果您正在匯入模組，請確保它存在於您的工作區中，或存在於 `python.autoComplete.extraPaths` 設定所包含的位置內。
如果您正在匯入未安裝的套件，您可以在已啟用的終端機中執行下列指令來安裝它：`python -m pip install {package_name}`。
如果您正在匯入已安裝在不同直譯器或核心中的套件，請選擇正確的直譯器。
如果您使用的是可編輯安裝 (editable install) 且目前設定為使用匯入掛鉤 (import hooks)，請考慮改用僅包含檔案路徑的 `.pth` 檔案，以增強相容性並確保更順暢的匯入行為。深入了解請參閱 Pyright 文件。

importCycleDetected
當 Pylance 偵測到兩個或多個模組之間存在循環依賴關係時，會發生此錯誤。
如何修復

嘗試重新排列您的匯入敘述以打破循環依賴。

Pylance 診斷的嚴重性可以透過 `python.analysis.diagnosticSeverityOverrides` 設定來自訂。詳細資訊請參閱設定參考。
後續步驟

Linting - 啟用、設定並套用各種 Python Linter。
偵錯 - 學習如何在本地與遠端對 Python 程式進行偵錯。

測試 - 設定測試環境，並探索、執行與偵錯測試。

基本編輯 - 了解功能強大的 VS Code 編輯器。

程式碼導覽 - 在原始碼中快速移動。

IntelliSense - 了解 IntelliSense 功能。
Jupyter 支援 - 了解如何開始使用 Jupyter Notebook。
Python 擴充功能範本 - 建立擴充功能以整合您喜愛的 Python 工具。

02/04/2026