Visual Studio 中的 Python 專案

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

專案一律會在 Visual Studio 解決方案內管理。 解決方案可以包含任意數目的專案，這些專案可能會相互參照，例如參考實作擴充模組之 C++ 專案的 Python 專案。 透過此關聯性，當您開始偵錯 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 或 [偵錯>開始偵錯] ） 或當您在 [互動式] 視窗中執行專案時，啟動檔案會執行。 您可以使用鍵盤快速鍵 Shift + Alt + F5 或選擇偵錯，然後在>中執行專案來開啟此視窗。 若要變更啟動檔案，請以滑鼠右鍵按一下要使用的檔案，然後選取 [ 設定為啟動專案 ] （或舊版 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 版中使用。

Template	Description
從現有的 Python 程式碼	從資料夾結構中的現有 Python 程式碼建立 Visual Studio 專案。
Python 應用	為具有單一空白原始檔的新 Python 應用程式提供基本專案結構。 依預設，專案會在預設全域環境的主控台解譯器中執行。 您可以變更 指派不同的環境。
Web 專案	基於各種框架的 Web 應用程序項目，包括 Bottle、Django 和 Flask。
背景應用程式 （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. 若要設定不同的啟動檔案，請在 [方案總管] 中找到該檔案，以滑鼠右鍵按一下該檔案，然後選取 [ 設定為啟動檔案]。

連結的檔案

連結檔案是帶入專案但通常位於應用程式專案資料夾之外的檔案。 這些檔案會在 方案總管 中顯示為一般檔案，並具有重迭的快捷方式圖示：

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

<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 方法調用添加到組件中。 此呼叫通常會新增至程式碼的開頭。 例如，Visual Studio 中的 IronPython Windows Forms 應用程式 （可在 Visual Studio 2019 中使用） 專案範本所建立的程式碼會在檔案頂端包含兩個呼叫：

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 平台安裝程式（WebPI）產品項目的連結，以便部署至 Microsoft Azure 雲端服務，並透過 WebPI 摘要安裝更多的元件。 預設情況下，顯示的提要是特定於 Python 的，包括 Django、CPython 和其他核心元件。 您也可以選取自己的訊息流，如下圖所示。 當您發佈至 Microsoft Azure 時，安裝工作會安裝所有參考的產品。

這很重要

WebPI 專案無法在 Visual Studio 2017 或 Visual Studio 2019 中使用。

相關內容

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