从源码构建

使用 GitHub Actions 编译

• 打开仓库的 Actions → Build Setup；点击 Run workflow，选择分支并运行。编译自己的修改时，先 Fork 并启用 Actions。
• 运行成功后，从 Artifacts 下载 AMExclusive-Setup-x64，解压得到 AMExclusive-Setup.exe。下载需登录 GitHub，产物保留 14 天。
• 仅手动触发，构建 Windows x64 Release 并检查内嵌安装文件，不自动发布 Release。构建机无需安装 Apple Music；安装和使用 AMExclusive 的电脑仍需安装。

本地构建环境

• Windows x64；Apple Music 或独立 WinUI 元数据目录。
• Visual Studio 2022+／Build Tools：MSVC x64 C++ 工具与 Windows 11 SDK。
• CMake 3.24+、PowerShell。

构建文件与目标

获取源码

git clone https://github.com/AntiOblivionis/AMExclusive.git
cd AMExclusive

构建 Release

在仓库根目录运行。脚本按需通过 Visual Studio DevShell 加载 MSVC；默认从本机 Apple Music 包读取元数据，以 x64 配置 CMake 并构建单文件安装器。

.\mod\scripts\Build-Mod.ps1 -Configuration Release

未安装 Apple Music 时构建

与 Action 使用同一个元数据下载脚本。WinUI 版本固定为 1.8.251222000，配套依赖也固定；仅用于生成 C++/WinRT 投影，不安装 UI 运行库，也不将其 DLL 打包进 Setup。

.\mod\scripts\Get-WinUIMetadata.ps1 -OutputDirectory .\mod\build\winui-metadata
.\mod\scripts\Build-Mod.ps1 -Configuration Release -WinUIMetadataDirectory .\mod\build\winui-metadata

目标与产物对应

• am_exclusive_hook → am-exclusive-hook.dll：HookDll、IPC、音质锁与 audio_v2。
• am_exclusive_ui → am-exclusive-ui.dll：UiAdapter 与 IPC。
• am_exclusive_broker → am-exclusive-broker.exe：Broker 与 IPC。
• am_exclusive_media_control → am_exclusive_media_control.exe：MediaSessionControl.cpp。
• am_exclusive_setup → AMExclusive-Setup.exe：SetupInstaller.cpp 与生成的 .rc 资源。

产物

• 分发文件：mod\build\dist\AMExclusive-Setup.exe。
• 构建目录：mod\build；二进制：mod\build\Release。
• 运行 Setup → 1 安装／升级，→ 2 卸载。

独立构建目录

相对目录位于 mod 下；本例分发到 mod\build-release\dist。脚本会重建所选构建目录中的 dist 文件夹。

.\mod\scripts\Build-Mod.ps1 -Configuration Release -BuildDirectory build-release

构建失败

• 找不到 MSVC：安装 x64 C++ 工作负载，或使用 x64 开发者 PowerShell。
• 找不到 CMake：加入 PATH，或安装 Visual Studio 的 CMake 工具。
• 找不到 Apple Music 包：安装 Apple Music，或按上面的独立元数据流程传入 WinUIMetadataDirectory。
• cppwinrt.exe 或元数据缺失：检查 Windows SDK 与 APPLE_MUSIC_PACKAGE_DIR；后者可指向 Apple Music 包或完整独立元数据目录。哈希校验失败时不要跳过校验，应重新下载。
• 首次 FetchContent 失败：检查 Git 与到 MinHook 仓库的网络连接。

直接使用 CMake

在 x64 开发者 PowerShell 中从仓库根目录执行。首次配置需要网络获取 MinHook；cppwinrt.exe 从 APPLE_MUSIC_PACKAGE_DIR 读取元数据并写入 build-dev/generated/winrt。该参数也可指向独立元数据目录。不要修改生成的头文件。

• 直接 CMake 构建产生 build-dev/Release 下的组件和安装器；不会执行 Build-Mod.ps1 的 dist 复制步骤。
• 单目标增量构建示例：cmake --build mod/build-dev --config Release --target am_exclusive_hook。需要完整分发时构建 am_exclusive_setup。
• 公开源码快照不附带私有验证套件；需要自行为修改增加测试，并完成真实设备播放验证。

$amPackage = Get-AppxPackage -Name AppleInc.AppleMusicWin
cmake -S mod -B mod/build-dev -A x64 "-DAPPLE_MUSIC_PACKAGE_DIR=$($amPackage.InstallLocation)"
cmake --build mod/build-dev --config Release --parallel