企业官网建设流程全解析

Folia 音乐播放器上手教程：新手如何 5 分钟播通第一首本地歌曲

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major

Folia 是一款以全屏歌词动画为核心卖点的音乐播放器，可以播放本地曲库、自建的 Navidrome 音乐服务，以及网易云、QQ 音乐、酷狗等平台的在线歌曲。跟着这篇 Folia 教程走完，你会装好播放器、导入并播通第一首本地歌，再掌握全屏歌词、收藏与快捷键，把它变成日常在用的听歌工具。

选安装方式：桌面版与 Web 版两条启动路线

Folia 提供两种形态，按省事程度排个序。

路线一：下载桌面版（推荐）。打开项目 Releases 页面，选择对应系统的安装包（Windows、macOS、Linux 三套都有），下载后安装，双击启动。前后端运行环境都打包在里面，装完即用。

✅ 验收点：窗口打开后，顶部能看到 Playlists / Radio / Albums / Folder / Navi 页签条，右上角有搜索框。

💡 桌面版在本地文件夹导入等功能上更稳，没有特殊需求就从它开始。

路线二：本地跑 Web 版。需要先装 Node.js 24 及以上版本，然后克隆仓库：

git clone https://gitcode.com/GitHub_Trending/fo/folia-major

进入目录执行npm install装依赖，再执行npm run dev启动开发服务器，用浏览器打开终端打印的地址。

✅ 验收点：浏览器里出现与桌面版相同的界面，页签条可正常切换。

首次跑通：五步播放第一首本地歌曲

先走本地曲库这条路：不依赖网络、不用账号，装完就能出声，出了问题也最好定位。

1. 点顶部的Folder页签 → 进入本地音乐区域，海报墙上出现All Songs卡片，上方有Import Folder按钮；
2. 点Import Folder→ 系统弹出目录选择器 → 选中存歌的文件夹并确认；
3. 等递归扫描跑完 → 它会读取子目录里的音频（MP3、FLAC、M4A 等）、同目录的.lrc歌词和内嵌封面，目录越大耗时越久；
4. 点进All Songs卡片 → 歌曲列表出现；
5. 单击任意一首歌 → 开始播放。

💡 扫描时会顺带捡起同目录、同名的.lrc、.vtt等歌词文件，歌词放在音频旁边，播放时就有字可动。

另外两条来源，各一句话带过：

• Navidrome：切到Navi页签，在设置里填好自建 Navidrome 服务器的地址，专辑和歌曲列表立刻可看可播；
• 在线平台：右上角搜索框直接输歌名或歌手（占位文字是「搜索在线歌曲...」），结果里单击即播；未登录时部分歌曲只能试听 30 秒。

导入规则、支持的格式和排除写法，完整版在 本地音乐库管理。

✅ 验收点：歌声从扬声器出来，播放进度条在走。

把 Folia 当日常音乐播放器用

全屏歌词动画

播放中按H→ 控制条收起，歌词动画接管整个窗口，这是 Folia 最出圈的画面。主题不止一种：浮名、流光、群唱、心象、云阶、倾诉、镜台、时计等风格随意切换，每个动画都有各自不同的排版氛围。

💡 每种歌词动画的参数都可以单独微调，挑到喜欢的排版后保持不动，日常听歌就是这种观感。

本地歌词与自动匹配

本地歌没有歌词文件也没关系：Folia 会按网易云、QQ 音乐、酷狗的顺序自动匹配在线歌词和封面，匹配不准时可以手动从候选里选，也可以恢复首次导入时的本地信息。

收藏想留住的歌

打开歌曲菜单，选「收藏」，提示「已添加到喜欢的音乐」即存好；之后在Playlists里就能找回这些歌。

✅ 验收点：按一次H，控制条消失，歌词动画铺满整个屏幕。

高频快捷键一览

完整清单在 快捷键定义 中，先记这六个（macOS 上Ctrl换成Cmd）：

💡 命令面板最值得单独记：按S后直接打「搜索本地歌曲」这样的汉字或拼音，对应动作立刻执行，比在菜单里逐层翻快得多。

✅ 验收点：按一次Space能暂停再恢复，按H控制条收起。

排坑区：常见症状与解法

1. 在线歌曲播到 30 秒就停→ 原因：未登录时在线平台只给试听权限。解法：点右下角悬浮按钮展开平台入口，扫码登录，整首歌、在线歌单与收藏一并解锁。
2. 重启后本地曲库变灰、歌播不了→ 原因：浏览器或系统可能在重启后收回目录读取权限。解法：界面提示「需要恢复本地音乐访问权限」时照提示重新授权；目录移动或改名过就重新导入该文件夹。
3. Web 版提示不支持文件夹导入→ 原因：Web 版导入依赖浏览器的 File System Access API，浏览器没有这项能力就会拦下。解法：换支持的浏览器，或直接用桌面版。
4. 目录里混了不想要入库的临时音频→ 在根目录放一个.foliaignore文件，规则写法与.gitignore相同，重新导入后生效。

✅ 验收点：症状消失——在线歌能完整播放，本地库卡片恢复彩色。

下一步：进阶内容去哪读

「启动 → 导入 → 播放 → 收藏 → 快捷键切歌」全部走通后，部署方式、环境变量配置、Stage API 这些进阶内容收在 技术文档 里；本地曲库的匹配、实体整理与歌单细节，完整说明见 本地音乐库管理。

【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major