MouseHighlighter/BUILD.md

MouseHighlighter - 编译指南

本文档提供详细的编译步骤和故障排除方法。

前提条件检查清单

• Windows 7 + SP1 或更高版本
• Visual Studio 2019 Community/Professional/Enterprise
• Windows 10 SDK (Build 19041 或更高)
• CMake 3.15+ 或集成构建工具
• C++17 兼容编译器

验证 Windows SDK 版本

1. 打开 Visual Studio Installer
2. 检查 "Windows 10 SDK (version xxxx)" 是否已安装
3. 如未安装，点击 "Modify" 并勾选 SDK 组件

编译方法

方法 1: Visual Studio IDE (推荐新手)

步骤 1: 打开项目

1. 启动 Visual Studio 2019+
2. 文件 → 打开 → CMake
3. 选择 mousehighline 文件夹中的 CMakeLists.txt

Visual Studio 将自动加载 CMake 项目配置。

步骤 2: 配置构建类型

1. 顶部"配置下拉菜单"，选择 x64-Release
2. Build → Regenerate CMake Cache (如首次加载)

步骤 3: 编译

1. Build → Build All (Ctrl+Shift+B)
2. 或右键 CMakeLists.txt → Build

输出文件位置：

mousehighline\build\Release\MouseHighlighter.exe

步骤 4: 运行

1. 调试 → 不调试情况下启动 (Ctrl+F5) 或
2. 从文件资管器直接运行 build/Release/MouseHighlighter.exe

方法 2: 命令行 (更加可控)

步骤 1: 打开开发者命令提示符

1. 按 Windows 键
2. 搜索 "Developer Command Prompt for VS 2019" (或对应版本)
3. 以管理员身份运行

步骤 2: 导航到项目目录

cd D:\Code\Project\mousehighline

步骤 3: 创建构建目录

if not exist build mkdir build
cd build

步骤 4: 生成 Visual Studio 项目文件

cmake -G "Visual Studio 17 2022" -A x64 ..
或者mingw+cmake
"D:\Compiler\cmake\bin\cmake.exe" -G "MinGW Makefiles" ..

可能的生成器选项：

• "Visual Studio 16 2019" - VS2019
• "Visual Studio 17 2022" - VS2022
• 或使用 cmake -G 查看完整列表

步骤 5: 编译

使用 CMake:

cmake --build . --config Release

使用 MSBuild (速度更快):

msbuild MouseHighlighter.sln /p:Configuration=Release /p:Platform=x64

使用 Visual Studio UI:

start MouseHighlighter.sln

然后在 VS 中按 Ctrl+Shift+B

步骤 6: 运行

.\Release\MouseHighlighter.exe

方法 3: 高级 - 使用 Ninja 构建

适合想要最快编译速度的用户。

前提

# 安装 Ninja
choco install ninja

编译

cd mousehighline
mkdir build && cd build
cmake -G "Ninja" -DCMAKE_BUILD_TYPE=Release ..
ninja

故障排除

编译错误

错误 1: "找不到 windows.h"

症状：

fatal error C1083: Cannot open include file: 'windows.h'

解决方法：

1. 打开 Visual Studio Installer → Modify
2. 勾选 "Desktop development with C++" 工作负载
3. 确保 "Windows 10 SDK" 已选中
4. 点击 Modify 并等待安装完成

错误 2: "dwmapi.lib 找不到"

症状：

error LNK1104: cannot open file 'dwmapi.lib'

解决方法：

1. 确认 CMakeLists.txt 中有 dwmapi 库链接
2. 手动验证 SDK 库路径：

   C:\Program Files (x86)\Windows Kits\10\Lib\<build>\um\x64\
   

3. 如路径不同，修改 CMakeLists.txt 中的链接路径

错误 3: C++17 特性未被识别

症状：

error C4002: too many arguments for macro invocation
error C2440: 'initializing'

解决方法：

1. 检查 CMakeLists.txt 中 set(CMAKE_CXX_STANDARD 17) 是否存在
2. 在 Visual Studio 中进行重新配置：

   Build → Regenerate CMake Cache
   

错误 4: "std::atomic 相关错误"

症状：

error C2668: 'std::atomic<T>::store': ambiguous call to overloaded function

解决方法：

• 确保未定义 _WIN32_WINNT 为过低版本 (应 ≥ 0x0601)
• CMakeLists.txt 中已指定 C++17 标准

运行错误

错误 1: "应用程序无法正常启动"

症状：

应用程序无法正常启动 (0xc0000135)

解决方法：

1. 检查 Visual C++ Runtime 是否已安装
   • 下载：https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads
   • 选择对应 VS 版本的 Runtime
2. 或用 CMake 配置为静态链接：
   • 修改 CMakeLists.txt 中的 MSVC_RUNTIME_LIBRARY

错误 2: "鼠标高亮未显示"

症状：

• 运行无错误，但看不到鼠标高亮效果

检查步骤：

1. 确认 DWM 已启用：

   Get-Service dwm | Select Status
   

   应输出 "Running"

2. 检查是否在全屏应用 (如游戏) 中

   • 分层窗口在独占模式下被隐藏 (正常行为)
   • 退出全屏游戏后应恢复

3. 查看托盘图标是否存在：

   • 右下角"显示隐藏的图标"
   • 应能看到 MouseHighlighter 图标

4. 检查权限：

   • 以管理员身份运行
   • 右键 → 以管理员身份运行

错误 3: 高 CPU 占用

症状：

• 鼠标静止时 CPU 占用 > 5%

诊断：

1. 打开任务管理器 → 性能
2. 额外检查是否有其他钩子冲突
3. 查看 config.ini 中 TargetFPS 配置

解决方法：

1. 降低目标 FPS：

   [Timing]
   TargetFPS=30
   

2. 检查系统是否有其他全局钩子工具运行 (截图工具、输入法等)

错误 4: 重复运行时崩溃

症状：

• 第一次运行正常，关闭后重新运行崩溃
• 或"钩子已被注册"错误

解决方法：

1. 检查是否有残留进程：

   Get-Process MouseHighlighter -ErrorAction SilentlyContinue
   

2. 手动结束进程：

   Stop-Process -Name MouseHighlighter -Force
   

3. 重启应用

性能问题

问题 1: 帧率不稳定 (出现卡顿)

症状：

• 鼠标移动时间断卡顿

检查：

1. CPU 占用是否稳定 (应 ≤ 5%)
2. 磁盘 I/O 是否正常

解决方法：

1. 降低渲染目标 FPS：

   TargetFPS=30
   

2. 禁用坐标平滑 (仅在需要时启用)：

   [Smoothing]
   Alpha=0.0
   

问题 2: 内存占用持续增长

症状：

• 运行数小时后内存从 30MB 增长到 100+ MB

诊断步骤：

1. 检查 GDI 对象数：

   // 在监控线程输出中查看
   

2. 使用 Performance Monitor (perfmon.exe) 追踪：
   • 打开 → Process → 添加计数器 → GDI Objects

解决方法：

• 这通常表示 GDI 资源泄漏 (Developer 问题)
• 报告给开发者并附上内存快照

生成发布版本

创建可发布的二进制文件

cd mousehighline
mkdir build_release
cd build_release

# 生成 Release 配置
cmake -G "Visual Studio 16 2019" -A x64 -DCMAKE_BUILD_TYPE=Release ..

# 编译
cmake --build . --config Release

# 输出文件位置
# build_release/Release/MouseHighlighter.exe

打包应用

# 创建发布目录
mkdir MouseHighlighter_v1.0.0

# 复制必要文件
copy build_release/Release/MouseHighlighter.exe MouseHighlighter_v1.0.0/
copy README.md MouseHighlighter_v1.0.0/

# 创建压缩包
# (使用 7-Zip、WinRAR 等)

关键编译标志

CMake 变量自定义

# 静态链接 Runtime (推荐发布版)
cmake -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedRelease ..

# 定义 Windows 最低版本
cmake -DWIN32_LEAN_AND_MEAN=ON ..

# 启用链接时优化 (LTO)
cmake -DCMAKE_INTERPROCEDURAL_OPTIMIZATION=ON ..

调试技巧

启用调试符号

cmake -DCMAKE_BUILD_TYPE=Debug ..

在 Visual Studio 中调试

1. 从 VS 打开 CMake 项目
2. 调试 → 启动调试 (F5)
3. 设置断点，观察变量

控制台日志输出

启用监控线程的日志输出 (Config.h 中编译条件)：

monitoring.logToFile = true;

最佳实践

1. 始终编译 Release 版本用于日常使用

   • Debug 版本性能下降 50-70%

2. 定期清理构建输出

   rm -r build/
   mkdir build && cd build
   

3. 使用 .gitignore 避免检入编译文件

   • 已提供，无需额外配置

4. 保持 CMake 缓存最新

   Build → Regenerate CMake Cache
   

获取帮助

• 检查 README.md 中的"常见问题"
• 查看编译错误的确切行号与文件
• 在 GitHub Issues 报告问题（包括编译环境信息）

下一步

编译成功后：

1. 运行应用
2. 阅读 README.md 了解使用方法
3. 检查 config.ini 的配置选项
4. 右键托盘图标调整设置