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，或者通过选择“调试>在 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. 若要设置其他启动文件，请在“解决方案资源管理器”中找到该文件，右键单击该文件，然后选择“设置为启动文件”。

链接文件

链接文件是指放入项目，但通常位于应用程序项目文件夹外的文件。 这些文件在“解决方案资源管理器”中显示为普通文件，具有重叠的快捷方式图标：

链接文件通过 <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。

因为在调用 clr.AddReference('<AssemblyName>') 方法后才能使用 IronPython 中的引用，所以还需要向程序集添加适当的 clr.AddReference 方法调用。 此调用通常添加在代码开头。 例如，在 Visual Studio 中通过“IronPython Windows 窗体应用程序”（在 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 支持