編輯

在 Visual Studio Code 中編輯 Python

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 基於微軟的 Pyright 靜態型別檢查工具，利用型別存根 (.pyi 檔案) 和惰性型別推斷來提供高效能的開發體驗。

有關 IntelliSense 的更多常規資訊，請參閱 IntelliSense。

提示：檢視適用於 VS Code 的 IntelliCode 擴充套件。IntelliCode 為 Python 中的 IntelliSense 提供了一套 AI 輔助功能，例如根據當前程式碼上下文推斷最相關的自動補全。有關更多資訊，請參閱適用於 VS Code 的 IntelliCode 常見問題解答。

自定義 IntelliSense 行為

預設啟用全套 IntelliSense 功能可能會讓您的開發體驗變慢，因此 Python 擴充套件啟用了一組最基本的功能，讓您在保持高效的同時擁有高效能的體驗。但是，您可以透過多種設定根據自己的喜好自定義分析引擎的行為。

啟用自動匯入

Pylance 為您工作區中的模組和您環境中安裝的包提供自動匯入建議。當您在編輯器中鍵入時，可能會得到補全建議。當您接受建議時，自動匯入會自動將相應的匯入語句新增到您的檔案中。

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

Completion with auto import displayed on the suggestion list

為自定義包位置啟用 IntelliSense

要為安裝在非標準位置的包啟用 IntelliSense，請將這些位置新增到 settings.json 檔案中的 python.analysis.extraPaths 集合中（預設集合為空）。例如，您可能將 Google App Engine 安裝在自定義位置，如果您使用 Flask，則在 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 時，“新增匯入”快速修復功能使您能夠快速完成環境中已安裝模組的匯入語句。當您開始在編輯器中鍵入包名時，會出現一個程式碼操作，可以自動完成該行原始碼。將滑鼠懸停在文字（用波浪線標記）上，然後選擇程式碼操作燈泡。然後，您可以從潛在的匯入列表中進行選擇。

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 能夠找到匯入包的型別存根，但無法找到包本身時，會發生此錯誤。當您嘗試匯入的包未在所選的 Python 環境中安裝時，可能會發生這種情況。

如何修復

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

importResolveFailure

當 Pylance 無法找到您要匯入的包或模組，也無法找到其型別存根時，會發生此錯誤。

如何修復

如果您正在匯入一個模組，請確保它存在於您的工作區中或包含在 python.autoComplete.extraPaths 設定中的位置。
如果您正在匯入一個未安裝的包，您可以在啟用的終端中執行以下命令來安裝它：python -m pip install {package_name}。
如果您正在匯入一個已經安裝在不同直譯器或核心中的包，選擇正確的直譯器。
如果您正在使用可編輯安裝，並且它當前設定為使用匯入鉤子，請考慮切換為使用僅包含檔案路徑的 .pth 檔案，以增強相容性並確保更平滑的匯入行為。在 Pyright 文件中瞭解更多資訊。

importCycleDetected

當 Pylance 檢測到兩個或多個模組之間存在迴圈依賴時，會發生此錯誤。

如何修復

嘗試重新排序您的匯入語句以打破迴圈依賴。

Pylance 診斷的嚴重性可以透過 python.analysis.diagnosticSeverityOverrides 設定進行自定義。有關更多資訊，請檢視設定參考。

後續步驟

程式碼檢查 - 啟用、配置和應用各種 Python 程式碼檢查工具。
除錯 - 瞭解如何在本地和遠端除錯 Python。
測試 - 配置測試環境以及發現、執行和除錯測試。
基本編輯 - 瞭解功能強大的 VS Code 編輯器。
程式碼導航 - 快速瀏覽您的原始碼。
IntelliSense - 瞭解 IntelliSense 功能。
Jupyter 支援 - 瞭解如何開始使用 Jupyter Notebooks。
Python 擴充套件模板 - 建立一個擴充套件以整合您最喜歡的 Python 工具。

09/11/2025