Folia 全屏歌词播放器快速教程：3 种来源、5 步让第一首歌铺满全屏
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 A multi-platform music player for local files, Navidrome, and online streaming services, featuring stunning animated lyrics.项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
Folia 是一款以全屏歌词动画为核心的音乐播放器，覆盖本地曲库、Navidrome 与网易云、QQ 音乐、酷狗等在线平台三种来源。这篇教程帮你定好歌曲来源、装起来并启动、把第一首歌播到全屏歌词页，顺手学会键盘上的日常操作。
Folia 歌曲来源怎么选：本地曲库、Navidrome 还是在线平台
装之前先问一句：你的歌是躺在自己电脑里、放在自建服务器上，还是全靠在线平台？这个选择决定了后面每一步走哪个入口。
| 歌曲来源 | 从哪个入口进 | 什么时候选它 | 提前要知道的事 |
|---|---|---|---|
| 本地音乐文件 | Folder页签 | 文件在自己电脑上，离线也能听 | 需要先导入一个音乐目录 |
| Navidrome 自建服务器 | Navi页签 | 已部署流媒体服务器，多设备共用 | 得先在设置里填好服务器地址 |
| 网易云 / QQ 音乐 / 酷狗 | 首页顶部搜索框 | 手头没有本地文件，随搜随听 | 未登录只能听 30 秒试听片段 |
拿不准就先走本地曲库：不碰账号、不依赖网络，导入即可听，是门槛最低的一条路。
本地目录导入后以文件夹卡片形式陈列，点卡片就按目录层级往下浏览。Navidrome 配置完成后，首页直接呈现曲库内容，浏览体验与本地库接近。在线平台则完全免配置：打开即能搜，在搜索页签里直接点播。
Folia 安装两条路线：桌面版安装包与 Web 开发环境
路线一：桌面版（多数人首选）。到 Releases 页面取回 Windows / macOS / Linux 对应平台的安装包，跟着向导装完即用。前后端运行环境都已打包在内，无需准备任何依赖；Linux 下.deb、.rpm、tar.gz三种格式任选其一。桌面版还支持波点音乐、YouTube Music、Spotify 与汽水音乐这四种 Web 版没有的来源。
路线二：本地开发跑 Web 版。先备好 Node.js 24 及以上版本，然后：
git clone https://gitcode.com/GitHub_Trending/fo/folia-major cd folia-major npm install npm run dev用浏览器打开终端提示的地址，完整界面就出来了。
怎么算启动成功：首页顶部出现一排Playlists / Radio / Albums / Folder / Navi页签，封面卡片加载出来；右上角搜索框负责在线平台检索，右下角悬浮按钮展开各平台的登录入口。
Folia 第一次播放：本地曲库 5 步入全屏歌词
以最常走的本地曲库为例：
- 点顶部
Folder页签，进入本地音乐区域； - 工具栏上点Import Folder，在系统目录选择窗口里选中你的音乐目录；
- 扫描期间先别动：Folia 会递归读取子目录里的音频、同目录
.lrc歌词与内嵌封面，曲库较大时后台读元数据要花点时间； - 扫描结束后，在海报墙里点
All Songs或任意文件夹卡片，单击任意一首歌，声音和封面立刻出现； - 进入全屏歌词页后按一次
H收起控制条，歌词动画铺满整屏。
满屏的歌词动画开始跳动，就代表第一次播放成功了。
歌来自在线平台的话路线更短：页签停在任一在线平台上，在右上角搜索框输入歌名或歌手（占位文字显示「搜索在线歌曲...」），在结果列表单击即播。想把某首歌留住，在歌曲菜单里选「收藏」，成功后会弹出「已添加到喜欢的音乐」的提示。
用键盘当 Folia 遥控器：高频快捷键速查
进入播放状态后，绝大多数动作不碰鼠标也能完成。按键定义可在 src/components/modal/userGuideContent.ts 中查看，下表覆盖日常 90% 的操作：
| 用来做什么 | 按哪个键 | 提示 |
|---|---|---|
| 收起或恢复控制条 | H | 把整屏留给歌词动画 |
| 播放或暂停 | Space | 使用频率最高的键 |
| 前后跳转 5 秒 | ←/→ | 不用拖着进度条走 |
| 切上一首 / 下一首 | Ctrl + ←/Ctrl + → | macOS 换成Cmd |
| 调出命令面板 | S | 见下方提示 |
| 打开播放队列 | Ctrl + P | macOS 为Cmd + P |
| 开合右侧面板 | P | 再按Tab轮换面板页签 |
💡S调出的命令面板值得单独记：直接敲汉字或拼音——「切歌」「收藏」都能命中动作，比在菜单里逐层翻找快得多。
Folia 新手排障：最容易碰到的三堵墙与对策
| 你会看到 | 为什么会这样 | 怎么办 |
|---|---|---|
| 在线歌曲播到 30 秒就中断 | 未登录状态下，平台只放出试听片段 | 点右下角悬浮按钮展开平台登录入口，扫码登录后完整播放恢复，自己的在线歌单与收藏也能用 |
| 重启应用后本地曲库变灰，点歌无反应 | 目录读取权限被浏览器或系统收回 | 看到「需要恢复本地音乐访问权限」提示时按引导重新授权；目录被移动或改名过，则重新导入该文件夹 |
| 网页版找不到可用的导入入口 | 浏览器不支持读取本地文件夹的 File System Access API | 换 Chrome 等支持该 API 的浏览器，或直接用桌面版，详见 docs/local-library-management.md |
💡 音乐目录里混着不想入库的临时音频时，在根目录放一个.foliaignore文件即可排除，规则写法与.gitignore相同，改完对该目录执行一次「重新导入」生效。
Folia 接下来可以试什么：从主题到多设备同步
- 换歌词动画主题：浮名、流光、群唱等各有排版氛围与可调参数，在播放页直接切换，效果预览见 README.md 的主题展示区；
- 智能匹配：本地歌曲可自动匹配在线歌词与封面，匹配不准时支持手动修正；
- 模组系统（桌面版，实验性）：在「设置 → 模组 → 模组系统」开启，可扩展新的歌词动画、背景与播放页图层；
- sync-server：自行托管后，多台设备间同步外观设置与 AI 主题库。
部署、环境变量与 Stage API 等更深的技术细节集中在 docs/technical.md。跑通「导入 → 播放 → 切歌 → 收藏」这条主线后，下一步值得做的，是挑一个顺眼的歌词主题，再打开自动在线匹配。
【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器 A multi-platform music player for local files, Navidrome, and online streaming services, featuring stunning animated lyrics.项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
