204 lines
6.1 KiB
Markdown
204 lines
6.1 KiB
Markdown
# 在 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>
|