Visual Studio 中的 Python 專案

Python 應用程式通常只使用資料夾和檔案來定義。 隨著應用程式成長，此結構可能會變得複雜，而且可能涉及自動產生的檔案、Web 應用程式的 JavaScript 等等。 Visual Studio 專案可幫助您管理此複雜性。 專案 (.pyproj 檔案) 會識別與您專案相關聯的所有來源和內容檔案。 它包含每個檔案的組建資訊、維護要與來源控制系統整合的資訊，以及協助您將應用程式組織成邏輯元件。

專案一律會在 Visual Studio 方案中管理。 方案可以包含任意數目的專案，這些專案可能彼此參考，例如一個 Python 專案參考實作延伸模組的 C++ 專案。 透過此關聯性，當您開始對 Python 專案進行偵錯時，Visual Studio 就會自動建置 C++ 專案 (如有必要)。 如需詳細資訊，請參閱 Visual Studio 中解決方案和專案。

Visual Studio 提供各種 Python 專案範本，可快速建立數種類型的應用程式結構。 您可以選擇範本，從現有的資料夾樹狀結構建立專案，或建立全新的空白專案。 如需可用範本的清單，請參閱 專案範本一節中的表格。

使用 Python 專案的秘訣

要在 Visual Studio 中執行 Python 程式碼，您不一定要使用專案，但這麼做有好處。 當您開始使用時，請檢閱下列有關使用專案和 Python 的考量事項。

• 在 Visual Studio 2019 和更新版本中，您開啟包含 Python 程式碼的資料夾，並執行該程式碼，無須建立 Visual Studio 專案和方案檔案。

  快速入門：在資料夾中開啟並執行 Python 程式碼文章中有提供本方法的引導式步驟。

• 您不需要專案也可以在 Visual Studio 中執行 Python 程式碼。 所有的 Visual Studio 版本都能搭配 Python 程式碼順利運作。

  您可以自行開啟 Python 檔案，並立即存取自動完成、IntelliSense 和偵錯功能。 不過，在不使用專案的情況下使用程式碼有一些潛在的缺點：

  • 因為程式碼一律會使用預設全域環境，所以如果程式碼是針對不同的環境，您可能就會看到完成不正確或錯誤。
  • 從資料夾中開啟單個檔案時，Visual Studio 會分析當中所有的檔案和套件。 此程序可能會耗用相當長的 CPU 時間。

• 您可以從現有的程式碼建立 Visual Studio 專案。 從現有的檔案建立專案一節中有描述此方法。

基本專案工作：檔案、環境和啟動

當您搭配 Python 程式碼使用專案時，您可以完成基本工作，包括新增檔案、指派啟動檔案，以及設定 Python 解譯器環境。

當您開發應用程式時，通常需要將不同類型的新檔案新增至您的專案中。 新增更多檔案很容易。 以滑鼠右鍵按一下您的專案，選取 [新增]>[現有項目]，然後瀏覽以尋找要新增的檔案類型。 [新增]>[新增項目] 選項會開啟對話方塊，顯示可用來建立新檔案的項目範本。 選項包括空白 Python 檔案、Python 類別、單元測試和各種與 Web 應用程式相關的檔案。 您可以使用測試專案來探索範本選項，以了解您的 Visual Studio 版本中提供了哪些選項。 如需詳細資訊，請參閱項目範本參考。

每個 Python 專案都有一個指派的啟動檔案，在 [方案總管] 中以粗體顯示。 啟動檔案會在您開始偵錯時執行 (選取 F5 或 [偵錯]>[開始偵錯])，或在 [Interactive] 視窗中執行專案時執行。 您可以使用鍵盤快速鍵 Shift + Alt + F5 開啟此視窗，或選取 [偵錯]>[在 Python Interactive 中執行專案]。 若要變更啟動檔案，以滑鼠右鍵按一下檔案以使用並選取 [設定為啟動項目] (或者，在較舊的 Visual Studio 版本中選取 [設定為啟動檔案])。

如果您從專案中移除選取的啟動檔案，且未選取替代檔案，Visual Studio 不會知道要使用哪一個 Python 檔案來啟動專案。 在此情況下，Visual Studio 2017 15.6 版和更新版本會顯示錯誤。 舊版會開啟輸出視窗並執行 Python 解譯器，或是輸出視窗會開啟，而後立即關閉。 如果您遇到這些行為，請確認您已指派啟動檔案。

提示

若要使輸出視窗保持開啟狀態，以滑鼠右鍵按一下專案，然後選取 [屬性]。 在對話方塊中，選取 [偵錯] 索引標籤，然後將 -i 旗標新增至 [解譯器引數] 欄位。 此參數會導致解譯器在程式完成後進入互動式模式。 視窗會保持開啟狀態，直到您關閉為止，例如使用鍵盤快速鍵 Ctrl+E+Enter。

新專案一律會與預設的全域 Python 環境關聯。 若要將專案與其他環境 (包括虛擬環境) 相關聯，請以滑鼠右鍵按一下專案中的 [Python 環境] 節點。 選擇 [新增環境]，然後選擇所要的環境。 您也可以使用工具列上的環境下拉式控制項以選取一個環境，或在專案中新增另一個環境。

若要變更使用中環境，在 [方案總管] 中以滑鼠右鍵按一下所需的環境，然後選取 [啟用環境]，如下圖所示。 如需詳細資訊，請參閱選取專案的環境。

專案範本

Visual Studio 提供您許多方法來建立 Python 專案，不論是從頭開始或是從現有的程式碼，都可以。 若要使用範本，請選擇 [檔案]>[新增]>[專案]或在 [方案總管]中以滑鼠右鍵按兩下方案，然後選擇 [新增]>[新增專案]。 在 [新增專案] 對話方塊中，您可以藉由搜尋 Python 或選取 [語言]>[Python] 節點來查看 Python 特定的範本：

Visual Studio 2022 版提供下列範本。

範本	描述
從現有 Python 程式碼	從資料夾結構中的現有 Python 程式碼建立 Visual Studio 專案。
Python 應用程式	使用單一空白原始程式檔案為新 Python 應用程式提供基本專案結構。 預設情況下，專案會在預設全域環境的控制台解譯器中執行。 您可以變更指派不同的環境。
Web 專案	針對以各種不同的架構 (包括 Bottle、Django 和 Flask) 為基礎的 Web 應用程式專案。
背景應用程式 (IoT)	支援將 Python 專案部署成在裝置上以背景服務的形式執行。 如需詳細資訊，請參閱 Windows IoT 開發人員中心。
Python 延伸模組	如果您已在 Visual Studio 2017 或更新版本中安裝 Python 原生開發工具與 Python 工作負載 (請參閱安裝)，此範本會出現在 Visual C++ 下。 該範本提供的 C++ 延伸模組 DLL 的核心結構，類似於建立適用於 Python 的 C++ 延伸模組中所述的結構。

注意

因為 Python 是解譯式語言，所以 Visual Studio 中的 Python 專案不會產生其他編譯式語言專案 (例如 C#) 所產生的獨立式可執行檔。 如需詳細資訊，請參閱問與答。

從現有的檔案建立專案

請遵循下列步驟，從現有的檔案建立專案。

重要

下列程序不會移動或複製任何原始來源檔案。 如果您想要使用檔案的複本，請先複製資料夾，再建立專案。

1. 啟動 Visual Studio，然後選取 [檔案]>[新增]>[專案]。

2. 在 [建立新專案] 對話方塊中，搜尋 python，然後選取 [從現有的 Python 程式碼] 範本，然後選擇 [下一步]。

3. 在 [設定新專案] 對話方塊中，輸入專案名稱和位置，選擇包含該專案的解決方案，然後選擇 [建立]。

4. 在從現有 Python 程式碼建立新專案精靈中，將資料夾路徑設為現有程式碼，為檔案類型設定篩選條件，並指定專案所需的任何搜尋路徑，然後選擇 [下一步]。 如果您不知道搜尋路徑，請將該欄位留白。

   

5. 在下一頁上，選擇專案的啟動檔案。 Visual Studio 會選取預設的全域 Python 解譯器和版本。 您可以使用下拉式功能表來變更環境。 在您準備就緒後，選取 [下一步]。

   注意

   對話方塊只會顯示根資料夾中的檔案。 如果您想要的檔案位於子資料夾中，請將啟動檔案保留空白。 您可以在方案總管中設定啟動檔案，如後續步驟所述。

   

6. 選取要儲存專案檔的位置 (磁碟上的 .pyproj 檔案)。 適合的話，您也可以包含虛擬環境的自動偵測，以及自訂適用於不同 Web 架構的專案。 如果您不確定這些選項，請將欄位設為預設值。

   

7. 選取 [完成]。

   Visual Studio 隨即建立專案，並在 [方案總管] 中開啟該專案。 如果您想要將 .pyproj 檔案移至不同的位置，請選取方案總管中的檔案，然後選取工具列上的 [檔案]>[另存新檔]。 此動作會更新專案中的檔案參考，但不會移動任何程式碼檔案。

8. 若要設定不同的啟動檔案，請在 [方案總管] 中找出檔案，並以滑鼠右鍵按一下該檔案，然後選取 [設定為啟動檔案]。

連結的檔案

連結的檔案就是已導入專案中但通常位於應用程式專案資料夾外的檔案。 這些檔案在 [方案總管]中會顯示為具有重疊捷徑圖示的一般檔案：

連結的檔案是在 .pyproj 檔案中使用 <Compile Include="..."> 元素來指定的。 如果連結的檔案使用目錄結構之外的相對路徑，便是隱含 。 如果檔案使用 [方案總管]內的路徑，則連結的檔案則是明確。 下列範例顯示明確連結的檔案：

<Compile Include="..\test2.py">
    <Link>MyProject\test2.py</Link>
</Compile>

在下列情況下，會忽略連結的檔案：

• 連結的檔案包含 Link 中繼資料，且 Include 屬性中指定的路徑位於專案目錄內。
• 連結的檔案會複製專案階層中已存在的檔案。
• 連結的檔案包含 Link 中繼資料，且 Link 路徑是位於專案階層外的相對路徑。
• 連結路徑是根目錄。

使用連結的檔案

若要新增現有的項目作為連結，請在專案中以滑鼠右鍵按一下您要新增檔案的資料夾，並選取 [新增]>[現有項目]。 在對話方塊中，選取檔案，然後選取 [新增]>[新增為連結]。 如果沒有任何衝突檔案，此命令會在選取的資料夾中建立連結。 不過，如果存在相同名稱的現有檔案，或專案中已存在該檔案的連結，就不會新增連結。

如果您嘗試連結到已經存在於專案資料夾中的檔案，則該檔案會新增為一般檔案，而不是連結。 若要將檔案轉換為連結，請選取 [檔案]>[另存新檔]，將檔案儲存到專案階層之外的位置。 Visual Studio 會自動將檔案轉換成連結。 同樣地，您也可以使用 [檔案]>[另存新檔] 來將檔案儲存在專案階層內的某個位置。

如果您在 [方案總管] 中移動某個連結的檔案，則會移動該連結，但實際的檔案不受影響。 同樣地，刪除某個連結將會移除該連結，但不會影響檔案。

您無法重新命名連結的檔案。

參考資料

Visual Studio 專案支援新增對專案和延伸模組的參考，這些參考會顯示在 [方案總管] 中的 [參考] 節點底下：

擴充功能參考通常會指出專案之間的相依性，並可用來在設計階段提供 IntelliSense 或在編譯階段提供連結。 Python 專案使用參考的方式類似，但由於 Python 的動態本質緣故，因此主要是在設計階段使用參考來提供改進的 IntelliSense。 您也可以使用它們來部署到 Microsoft Azure 以安裝其他相依性。

使用延伸模組

對 .pyd 檔案的參考可以為產生的模組啟用 IntelliSense。 Visual Studio 會將 .pyd 檔案載入到 Python 解譯器，並自我檢查其類型和函式。 Visual Studio 也會嘗試剖析文件字串來找出提供簽章說明的函式。

在任何時候，只要更新磁碟上的延伸模組，Visual Studio 就會在背景中重新分析該模組。 此動作不會影響執行階段行為，但在分析完成前，可能會無法使用某些完成。

您可能也需要新增包含該模組之資料夾的搜尋路徑。

使用 .NET 專案

使用 IronPython 時，您可以新增對 .NET 組件的參考來啟用 IntelliSense。 對於方案總管中的 .NET 專案，以滑鼠右鍵按一下 Python 專案中的 [參考] 節點，然後選取 [新增參考]。 在對話方塊中，選取 [專案] 索引標籤，然後瀏覽至所需的專案。 針對您已個別下載的 DLL，請改選 [瀏覽] 索引標籤，然後瀏覽至想要的 DLL。

由於 IronPython 中的參考在呼叫 clr.AddReference('<AssemblyName>') 方法後才可用，因此您還需要將適當的 clr.AddReference 方法新增至組件。 此呼叫通常會在程式碼開頭新增。 例如，IronPython Windows Forms 應用程式 (可在 Visual Studio 2019 中取得) 專案範本在 Visual Studio 中建立的程式碼在檔案頂端包含兩個呼叫：

import clr
clr.AddReference('System.Drawing')
clr.AddReference('System.Windows.Forms')

from System.Drawing import *
from System.Windows.Forms import *

# Other code omitted

使用 WebPI 專案

您可以新增對 Web Platform Installer (WebPI) 產品項目的參考以供部署到 Microsoft Azure 雲端服務，然後在該處透過 WebPI 摘要來安裝更多元件。 根據預設，顯示的摘要為 Python 特定，並且包含 Django、CPython 及其他核心元件。 您也可以選取自己的摘要，如下圖所示。 當您發佈到 Microsoft Azure 時，安裝作業將會安裝所有參考的產品。

重要

WebPI 專案在 Visual Studio 2017 或 Visual Studio 2019 中不可用。

相關內容

• Visual Studio 中的解決方案和專案
• 選取專案的環境
• 在 Visual Studio 中安裝 Python 支援