# 在 Visual Studio 2026 中运行本项目

本文说明如何在 Visual Studio 2026 中打开、构建和运行本项目。  
本文档编写时的日期为 2026-05-08，Visual Studio 2026 已发布；Microsoft Learn 的发布历史显示 2026 年 4 月 28 日稳定通道版本为 18.5.2。

## 1. 项目构建方式说明

本项目是一个基于 C++、Win32 API、GDI/GDI+ 和 MinGW-w64 的俄罗斯方块程序。

项目当前没有 Visual Studio `.sln` 或 `.vcxproj` 工程文件，推荐继续使用项目根目录已有脚本构建：

```powershell
.\build-mingw.ps1
```

构建并运行：

```powershell
.\build-mingw.ps1 -Run
```

生成的程序位于：

```text
.vscode-build\mingw\Tetris.exe
```

因为运行时需要读取 `assets/` 目录中的图片、音频和视频资源，建议从项目根目录启动程序，避免资源路径失效。

## 2. 安装 Visual Studio 2026

1. 打开 Visual Studio 2026 下载页面或 Visual Studio Installer。
2. 安装 Visual Studio 2026 Community、Professional 或 Enterprise 均可。
3. 在安装器中选择 `Desktop development with C++` 工作负载。
4. 保留默认的 Windows SDK 和 C++ 工具组件。
5. 完成安装后启动 Visual Studio 2026。

说明：Microsoft Learn 的 Visual Studio 安装文档建议通过工作负载选择所需功能；C++ 桌面开发应选择 C++ 桌面开发相关工作负载。Visual Studio 2026 系统要求页面说明其支持 Windows 11、Windows Server 2025/2022/2019 等 64 位系统。

## 3. 安装或确认 MinGW-w64

本项目的构建脚本调用的是 `g++.exe` 和 `windres.exe`，因此只安装 Visual Studio 2026 还不够，还需要 MinGW-w64。

推荐满足以下任一条件：

1. `g++.exe` 和 `windres.exe` 已加入系统 `PATH`。
2. MinGW-w64 安装在：

```text
C:\mingw64\bin\
```

可在 PowerShell 中检查：

```powershell
g++ --version
windres --version
```

如果提示找不到命令，需要安装 MinGW-w64，或把 MinGW-w64 的 `bin` 目录加入系统环境变量 `PATH`。

## 4. 在 Visual Studio 2026 中打开项目

1. 启动 Visual Studio 2026。
2. 在开始窗口选择 `Open a local folder`，或在菜单中选择 `File -> Open -> Folder...`。
3. 选择项目根目录：

```text
D:\VSC_program\Tereis
```

4. 等待 Visual Studio 扫描文件。
5. 在 Solution Explorer 中查看 `src`、`assets`、`build-mingw.ps1` 等文件。

Microsoft Learn 说明，Visual Studio 的 `Open Folder` 模式适合打开没有专用工程文件的代码库；对于无法被 IDE 自动识别的构建系统，可以通过自定义任务配置构建命令。

## 5. 在 Visual Studio 终端中构建和运行

这是最简单、最推荐的方式。

1. 在 Visual Studio 2026 中打开菜单 `View -> Terminal`。
2. 确认终端当前目录是项目根目录。如果不是，执行：

```powershell
cd D:\VSC_program\Tereis
```

3. 只构建：

```powershell
.\build-mingw.ps1
```

4. 构建并启动游戏：

```powershell
.\build-mingw.ps1 -Run
```

如果 PowerShell 阻止脚本运行，可临时使用：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\build-mingw.ps1 -Run
```

## 6. 可选：在 Visual Studio 中配置 Open Folder 构建任务

如果希望在 Visual Studio 的 Open Folder 模式中通过任务执行构建，可以添加 `tasks.vs.json`。Microsoft Learn 说明，`tasks.vs.json` 用于定义自定义构建命令，`launch.vs.json` 用于定义调试启动配置。

可在 Visual Studio 中右键项目文件夹，选择 `Configure Tasks`，然后参考以下内容配置：

```json
{
  "version": "0.2.1",
  "tasks": [
    {
      "taskName": "Build Tetris with MinGW",
      "appliesTo": "/",
      "type": "launch",
      "command": "powershell.exe",
      "args": [
        "-NoProfile",
        "-ExecutionPolicy",
        "Bypass",
        "-File",
        "${workspaceRoot}\\build-mingw.ps1"
      ],
      "workingDirectory": "${workspaceRoot}"
    },
    {
      "taskName": "Build and Run Tetris with MinGW",
      "appliesTo": "/",
      "type": "launch",
      "command": "powershell.exe",
      "args": [
        "-NoProfile",
        "-ExecutionPolicy",
        "Bypass",
        "-File",
        "${workspaceRoot}\\build-mingw.ps1",
        "-Run"
      ],
      "workingDirectory": "${workspaceRoot}"
    }
  ]
}
```

注意：Visual Studio 可能把该文件放在隐藏的 `.vs` 目录中。该目录通常是本机配置，不一定需要提交到仓库。

## 7. 常见问题

### 找不到 `g++.exe`

原因：未安装 MinGW-w64，或 MinGW-w64 的 `bin` 目录没有加入 `PATH`。

处理：

```powershell
g++ --version
```

如果命令失败，请安装 MinGW-w64，或把 `C:\mingw64\bin` 加入系统 `PATH`。

### 找不到 `windres.exe`

原因：资源编译器不可用。项目需要它编译 `src\resources\Tetris.rc` 中的图标、菜单和字符串资源。

处理：确认 MinGW-w64 安装完整，并检查：

```powershell
windres --version
```

### 程序启动后没有图片、音乐或视频

原因：程序没有从项目根目录启动，导致相对路径下的 `assets/` 资源无法读取。

处理：在项目根目录执行：

```powershell
.\build-mingw.ps1 -Run
```

或手动启动：

```powershell
Start-Process .\.vscode-build\mingw\Tetris.exe -WorkingDirectory .
```

### 直接按 F5 没有运行

原因：本项目当前不是 Visual Studio `.sln` / `.vcxproj` 工程，Visual Studio 不一定知道应使用 `build-mingw.ps1` 构建。

处理：优先使用 Visual Studio 终端运行构建脚本；如果需要 IDE 菜单任务，可按第 6 节配置 `tasks.vs.json`。

## 8. 参考资料

- Visual Studio 2026 Release Notes: <https://learn.microsoft.com/visualstudio/releases/vs18/release-notes>
- Visual Studio 2026 Release History: <https://learn.microsoft.com/en-us/visualstudio/releases/2026/release-history>
- Visual Studio 2026 System Requirements: <https://learn.microsoft.com/en-us/visualstudio/releases/2026/vs-system-requirements>
- Install Visual Studio: <https://learn.microsoft.com/en-us/visualstudio/install/install-visual-studio>
- Create build and debug tasks for Open Folder development: <https://learn.microsoft.com/en-us/visualstudio/ide/customize-build-and-debug-tasks-in-visual-studio>