go-musicfox：在终端里听音乐的 TUI 音乐播放器 #

go-musicfox 是什么？ #

go-musicfox 是一款用 Go 语言编写的终端（TUI）音乐播放器，基于网易云音乐曲库，可在 macOS、Linux、Windows 上运行。

它把完整的音乐体验搬进了 80 列的终端窗口：搜索歌曲、发现歌单、管理播放队列、切换播放模式，全部通过键盘完成。软件内置 Beep、MPV、MPD、DLNA、AVFoundation、MediaPlayer 六套播放引擎，提供 8 级音质与 UNM 多源智能回退，支持 LRC / YRC 逐字同步歌词、DLNA 投送到电视与音响、Linux MPRIS 与 macOS/Windows 系统媒体控件集成。对于长期在终端里工作、又不想被弹窗和广告打扰的开发者与极简主义者来说，go-musicfox 是一个零干扰、极轻量的听歌方案。

go-musicfox 有哪些亮点特色？ #

• 六大播放引擎，按需切换：Beep（纯 Go 实现、零外部依赖，内置 MP3 / FLAC / OGG / WAV 解码）、MPV（IPC 控制、格式兼容性最强）、DLNA（投送到智能电视与 Hi-Fi 音响）、MPD（适配 NAS 与树莓派等无头服务器）、AVFoundation（macOS 原生框架，支持音频路由自动切换）、MediaPlayer（Windows WinRT，深度对接系统媒体控件），从纯 Go 零依赖到系统原生框架总有一套适合你的场景。
• 逐字同步歌词，四种渲染模式：解析 LRC / YRC 逐字时间轴，提供 simple / smooth / wave / glow 四种视觉渲染模式；macOS 下配合 LyricsX 还能实现浮动桌面歌词，让终端听歌同样沉浸。
• 系统级深度集成：覆盖 Linux MPRIS、macOS Now Playing 与菜单栏、Windows 媒体控件；蓝牙断连自动暂停、系统休眠自动响应，与操作系统无缝协作。
• 8 级音质解锁与多源回退：从标准品质到鲸云臻享共八档逐级提升，UNM 多源智能回退（酷我 / 酷狗 / 咪咕 / QQ 音乐），灰色歌曲也能找到可用音源播放。
• 全键位可定制，纯键盘流操作：40+ 内置操作全部支持自由重映射，支持全局快捷键与 TOML 配置，Vim 式 hjkl 导航；同时支持鼠标单击 / 双击 / 滚轮 / 右键。
• 终端内渲染真图形封面：基于 Kitty 图形协议在终端中绘制专辑封面，支持圆角裁剪与旋转动画，配合双列布局与鼠标操作，被官方称为「TUI 颜值巅峰」，Kitty、iTerm2 等终端原生支持。
• 轻量单二进制，随处可跑：无 Electron、无浏览器内核，一个数 MB 的单二进制文件即可运行，内存占用极低，树莓派、NAS、VPS、老旧笔记本都能流畅使用，日常使用 CPU 占用几乎可以忽略。
• 开源 MIT 与 Last.fm 同步：代码完全开放、MIT 许可证，可审查、修改、二次分发，不依赖任何云服务；同时支持自动 scrobble 听歌历史到 Last.fm，并可配置记录阈值防止短时切歌污染数据。

免费下载 go-musicfox #

以下为官方提供的各平台安装包（v5.1.0），点击链接即可下载。若需获取最新版本，也可访问官网安装文档或 GitHub Releases 页面。

说明：官网主推的安装方式为包管理器（如 Homebrew、AUR、Scoop 等），上表为各平台离线压缩包 / 安装包，适合无法使用包管理器的环境。

go-musicfox 如何使用？ #

go-musicfox 是纯键盘驱动的 TUI 应用，上手路径非常直接：

1. 在终端中启动程序：安装完成后，在终端输入 musicfox 并回车，即可进入主界面。首次启动时按提示登录网易云音乐账号（官网正文示例中展示了 $ musicfox 的启动命令）。
2. 熟悉主界面布局：界面顶部会显示当前播放歌曲信息（如 ♩ 许嵩 - 忽略不计），主体区域为歌单 / 歌曲列表，底部为操作提示。使用 Vim 式 hjkl 或方向键上下左右移动光标。
3. 搜索与发现音乐：通过内置搜索功能查找歌曲、歌手、专辑或歌单，选中后按回车即可加入播放队列开始播放。
4. 切换播放模式：列表循环、顺序播放、单曲循环、随机播放、无限随机、心动模式共六种播放逻辑，用一个快捷键即可循环切换，适配不同听歌心境。
5. 调整个性化设置：在配置界面中选择播放引擎（Beep / MPV / MPD / DLNA / AVFoundation / MediaPlayer）、音质档位、歌词渲染模式，并通过 TOML 配置文件重映射 40+ 快捷键，打造属于自己的操作肌肉记忆。

提示：若选择 MPV 或 MPD 引擎，需要先在系统中安装对应的 mpv / MPD 服务；默认的 Beep 引擎为纯 Go 实现，开箱即用，无需任何额外组件。

go-musicfox 的常见问题？ #

go-musicfox 是免费的吗？ 是。go-musicfox 采用 MIT 许可证开源发布，代码完全开放，可以免费使用、审查、修改和二次分发，不依赖任何云服务，听歌数据与隐私由用户自己掌握。

支持哪些操作系统？ 官方明确支持 macOS、Linux、Windows 全平台，并覆盖 Intel / AMD 与 arm64 架构；社区生态还提供 Termux 等移动终端环境的支持。

不安装额外播放器能用吗？ 可以。默认的 Beep 引擎是纯 Go 实现、零外部依赖，内置支持 MP3、FLAC、OGG、WAV 格式解码，开箱即用。如果追求更强的格式兼容性或音频处理能力，可以切换到 MPV 引擎（需自行安装 mpv）。

灰色歌曲或版权受限的歌曲能播放吗？ go-musicfox 提供 8 级音质解锁与 UNM 多源智能回退（酷我 / 酷狗 / 咪咕 / QQ 音乐），在官方音源不可用时可以尝试从其他音源找到可播放的版本。

终端里为什么不显示专辑封面？ 终端内渲染专辑封面依赖 Kitty 图形协议，需要 Kitty、iTerm2 等原生支持的终端才能正常显示；若使用不支持该协议的终端，封面将无法绘制。

会收集我的个人信息吗？ 根据官网隐私政策，项目不收集姓名、邮箱、登录凭据等个人身份信息，官网本身没有注册、评论或表单功能；官网仅在访问统计中使用 Google Analytics 收集匿名访问数据，数据保留 26 个月，且不由项目自建服务器存储。

go-musicfox 如何安装？ #

官网推荐使用包管理器安装，官方列出的支持渠道包括 Homebrew、AUR、Copr、Nix、Scoop、Flatpak、星火商店、Termux、Debian / Ubuntu 等（15+ 包管理器）。

macOS #

1. 打开终端，执行官方推荐的一行命令：

   brew install anhoder/go-musicfox/go-musicfox
   

2. 或者前往 GitHub Releases 页面下载对应架构的二进制文件： https://github.com/go-musicfox/go-musicfox/releases/latest
3. 安装完成后，在终端输入 musicfox 即可启动。

Linux #

1. 根据发行版选择对应渠道：
   • Arch Linux：通过 AUR 安装；
   • Fedora：通过 Copr 安装；
   • Nix / NixOS：通过 Nix 安装；
   • Debian / Ubuntu：使用对应软件包；
   • 通用方式：Flatpak 或星火商店。
2. 也可以直接下载 Linux amd64 安装包，按发行版规范安装。
3. Termux 用户可通过 Termux 渠道安装，在移动端终端中听歌。

Windows #

1. 使用 Scoop 安装（推荐），或下载本页提供的 Windows amd64 / arm64 压缩包。
2. 解压压缩包到任意目录，将所在目录加入系统 PATH 环境变量。
3. 打开 PowerShell 或 Windows Terminal，输入 musicfox 启动。

源码编译 #

官网提供「源码编译」方式，适合希望自行构建的用户：克隆 go-musicfox 仓库后使用 Go 工具链编译；完整安装文档可参考官网的安装说明页面。

go-musicfox 如何卸载？ #

go-musicfox 的卸载方式取决于你当初使用的安装渠道。

macOS #

1. 若通过 Homebrew 安装，执行：

   brew uninstall go-musicfox
   

2. 若为手动下载的二进制文件，直接删除对应的可执行文件即可。

Linux #

1. 通过包管理器安装的，使用对应命令卸载，例如 Arch 用户执行 pacman -R go-musicfox（AUR 助手同理）、Flatpak 用户执行 flatpak uninstall go-musicfox。
2. 手动安装的，删除对应二进制文件即可。

Windows #

1. 通过 Scoop 安装的，执行 scoop uninstall go-musicfox。
2. 手动解压安装的，删除解压目录，并从系统 PATH 环境变量中移除对应路径。

清理残留配置 #

go-musicfox 会在用户目录下保存配置与缓存文件（用于保存账号登录状态、快捷键配置与播放设置）。官网未在公开页面中说明确切的配置目录路径，如需彻底清理，请在卸载后手动检查用户主目录下的 go-musicfox 相关配置目录一并删除，具体路径请以你所用版本的实际情况为准。