补充vs使用文档

2026-05-08 16:13:48 +08:00
parent 70b1665b31
commit a0bae4b6b8
1 changed files with 203 additions and 0 deletions
@@ -0,0 +1,203 @@
+# 在 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>