Folia部署到Cloudflare Workers实战Serverless歌词动画音乐播放器完整指南【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-majorFoliafolia-major是一款专注于绚丽歌词动画效果的本地音乐 / Navidrome / 第三方多平台在线音乐播放器支持网易云、QQ 音乐、酷狗音源与本地音乐库。把它部署到 Cloudflare Workers你可以在零服务器成本的情况下获得一个完整的 Serverless 音乐播放器静态前端与后端 API 同处一个 Worker按请求计费空闲不花钱。本文是一份面向新手的实战部署指南包含原理拆解、完整步骤、环境变量清单与常见问题排查。为什么选择 Cloudflare Workers 部署 Folia大多数音乐播放器 Web 版的部署难点在于「前端 后端」要分别托管而 Folia 的 Worker 入口把两者合二为一一套代码两种职责/api/*路由优先交给 Worker 处理AI 主题、歌词代理、歌词切词、QQ 音乐 API其余请求直接回落到静态资源SPA 友好未命中的路径自动回退到index.html前端路由刷新不 404免运维不需要常驻 Node 进程QQ 音乐 API 也不再需要单独部署 API 实例手机即用部署后可在 Chrome for Android / iOS Safari 中安装为 PWA部署完成后的效果预览部署前看懂架构4 个文件讲清 Serverless 原理整个 Cloudflare 部署的核心配置只有 4 个文件全部在仓库根目录文件作用wrangler.jsoncWorkers 部署配置入口、静态资源目录、路由优先级worker/index.ts请求总入口负责分发/api/*与静态资源worker/lyric-proxy.ts歌词 CORS 代理绕过浏览器跨域限制worker/qq.tsQQ 音乐 API 的 Serverless 接入层wrangler.jsonc的关键配置值得细看{ main: ./worker/index.ts, assets: { directory: ./dist, // Vite 构建产物 binding: ASSETS, not_found_handling: single-page-application, // SPA 回退 run_worker_first: [/api/*] // API 请求先走 Worker } }worker/index.ts的fetch处理器按顺序检查 5 类请求/api/generate-themeAI 主题生成、/api/generate-theme_openai、/api/lyric-proxy歌词代理、/api/segment-lyrics歌词逐字切词见 worker/segment-lyrics.ts、/api/qq/*QQ 音乐路由其余全部交给env.ASSETS.fetch()返回静态文件。其中 QQ 路由被特意包裹在 try/catch 中——失败降级为 502 而不是让整个 Worker 崩溃这是一个值得学习的容错设计。一键部署步骤从克隆到上线只要 4 步第一步获取代码git clone https://gitcode.com/GitHub_Trending/fo/folia-major cd folia-major⚠️ 项目要求 Node.js 24 或更高版本请先确认node -v。第二步安装依赖并配置环境变量npm install cp .env.example .env.local在.env.local中填写VITE_前缀的变量是构建时注入的必须先配置再构建变量名描述是否必需VITE_NETEASE_API_BASE网易云音乐 API 实例地址是VITE_AI_PROVIDERAI 提供商google或openai是需要 AI 功能时GEMINI_API_KEYGemini API Key用 Gemini 时OPENAI_API_KEY/OPENAI_API_URL/OPENAI_API_MODELOpenAI 兼容接口配置用 OpenAI 系时VITE_QQ_API_BASE填/api/qq启用内置 serverless QQ 路由否QQ_SESSION_SECRETQQ 登录态加密密钥不加VITE_前缀启用 QQ 时一个最小可用的 Gemini 配置示例VITE_NETEASE_API_BASEhttps://your-netease-api.example.com VITE_AI_PROVIDERgoogle GEMINI_API_KEYyour_google_gemini_api_key第三步构建前端产物npm run build该命令会先编译api-ts目录再由 Vite 把前端打包到dist/——这正是wrangler.jsonc中assets.directory指向的目录。第四步部署到 Workersnpx wrangler deploy首次运行会引导你登录 Cloudflare 账号并选择项目Zone / Account 均按提示选择即可。部署成功后终端会给出https://xxx.xxx.workers.dev的访问地址打开即可开始听歌。可选增强把 Serverless 能力拉满1️⃣ QQ 音乐内置路由 Durable Object 扫码登录Cloudflare 部署下 QQ 音乐不需要额外部署常驻 API 实例VITE_QQ_API_BASE填成/api/qq再配QQ_SESSION_SECRET即可默认支持微信扫码登录。进阶玩法是绑定一个 Durable ObjectQQ_QR_CHANNEL→QqQrChannel增加 QQ 扫码登录。为什么非要 DO因为 QQ 扫码通道依赖一条长连接的 MQTT WebSocket而普通 Worker 调用结束连接就销毁只有 Durable Object 能跨请求「握住」这条连接。相关原理与排错细节见 docs/qq-music-deployment.md。2️⃣ 跨设备同步Sync Server 部署在同一账号Folia 提供可选的官方同步服务端 sync-server/用于在多设备间同步外观设置与 AI 主题库推荐形态正是Cloudflare Workers D1 数据库在sync-server/目录执行wrangler d1 create folia-sync创建数据库将 sync-server/wrangler.toml 复制为wrangler.local.toml并填入真实的database_id执行wrangler deploy --config wrangler.local.toml部署后在 Folia 的「存储设置」中填写服务端地址与SYNC_TOKEN即可启用同步。常见问题排查清单症状可能原因与解法刷新页面 404构建后未部署最新产物确认dist/已生成并重新wrangler deploy环境变量不生效VITE_变量是构建时注入的改完.env.local必须重新npm run build再部署AI 主题生成失败检查VITE_AI_PROVIDER与对应 API Key 是否匹配QQ_SESSION_SECRET千万不要误加VITE_前缀QQ 登录路由返回 501未设置QQ_SESSION_SECRET曲库搜索仍可用仅登录不可用歌词加载异常确认部署地址为 HTTPSWorkers 默认即是歌词代理仅允许白名单域名属正常安全限制更完整的变量说明与环境差异参见 docs/technical.md。总结回顾一下这套部署方案的关键wrangler.jsonc让静态资源与 API 路由共用一个 Worker/api/*优先、SPA 兜底的策略让 Folia 的歌词动画、AI 主题、QQ 音乐等功能在 Serverless 形态下开箱即用配合 Durable Object 与 D1甚至登录态保持与多设备同步都能免费搞定。按照本文 4 步走完你得到的不只是一个能跑的播放器而是一个几乎零成本的私人歌词动画舞台——下一首歌的灯光秀就交给 Folia 吧 【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
