★ FEATURED ARTICLE Folia 歌词动画播放器装进手机PWA 安装与自部署 30 分钟完整指南【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major昨晚地铁上我用手机浏览器打开 Folia 地址几步操作后一个全屏歌词动画播放器就以独立图标躺在主屏上了。Folia 是一款支持网易云、QQ 音乐、酷狗、Navidrome 与本地曲库的多平台音乐播放器招牌是全屏歌词动画。读完这篇你能自己部署一个实例并把它装进手机。先搞懂原理Folia 凭什么能装进手机主屏Folia 的 Web 构建就是一个 PWA渐进式 Web 应用vite.config.ts 里的 manifest 声明了standalone独立窗口模式Service Worker 走autoUpdate策略index.html内置了 iOS 全屏元标签。这意味着你不用经过任何应用商店就能把这个长得像 App 的网页装到主屏安装后核心界面资源由 Service Worker 预缓存弱网下也能快速启动。部署前 3 项必查条件条件为什么必须自查方法地址是 HTTPSPWA 安装与离线运行依赖浏览器安全上下文HTTP 下安装入口不出现浏览器地址栏有锁形标识NAS 自部署需反代加可信证书见 deploy/docker/README.md 的 HTTPS 章节安卓用 Chrome、iOS 用 Safari其他浏览器不提供 PWA 安装入口打开地址确认浏览器内核与版本必填变量已填Docker 全栈缺SYNC_TOKEN至少八位随机串会直接拒绝启动AI 功能缺密钥则主题配色不可用对照 deploy/docker/README.md 的环境变量表逐项核对30 分钟把 Folia 上线3 条部署路径路径一一键托管平台零服务器打开仓库 README.md点 Vercel 或 Cloudflare 的一键部署按钮创建项目部署完成后在项目设置里补齐环境变量音乐平台 API 地址、AI 提供商与密钥变量清单与填写示例见 docs/technical.md 的部署与开发章节几分钟拿到带域名、自带 HTTPS 的访问地址全程不需要自己的服务器。路径二Docker 全栈适合 NAS 自托管新建空目录放入 compose.yaml 与重命名为.env的 .env.example编辑.env给SYNC_TOKEN填入至少八位的随机字符串AI 密钥可留空不影响播放执行docker compose up -d默认访问地址http://NAS-IP:18080路径三全量构建自由度最高克隆仓库git clone https://gitcode.com/GitHub_Trending/fo/folia-major确认本机 Node.js 为 24 或更高版本按 docs/technical.md 的部署与开发章节安装依赖、配置环境变量并启动适合想改代码、接自定义音源的用户。手机安装 Folia PWA 的四步操作Chrome 添加到主屏幕安卓用 Chrome 打开 Folia 地址点右上角菜单⋮选添加到主屏幕或安装应用确认名称为 Folia点添加Safari 添加到主屏幕iPhone / iPad用 Safari 打开 Folia 地址点底部分享按钮上滑找到添加到主屏幕确认名称点添加完成后主屏出现独立的 Folia 图标点开直接全屏启动没有地址栏状态栏与应用背景融为一体观感与原生 App 几乎一致。手机端能力边界什么支持什么不支持功能手机 PWA说明与替代在线搜索与播放网易云/QQ/酷狗✅ 支持登录态保存在手机浏览器里歌词动画主题✅ 支持布局随窗口尺寸响应式重排竖屏照样完整Navidrome 私有曲库✅ 支持支持服务器预置凭据自动登录本地音乐文件夹导入❌ 不支持依赖 File System Access API仅桌面 Chromium 系浏览器可用替代方案走 Navidrome音频输出设备选择⚠️ 降级需要 HTTPS 安全上下文详见 docs/local-library-management.md进阶Navidrome 凭据自动下发手机听自己的歌手机端导不了本地音频文件让 Navidrome 补上这块在 NAS 上用 Docker 部署 Navidrome挂载音乐目录在.env填入NAVIDROME_URL、NAVIDROME_USERNAME、NAVIDROME_PASSWORD三项NAVIDROME_URL必须是手机能直连的地址不能写 Docker 内部主机名重建 backend 容器使配置生效这套组合的好处音乐文件留在 NAS手机通过 PWA 远程访问不占空间也不费流量任何新打开的浏览器自动登录并启用 Navidrome手机、电视、电脑不用再各登录一遍。排错6 个常见现象的自查方法现象原因解决菜单里找不到添加到主屏幕地址不是 HTTPS或浏览器不支持 PWA改用 HTTPS 地址安卓换 Chrome、iOS 换 Safari重新加载页面安装提示有时只在首次访问出现更新后手机里还是旧界面Service Worker 走autoUpdate长时间未打开则未刷新手动清除站点数据后重新添加或等下次冷启动自动生效QQ 音乐登录后曲库不可用一键部署下VITE_QQ_API_BASE未填/api/qq或缺QQ_SESSION_SECRET按 docs/technical.md 补齐两项后重新部署AI 主题配色不可用部署时未配置 AI 密钥如GEMINI_API_KEY补齐环境变量重建对应容器或重新部署Navidrome 预置凭据不生效三项未填全或NAVIDROME_URL不是完整 http(s) 地址、浏览器连不通检查 backend 日志警告换成各设备可达的地址后重建 backend局域网 HTTP 下本地导入不可用非安全上下文File System Access API 被禁用这是预期行为手机听自己的歌走 Navidrome 方案装好后你的手机多了一个全屏歌词动画播放器与私有 Navidrome 曲库下一步建议把 Navidrome 和 Folia Docker 放进同一台 NAS一次配齐。【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
