// Getting Started

快速开始

从源码把 Mio Music 跑起来：准备环境、克隆仓库、运行，以及生成 macOS 开发包。

平台状态 目前只有 macOS 上有开发包与实机运行记录。Windows 与 Linux 的检查工作流已经配置，但还没有它们的运行证据；此前这两个目标只做过类型检查，切换到 gpui-fast 后也需要重新验证。遇到问题请提交 Issue。

环境要求

Rust stable：工作区使用 edition 2024，需要 Rust 1.85 或更新版本。
Git：内置的列表插件放在子模块里，克隆时需要带上子模块。
系统依赖：原生构建依赖遵循 GPUI Kit 官方文档。下面是项目 CI 实际使用的安装方式。

macOS

brew install dav1d pkgconf

发布流程在 Apple 芯片与 Intel Mac 上分别原生构建，提供 aarch64 与 x86_64 的 .dmg 和独立更新包，请按芯片选择。Android 发布包分为 arm64-v8a、armeabi-v7a 与 x86_64；Intel macOS 和 Android x86_64 的运行验收仍待完成。

Linux（Ubuntu 24.04）

sudo apt-get update && sudo apt-get install -y \
  gcc g++ clang cmake pkg-config libfontconfig-dev libwayland-dev \
  libwebkit2gtk-4.1-dev libxkbcommon-x11-dev libx11-xcb-dev \
  libssl-dev libzstd-dev libasound2-dev libvulkan1 libdav1d-dev

Windows

CI 使用 Chocolatey 安装 pkgconfiglite，并用 vcpkg 安装 dav1d:x64-windows，再把 vcpkg 的 lib\pkgconfig 加入 PKG_CONFIG_PATH，把 bin 加入 PATH：

choco install pkgconfiglite -y --no-progress
vcpkg install dav1d:x64-windows

为什么需要 dav1d GPUI 内部用于 AVIF / MP4 解码的 dav1d-sys 通过 pkg-config 链接系统里的 dav1d。

获取源码

内置的列表插件在子模块 plugins/ 中（仓库 mio-music-plugins），应用用 include_str! 把它们嵌入二进制，所以克隆时一定要带上子模块：

git clone --recurse-submodules https://github.com/Mio888888/Mio-Music.git
cd Mio-Music

已经克隆过的仓库，补拉子模块：

git submodule update --init

运行

cargo run --locked -p mio-app

开发构建会把依赖也按优化级别编译，所以首次编译比较久，之后的增量编译很快。默认窗口大小为 1200 × 800。

macOS 开发包

需要在 Finder 里双击打开、或测试托盘与系统集成时，生成 .app：

sh tools/bundle-macos.sh

产物位于 target/debug/Mio Music GPUI.app。开发包使用本地 ad-hoc 签名，没有发布证书与公证，所以首次打开可能需要在「系统设置 → 隐私与安全性」中放行。资源与字体在 Debug 与 Release 中都嵌入二进制。

首次启动之后

应用本身不再内置任何在线音乐来源。搜索、歌单、专辑、发现与歌手数据都来自你安装并启用的 外部插件。应用内置了 Subsonic、Navidrome、Jellyfin、Emby、Plex、Songloft 插件，启动时自动安装，无需手动操作。进入 设置 → 插件，在「音乐列表插件」的插件卡片上点「配置」填入服务器地址与账号即可。详细步骤见使用指南。

也可以本地音乐为主：在本地音乐里添加目录即可扫描播放，不依赖任何插件。

检查与测试

提交代码之前，与 CI 保持一致：

cargo fmt --all -- --check
cargo test --workspace --locked
cargo check --workspace --locked

仓库里还有几个维护工具：

python3 tools/test-extract-source.py
node --check tools/spec-extract/capture.js

需要更新相邻源仓库（Mio-Music）的静态快照时，使用 python3 tools/extract-source.py --source ../Mio-Music。提取器只写目标工程，需要 Python 3 与 Node.js。

预览本官网

官网与文档位于仓库的 website/，是不需要构建的纯静态文件：

cd website
python3 -m http.server 4173

然后打开 http://localhost:4173。这个目录不属于 Cargo 工作区，不会进入任何安装包。