6.1 KiB
在 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 工程文件，推荐继续使用项目根目录已有脚本构建：
.\build-mingw.ps1
构建并运行：
.\build-mingw.ps1 -Run
生成的程序位于：
.vscode-build\mingw\Tetris.exe
因为运行时需要读取 assets/ 目录中的图片、音频和视频资源，建议从项目根目录启动程序，避免资源路径失效。
2. 安装 Visual Studio 2026
- 打开 Visual Studio 2026 下载页面或 Visual Studio Installer。
- 安装 Visual Studio 2026 Community、Professional 或 Enterprise 均可。
- 在安装器中选择
Desktop development with C++工作负载。 - 保留默认的 Windows SDK 和 C++ 工具组件。
- 完成安装后启动 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。
推荐满足以下任一条件：
g++.exe和windres.exe已加入系统PATH。- MinGW-w64 安装在：
C:\mingw64\bin\
可在 PowerShell 中检查：
g++ --version
windres --version
如果提示找不到命令，需要安装 MinGW-w64，或把 MinGW-w64 的 bin 目录加入系统环境变量 PATH。
4. 在 Visual Studio 2026 中打开项目
- 启动 Visual Studio 2026。
- 在开始窗口选择
Open a local folder，或在菜单中选择File -> Open -> Folder...。 - 选择项目根目录：
D:\VSC_program\Tereis
- 等待 Visual Studio 扫描文件。
- 在 Solution Explorer 中查看
src、assets、build-mingw.ps1等文件。
Microsoft Learn 说明，Visual Studio 的 Open Folder 模式适合打开没有专用工程文件的代码库；对于无法被 IDE 自动识别的构建系统，可以通过自定义任务配置构建命令。
5. 在 Visual Studio 终端中构建和运行
这是最简单、最推荐的方式。
- 在 Visual Studio 2026 中打开菜单
View -> Terminal。 - 确认终端当前目录是项目根目录。如果不是，执行：
cd D:\VSC_program\Tereis
- 只构建：
.\build-mingw.ps1
- 构建并启动游戏：
.\build-mingw.ps1 -Run
如果 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，然后参考以下内容配置：
{
"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。
处理：
g++ --version
如果命令失败，请安装 MinGW-w64，或把 C:\mingw64\bin 加入系统 PATH。
找不到 windres.exe
原因：资源编译器不可用。项目需要它编译 src\resources\Tetris.rc 中的图标、菜单和字符串资源。
处理：确认 MinGW-w64 安装完整，并检查：
windres --version
程序启动后没有图片、音乐或视频
原因：程序没有从项目根目录启动，导致相对路径下的 assets/ 资源无法读取。
处理：在项目根目录执行：
.\build-mingw.ps1 -Run
或手动启动：
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