构建与本地运行

生成 Web 资源、构建宿主与运行隔离预览。

Windows · WinUI 预览版

生成 Web 资源、构建宿主与运行隔离预览。

页面说明

构建与本地运行 是 OFPlayer 本地优先音乐工作流的一部分。这个页面会先说明功能边界、适用场景和下一步入口，再交给网页播放器或工具页面完成具体操作。

OFPlayer 面向有个人音乐收藏的用户，重点放在本地文件播放、WebDAV 与 Subsonic/Navidrome 音乐库连接、歌词和音频工具、隐私优先的数据处理，以及足够克制的桌面式界面。

如果你只是想试用，可以从网页版开始导入本地音频；如果已经有 NAS、服务器或远程曲库，可以继续阅读教程，把 OpenList、WebDAV 或 Navidrome 接到同一套播放体验里。

页面内容会尽量说明真实可用的能力，不把尚未完成的方向包装成已经上线的功能。遇到部署、连接或格式问题时，可以顺着相关文档和工具逐步检查，而不是在播放器里反复猜配置。

对于搜索、分享或禁用脚本的访问场景，这份静态内容也会保留核心信息：页面主题、产品边界、相关入口和下一步操作都能被直接读取，不依赖前端应用完成后才出现。

每个入口都会尽量连接到相邻的说明页，避免只留下单点页面，内容也会随着产品发布持续更新。

从这里可以继续访问 OFPlayer 文档、下载与版本、GitHub。这些内部入口覆盖产品介绍、教程、文档、下载和实际工具，方便从了解能力一路走到部署、整理曲库和开始播放。

构建与本地运行

以下命令面向包含完整 src-winui 实现的桌面开发检出，不适用于只有官网代码的仓库。请先确认所在分支包含 Native Host、WinUI Core 和共享 Web 入口。

开发环境

当前项目文件指定 .NET 10、Windows SDK 10.0.26100、x64 与 Windows App SDK 1.8。这是本次源码的构建配置，不是已经验收的最终最低系统要求。

还需要 Node.js/npm、Rust 的 Windows 编译环境，以及 C++/Windows SDK 构建依赖。共享沉浸与胶囊需要 WebView2。依赖版本以检出中的项目文件与锁文件为准。

生成共享 Web 资源

在桌面仓库根目录执行：

npm ci
pwsh -NoProfile -File scripts/build-winui-web.ps1 -RepoRoot (Get-Location).Path

脚本会运行类型检查和 Vite 构建，从 manifest 收集 immersive.html 与 lyric-capsule.html 的依赖，写入 WinUI 的 Assets/web 并生成构建戳记。不要用旧 dist 目录手工覆盖这些资源。

构建宿主与原生界面

cargo build --manifest-path src-tauri/Cargo.toml --bin ofplayer-native-host
dotnet build src-winui/OFPlayer.WinUI/OFPlayer.WinUI.csproj -p:Platform=x64

Web 构建、Rust 宿主构建与 WinUI 构建是三个环节；其中一个通过不能替代另外两个。

使用独立数据目录运行

下面的示例将预览数据放在当前检出下的 .preview-data，避免混用已有正式曲库：

$env:OFPLAYER_WINUI_DATA_ROOT = Join-Path (Get-Location) '.preview-data'
$env:OFPLAYER_NATIVE_HOST_PATH = Join-Path (Get-Location) 'src-tauri/target/debug/ofplayer-native-host.exe'
& './src-winui/OFPlayer.WinUI/bin/x64/Debug/net10.0-windows10.0.26100.0/win-x64/OFPlayer.WinUI.exe'

未配置数据目录时，当前实现默认使用本地应用数据目录下的 ofplayer-winui-preview。以应用 设置 → 曲库与存储 → 数据位置与重置显示的实际位置为准。

同一个数据目录不可被两个宿主同时占用。不要让旧 Tauri 客户端与 WinUI 共写同一份数据库，也不要绕过正式目录保护来完成普通预览。

验证层次

dotnet run --project src-winui/OFPlayer.WinUI.Core.Tests/OFPlayer.WinUI.Core.Tests.csproj
cargo test --manifest-path src-tauri/Cargo.toml --test native_host_protocol

Core 测试验证模型和策略；协议测试启动真实宿主验证进程通信。最后仍需在原生窗口中检查导入、播放、分组返回、沉浸、胶囊和设备行为。浏览器中的 Vue 页面不能证明 XAML 焦点、窗口拖动、系统媒体控制正常。

发布前再检查

当前 publish 配置会在可用时复制 release 原生宿主和应用 PRI 资源。发布目录需要完整资源、宿主及运行依赖，不能只拷贝一个 exe。干净机器安装、签名、升级、数据保留和更新失败恢复是独立的发布验收。