Folia：把歌词做成一场视觉盛宴

<p align="center">  </p>

你有过这样的体验吗？深夜戴着耳机听歌，旋律在耳边流淌，却总觉得少了点什么——那种文字与音符交织在一起、让情绪扑面而来的冲击力。Folia 正是为解决这个痛点而生：它不是又一个音乐播放器，而是一个以全屏沉浸式歌词动画为核心的全新听歌体验。

<p align="center">  </p>

一、项目起源：一个人想做点"不一样的事"

Folia 的作者 chthollyphile 曾在 GitHub 上写道：传统的音乐播放器把歌词当作附属品，而 Folia 想要让歌词本身成为主角。这个项目诞生于 2022 年，最初只是一个用 TypeScript + React 写的小工具，用来给自己的网易云音乐播放列表配上炫酷的逐字动画。让人意外的是，作者把源码开源后，这个"自用工具"迅速在中文开源社区传播开来。

从最初的单一平台支持，到如今同时接入网易云音乐、酷狗音乐、QQ 音乐、Navidrome 私有音乐库四大音源；从简单的时间轴歌词，到 AI 驱动的逐字高亮、分段配色、主题生成——Folia 用了三年时间完成了一次又一次的迭代升级。截至目前，项目已获得近 5000 颗 GitHub Stars， Contributors 超过 35 人，形成了活跃的国际社区（Discord 成员超过数千人）。

<p align="center">   </p>

二、核心功能：歌词的"新看法"

逐字动画引擎

Folia 最引以为傲的功能是对歌词的精细化处理。它支持：

• 逐字高亮：当前唱的每个字单独高亮，类似 KTV 字幕效果，但更流畅、更具设计感
• AI 歌词分词：接入 Google Gemini 或 OpenAI 兼容 API，自动将长句切分成合理的演唱节拍单元
• 多轨音频可视化：频谱、波形、脉动球等多种视觉化效果随音乐实时变化
• 动态主题生成：上传任意一张图片，AI 自动提取配色生成专属歌词主题

多元音源支持

音源	登录方式	歌词支持	备注
网易云音乐	手机扫码	逐字歌词	依赖 NeteaseCloudMusicApiEnhanced
酷狗音乐	账号密码	基础歌词
QQ 音乐	微信/QQ 扫码	逐字歌词	支持 Serverless 模式（Vercel/Cloudflare Workers）
Navidrome	用户名密码	LRC 歌词	支持私有音乐库，隐私友好

全平台覆盖

• Web 版：Vercel 一键部署，适合公网访问，支持 PWA
• 桌面版：Electron 实现，Windows/macOS/Linux 均有安装包；Linux 还支持 AUR（Arch）、deb、rpm 多格式
• 特殊集成：提供 Quickshell 歌词插件，可在 omarchy 4 桌面环境的状态栏显示歌词

三、技术架构：TypeScript 全家桶

Folia 采用了前后端分离的现代化架构，但与常规 SPA 不同，它实际上是一个混合应用：

前端：TypeScript + React + Vite
       ├── Web UI（歌词播放器主体）
       ├── Electron 主进程（桌面版）
       └── 多个 Node.js 后端 API（歌词分词、QQ音乐代理、主题生成等）

后端（内置于仓库）：
  ├── api/lyric-proxy.js     —— 歌词代理
  ├── api/generate-theme.js  —— AI 主题生成（Gemini / OpenAI）
  ├── api/segment-lyrics.js  —— AI 歌词分词
  └── electron/              —— 桌面端特有逻辑（登录、Discord RPC、壁纸窗口等）

Docker 部署架构尤为值得称道。deploy/docker/ 下提供了完整的多容器编排方案：

• gateway：Nginx 网关，负责前端静态文件服务和 API 反向代理，监听 18080 端口
• backend：Node.js 服务，承载 AI 能力（歌词分词、主题生成）
• netease-api / kugou-api / qq-api：三个独立的音乐 API 服务，分离部署降低耦合
• sync-server：同步服务，支持多设备播放状态同步

所有容器均采用 read_only: true + no-new-privileges 安全加固，并大量使用 tmpfs 减少磁盘 IO。compose.yaml 支持从预构建镜像拉取（FOLIA_IMAGE_NAMESPACE），compose.build.yaml 则支持本地 Docker build。

四、上手体验：哪条路最适合你？

使用方式	难度	推荐场景	部署时间
桌面安装包	⭐	即装即用，不想折腾	< 5 分钟
Vercel Web 版	⭐⭐	想在浏览器/手机上听歌	10 分钟
Docker 自托管	⭐⭐⭐	有 NAS 或服务器，想完整部署	30-60 分钟
源码开发	⭐⭐⭐⭐	想参与开发或魔改	看个人能力

桌面版是最推荐的入门方式——下载对应平台的 Release 包，双击安装即可。作者提供了三条更新通道：Realeco（稳定版）、Limo（Nightly）和 Cielo（Canary），满足不同用户的需求。

自托管 Docker 则适合有技术基础的用户。克隆仓库后，复制 deploy/docker/.env.example 到 .env，填入必要的环境变量（GEMINI_API_KEY、NAVIDROME 账号等），再执行 docker compose -f deploy/docker/compose.yaml up 即可。整个栈约需 5 个容器，首次启动依赖网络拉取镜像，耗时约 20-30 分钟。

五、AI 在 Folia 中的角色

AI 不是 Folia 的噱头，而是歌词体验的核心驱动力。项目使用 Gemini 和 OpenAI 兼容 API 做两件事：

1. 歌词分词（segment-lyrics）：将无时间戳的纯歌词文本智能切分成逐字/逐词单元，配合音频分析精确对齐播放时间。这解决了"歌词文件只有整句时间戳"的行业痛点。
2. 主题配色生成：用户上传任意图片，AI 分析主色调后生成匹配的全屏歌词主题。这让"一首歌一种皮肤"变成零门槛的操作。

需要注意的是，AI 功能完全可选——关闭 AI provider 后，Folia 仍然是一个功能完整的播放器，只是失去逐字动画和 AI 配色两个高级特性。

六、争议与局限

Folia 也有它的问题，客观来看：

1. 版权灰色地带

网易云、QQ 音乐等音源的歌词数据受版权保护，Folia 通过逆向解析 API 的方式提供歌词。这意味着：在中国大陆地区，该项目存在版权合规风险，用户需自行判断使用场景。

2. 桌面版体积较大

Electron 方案带来了跨平台便利，但也意味着桌面版包含完整的 Chromium + Node.js 运行时，安装包约 200-300MB。对于只是想简单听歌的用户，这个体积偏重。

3. API 维护成本

网易云音乐的 API 经常被官方封锁，作者需要持续维护逆向解析逻辑。从技术上说，这是一种"猫鼠游戏"，不是可持续的长期方案。

4. 自托管有一定门槛

完整的 Docker 部署需要理解 Docker 网络、API 环境变量等概念，对纯小白用户并不友好。虽然文档较全，但缺失一条"最简路径"（比如只跑前端 + 一个网易云 API）。

七、行业意义与增长趋势

Folia 的出现填补了一个被长期忽视的需求：歌词体验的审美升级。在 Spotify、Apple Music、QQ 音乐等商业产品主导市场的背景下，Folia 证明了"歌词作为主角"这条路是走得通的。

从数据来看，项目从 2022 年的几百 Stars 增长到如今的近 5000 Stars，保持了稳定上升的曲线。值得关注的是其社区运营——作者维护了活跃的 Discord 频道、详细的文档站点（folia-site.cielaniska.top/guide/），以及多语言贡献者生态（35 位 Contributors，覆盖中文和英文文档）。

从更宏观的视角看，Folia 代表了AI + 垂直场景工具的结合方式：不是用 AI 替代传统功能，而是用 AI 解决传统方案做不到的体验问题（逐字歌词对齐、AI 配色）。这种"增量 AI"思路值得很多工具类项目借鉴。

---

<p align="center">  </p>

一句话总结：Folia 是一个把歌词做成艺术的音乐播放器，适合追求沉浸式听歌体验、对审美有要求、愿意折腾一下部署的用户。桌面版开箱即用，自托管版功能完整但有门槛。