本指南基于实际构建经验编写，适用于在 Windows 10/11 环境下使用 Visual Studio 2022 和 vcpkg 从源码编译 AirPodsDesktop 项目。

---

前置要求

工具/组件	版本要求	备注
PowerShell	7.5.4 或更高版本	避免脚本执行策略、代理、路径等问题。Windows 自带 5.1 可能不足。
Visual Studio	2022 (17.x)	安装时勾选“使用 C++ 的桌面开发”工作负载，包含 MSVC v143 和 Windows SDK。
CMake	3.20+	可从 cmake.org 下载，或通过 winget install CMake。
Git	任意版本	用于克隆仓库和 vcpkg。
Qt	5.15.2 (msvc2019_64)	必须下载 Qt 5.15.2 的 MSVC 2019 64-bit 版本。
vcpkg	最新版	用于自动管理 C++ 依赖库（Boost, cpr, nlohmann-json 等）。

注意：虽然 Windows PowerShell 5.1 可能勉强可用，但实践中常遇到代理设置失败、下载超时、脚本执行错误等问题。强烈建议升级到 PowerShell 7 后再进行构建。

---

第一步：安装必需软件

1. 升级 PowerShell 到 7.x（如果当前版本 < 7）

查看当前版本：

powershell

$PSVersionTable.PSVersion

若显示 Major 为 5 或更低，请按以下方法升级：

• 方法一：使用 Winget（推荐，管理员终端）

  powershell

  winget install --id Microsoft.PowerShell --source winget

• 方法二：下载 MSI 安装包
  访问 PowerShell GitHub Releases，下载 PowerShell-7.5.4-win-x64.msi（或更高版本）并安装。

• 方法三：Microsoft Store
  打开 Store，搜索 “PowerShell”，安装由 Microsoft Corporation 发布的版本。

安装完成后，重新打开终端，输入 pwsh 即可进入 PowerShell 7 环境。后续所有命令都建议在 pwsh 中执行。

2. 安装 Visual Studio 2022

• 从 Visual Studio 官网 下载 Community 2022。

• 运行安装程序，选择工作负载 “使用 C++ 的桌面开发”。

• 确认已包含 MSVC v143 工具集和 Windows 10/11 SDK。

3. 安装 CMake

• 下载并安装 CMake（安装时可选择“将 CMake 添加到系统 PATH”）。

• 验证安装：cmake --version

4. 安装 Git

• 从 git-scm.com 下载并安装。建议保持默认选项。

5. 安装 Qt 5.15.2

使用 aqtinstall安装 Qt 5.15.2（命令行工具，无需 Qt 账号）

powershell

pip install aqtinstall

# 安装 Qt 基础库
aqt install-qt windows desktop 5.15.2 win64_msvc2019_64 -O C:\Qt

# 安装 Qt 基础库 + 源码
aqt install-qt windows desktop 5.15.2 win64_msvc2019_64 -O C:\Qt --archives qtbase qtsvg qtdeclarative

6. 安装 vcpkg

powershell

git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat
# （可选）将 vcpkg 集成到全局 CMake，但本指南采用 toolchain 方式，无需执行 integrate install

记录 vcpkg 的完整路径（例如 C:\Users\你的用户名\vcpkg）。

---

第二步：克隆项目源码

powershell

git clone https://github.com/SpriteOvO/AirPodsDesktop.git
cd AirPodsDesktop

---

第三步：配置 CMake 项目

在项目根目录下创建 Build 文件夹并进入：

powershell

mkdir Build
cd Build

执行 CMake 配置命令（请替换其中的路径）：

powershell

cmake .. -DCMAKE_TOOLCHAIN_FILE="C:/Users/你的用户名/vcpkg/scripts/buildsystems/vcpkg.cmake" -DCMAKE_PREFIX_PATH="C:/Qt/5.15.2/msvc2019_64" -G "Visual Studio 17 2022" -A x64

• CMAKE_TOOLCHAIN_FILE：指向 vcpkg 的 toolchain 文件，用于自动下载依赖。

• CMAKE_PREFIX_PATH：指向 Qt 5.15.2 的安装目录。

• -G "Visual Studio 17 2022" -A x64：生成 64 位 Visual Studio 解决方案。

首次运行该命令时，vcpkg 会自动下载并安装所有依赖库（Boost、cpr、cxxopts、magic_enum、nlohmann_json、zlib 等）。请确保网络通畅，下载过程可能较慢。

如果 CMake 配置成功，你会看到类似以下的输出：

-- Configuring done
-- Generating done
-- Build files have been written to: D:/AirPodsDesktop/Build

---

第四步：修复源码中的静态断言错误（关键步骤）

项目源码 Source/Logger.h 第 63 行附近存在一个 C++ 模板中的 static_assert(false)，这会导致编译失败。在编译前必须修改该文件。

1. 用文本编辑器打开 AirPodsDesktop/Source/Logger.h。

2. 找到如下代码段（约在第 50~70 行）：

        else {
            static_assert(false);   // 第 63 行
        }

将 static_assert(false); 替换为：

  static_assert(sizeof(level) == 0, "Invalid level");

修改后保存文件。

该修改是安全的，因为 level 枚举值永远不会进入 else 分支，但标准 C++ 要求依赖模板参数的静态断言。

---

第五步：编译项目

在 Build 目录下执行：

powershell

cmake --build . --config Release

编译过程会：

• 构建 SingleApplication 静态库

• 构建 spdlog.dll 动态库

• 编译所有源文件并链接生成 AirPodsDesktop.exe

• 自动调用 windeployqt 部署 Qt 运行时 DLL 和插件

成功时，可执行文件位于 Build/Binary/AirPodsDesktop.exe。

---

第六步：运行程序

直接双击 Binary/AirPodsDesktop.exe 即可启动。若提示缺少 DLL，请确保系统 PATH 中包含 Qt 的 bin 目录（或已通过 windeployqt 复制了所需文件）。

---

常见问题与解决方案

1. vcpkg 下载依赖时网络超时或 SSL 错误（如 curl operation failed with error code 35）

• 原因：GitHub、SourceForge 等源在国内访问不稳定，或代理配置不正确。

• 解决：

  • 配置 HTTP/HTTPS 代理（见第三步）。

  • 确保代理地址以 http:// 开头，不要加 https:// 前缀（vcpkg 要求）。

  • 若代理使用 127.0.0.1:7890，应设置：

    powershell

    $env:HTTP_PROXY = "http://127.0.0.1:7890"
    $env:HTTPS_PROXY = "http://127.0.0.1:7890"

  • 或手动下载失败的包（如 libcpr-cpr-1.7.2.tar.gz）放入 C:\Users\用户名\vcpkg\downloads，然后重新运行 CMake。

2. 编译时出现 error C2607: 静态断言失败

• 原因：未修改 Logger.h 中的 static_assert(false)。

• 解决：按照第四步修改源码。

3. CMake 找不到 Qt

• 解决：确保 -DCMAKE_PREFIX_PATH 指向正确的 Qt 安装路径（例如 C:/Qt/5.15.2/msvc2019_64）。路径中使用正斜杠 /，不要使用反斜杠。

4. 链接时提示 boost::stacktrace::stacktrace 未定义

• 原因：vcpkg 安装的 Boost 是 header-only 版本，但 stacktrace 需要编译库。

• 解决：vcpkg 会自动处理，若仍有问题可手动安装：

  powershell

  .\vcpkg install boost-stacktrace:x64-windows

5. 运行 windeployqt 时警告 VCINSTALLDIR is not set

• 影响：不影响运行，只是无法自动复制 VC 运行时库（通常系统已有）。可忽略。

6. 编译成功但程序闪退

• 检查是否缺少蓝牙或音频设备驱动。

• 尝试以管理员身份运行（某些功能可能需要）。

• 查看日志文件（默认位置：%APPDATA%\AirPodsDesktop\log）。

7. PowerShell 5.1 执行脚本时报错或代理设置无效

• 解决：升级到 PowerShell 7（见第一步）。若无法升级，可尝试在 PowerShell 5.1 中手动设置代理后，使用 pwsh -Command "cmake ..." 调用。

---

完整命令行示例（一键编译，使用 PowerShell 7）

假设你已按上述步骤配置好环境，在 PowerShell 7 中执行：

powershell

# 克隆项目
git clone https://github.com/SpriteOvO/AirPodsDesktop.git
cd AirPodsDesktop

# 创建构建目录
mkdir Build -Force
cd Build

# 设置代理（如果需要）
$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"

# 配置 CMake（请替换实际路径）
cmake .. -DCMAKE_TOOLCHAIN_FILE="C:/Users/shane/vcpkg/scripts/buildsystems/vcpkg.cmake" -DCMAKE_PREFIX_PATH="C:/Qt/5.15.2/msvc2019_64" -G "Visual Studio 17 2022" -A x64

# 修复 Logger.h（用 PowerShell 命令自动替换）
(Get-Content ..\Source\Logger.h) -replace 'static_assert\(false\);', 'static_assert(sizeof(level) == 0, "Invalid level");' | Set-Content ..\Source\Logger.h

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

# 运行程序
.\Binary\AirPodsDesktop.exe

---

结语

按照本指南，你应该能成功在 Windows 上编译并运行 AirPodsDesktop。若遇到其他问题，请查阅项目 GitHub Issues 或提供详细错误信息。祝使用愉快！