Folia

外观

本页的内容太多了！

如果你想快速找到某个问题的答案，可以按 Ctrl + F 搜索关键词，或者将这个页面的地址发送给AI，让他们帮你找到对应的解答。

常见问题 ​

WARNING

注意，由于酷狗服务器的播放节点默认使用HTTP和错配的CDN证书，而PWA/安全上下文要求不能在 HTTPS 中混入 HTTP，因此相关的网络请求会自动升级到HTTPS 这在某些情况下，会导致酷狗播放失败。此时可以考虑手动访问 https://fs.youthandroid2.kugou.com/，然后信任此站点，有一定概率可以缓解该问题 若仍然出现错误，则可能是你附近的酷狗CDN的配置不再支持 HTTPS，此问题尚无较解决方法，如果持续出现此现象，请考虑使用网易云

这页主要整理主项目里最常见的问题

如何删除导入的本地文件夹 ​

alt text

为什么切换背景没有效果，窗口显示为灰色/白色/半透明磨砂状态 ​

alt text

请关闭 开启播放页原生毛玻璃背景 功能。该功能会在播放页启用原生毛玻璃背景，导致自定义背景无法显示。

另外此功能要求在Windows平台，要求系统版本为 Windows 11 22H2 以上版本，否则会降级为纯色背景。

很多操作都太繁琐了怎么办 ​

任何时候你觉得某个操作很繁琐，都可以按 Ctrl/Cmd + K 打开全局命令面板。焦点不在输入框时也可按 S；海报墙默认会优先把单字符用于筛选，详见命令面板用户指南：

alt text

指令窗口包含了应用的绝大多数功能，可以点击问号按钮查看所有可用指令。

最近使用过的 10 条指令会被记住，打开面板不输入任何内容时就会先看到它们；此外还有一份使用频次统计给常用命令加权。

按 : 可以进入执行模式，再按一个字母立刻执行命令（n 下一首、v 音量、q 队列、d 切换明暗……）。还可以在设置 > 选项 > 交互控制里录一个 Alt + 字母 的自定义快捷键，以及在界面设置里固定三条快捷命令。

随机播放/播放队列在哪里 ​

两者都位于右侧展开面板

alt text

此外，按 Ctrl/Cmd + P 可以直接打开队列，也可以在命令面板输入队列或queue，快速查看、搜索和批量整理当前播放队列：

alt text

随机播放按钮不同于其他播放器，其作用是将当前播放队列内的歌曲随机打乱一次，再次点击会再次打乱

怎么退出播放页面 ​

鼠标悬停在左上角，点击出现的返回图标，或者点击右侧按钮展开面板，在歌曲封面上点击返回主页

alt text

为什么逐字歌词动画对不上/慢半拍 ​

绝大多数情况下是因为歌词文件本身不是逐字歌词。这种情况下，会根据整句的持续时间来估算逐字歌词动画，因此准确度比较一般。

如果是整体偏早或偏晚，先分清是哪一种：

  • 所有歌都差不多的偏移量，通常是蓝牙耳机等输出设备的延迟，用 设置 > 选项 > 播放控制 > 全局时间偏移 一次性补偿，调整时有实时预览。
  • 只有某一首对不齐，用播放页右侧面板里的单曲歌词时间偏移。

怎么全屏/怎么隐藏进度条/怎么隐藏下面的翻译/怎么隐藏右边按钮 ​

按 F11 可以切换全屏模式，再按一次 F11 可以退出全屏。

按 H 可以切换隐藏进度条和右边按钮，再按一次 H 可以切换回来。

此外，视觉设置中可以选择自动隐藏UI，当无操作一段时间之后，进度条与按钮都会隐藏。

你还可以在高级自定义设置里找到更多选项，来调整界面显示：

alt text

为什么大量的歌曲都显示为已下架无法播放 ​

原因是没有登录网易云账户，或者登陆状态失效了（即使右下角显示已登录，有用户头像等信息，实际上登录状态可能已经过期了）。

alt text

点击退出登录，然后重新扫码登陆一次，一般就可以解决了。

为什么我能打开播放器，但搜不到歌 ​

最常见原因是 网易云 API 没有配置好，或者 API 地址本身不可访问。

首先检查是否是登录状态失效（即使右下角显示已登录，实际上登录状态可能已经过期了）。退出登录，然后重新扫码登陆一次。如果不是登录状态问题，再检查：

  1. 是否已经正确填写 VITE_NETEASE_API_BASE
  2. 这个地址能否直接在浏览器里打开
  3. 你部署的是 Web 版还是桌面版
  4. 你部署的网易云 API 是否额外配置了 ENABLE_GENERAL_UNBLOCK=false

如果你部署的是 Web 版，建议先按 部署 Web 版 先把前端和网易云 API 都部署好，再回头排查搜索问题。

为什么点了 AI 主题按钮之后，下一首歌也会用上一次的 AI 主题？或者我切歌的时候突然发现颜色变了，但我明明没有点 AI 主题按钮？ ​

先说结论：很多时候这不是bug，而是当前设计就是这样。

AI 主题的行为大致是：

  1. 如果你已经配置 AI 接口，点击 AI 主题按钮时，会把当前歌曲歌词发给模型，让模型返回一套主题配置
  2. 这套配置同时包含浅色和深色主题
  3. 以后切歌时，如果新歌曲以前生成过 AI 主题，就会切到那首歌对应的主题
  4. 如果新歌曲从来没生成过 AI 主题，就会继续沿用你上一次正在使用的 AI 主题

这意味着：它并不是“每切一首歌都自动重新请求一次 AI 并生成全新主题”。只有你主动为某首歌生成过主题，后续切回这首歌时才会自动切过去。

如果你没有配置 AI API，也不是完全不能用。当前实现仍然会在你点击按钮时做一次主题生成，只是这时走的是退化方案：从封面取色，再结合内置主题生成一套结果。想让颜色重新变化，需要你再点一次按钮。

在设置中可以更改这个行为，停止自动切换主题：

alt text

更多说明见 AI 主题。

为什么播放的时候会突然卡住，所有动画都不动，过一会就好了，尤其是拖动进度条的时候 ​

优先检查本地歌曲播放的时候是否存在相同问题，如果本地歌曲没有问题，优先怀疑网络问题导致的音频文件缓冲不顺畅。

由于歌曲动画等时间相关的操作，依赖于当前音频的播放时钟来驱动，如果网络问题导致音频文件缓冲不顺畅，卡住了，那么动画也会跟着卡住。 这个问题常见于本地开了科学上网工具的情况，网易云的音频文件是流式传输的，如果走了全局代理导致网络延迟，就会出现这种卡顿。

为什么手机浏览器里打开后界面显示不正常，或者部分功能无法使用 ​

  1. 请检查是否使用的是 Chrome for Android 或者 iOS 18 以上版本的 Safari，其他浏览器可能(非常可能！) 存在兼容性问题
  2. 文件系统访问功能在移动端浏览器里的支持有限，经测试目前只有 Chrome for Android 支持，iOS 上的 Safari 目前不支持这个功能，所以在 iOS 的移动浏览器里无法使用本地音乐相关的功能
  3. 音频设备访问，本机字体访问这些功能在移动端上也都无法保证能用

为什么本地音乐没有歌词 ​

按顺序检查：

  1. 音频旁边是否存在同名 .lrc 或 .vtt
  2. 音频文件里是否内嵌了歌词
  3. 你是否手动触发过在线匹配
  4. 当前歌词来源是否被切到了别的来源

如果你导入的是整批本地音乐，建议搭配 本地音乐 一起看。

为什么每次重新打开都要重新授权本地音乐目录 ​

  1. 先确认你是否已经更新到较新的版本
  2. 再确认导入后的音乐目录有没有被移动、重命名、换盘，或者权限被系统回收

如果更新后仍能稳定复现，再带着版本号和复现步骤去提 issue，会更容易定位。

为什么本地音乐明明还在，却提示要重新授权，或者就是播不了 ​

如果你遇到的是“列表里还有歌，但播不了”，通常优先怀疑：

  • 文件访问权限失效
  • 文件路径变了，比如移动了文件、重命名了文件
  • 索引还在，但实际文件句柄已经失效

最直接的处理方式是打开那个文件夹，点击重新导入：

alt text

优先检查：

  • Server URL 能否从当前设备直接访问（含协议和端口，结尾不要多一个 /）
  • 用户名和密码是否正确
  • 是否有反向代理、HTTPS、跨域或端口转发问题
  • 页面是 HTTPS 而服务端是 HTTP 时，浏览器会拦截混合内容
  • 服务本身是否正在运行

Web 部署版本的 Folia 需要连接公网地址的实例。如果你的实例在内网，建议使用桌面版 Folia 来连接。

我用的不是 Navidrome，能连吗 ​

可以试。Folia 这一块走的是标准的 Subsonic / OpenSubsonic API（声明版本 1.16.1），不是 Navidrome 私有接口，设置项叫 Navidrome 只是因为它是最常见的实现。

不过不同服务端覆盖的方法和扩展不一样，能用到哪些功能取决于你的服务端实现了什么。连接成功后，设置页的服务器信息会列出服务端类型、版本、OpenSubsonic 是否可用和支持的扩展——这是判断“为什么某个功能没有”的第一现场。详见 Navidrome / OpenSubsonic。

队列拼贴 / Lattice 是什么，怎么打开 ​

按 Ctrl/Cmd + B。它把整条播放队列铺成一面海报墙，是和播放页并列的第二个播放视图。再按一次退出。

想让点击播放后直接进它：设置 > 选项 > 界面设置 > 播放后进入的视图。私人 FM 下不可用。完整说明见 Lattice（队列拼贴）。

Now Playing 连接不上怎么办 ​

Folia 连接的是本机 Now Playing 服务的默认ws端口：

text
ws://localhost:9863/api/ws/lyric

先确认本机对应服务已经启动，再检查：

  • 9863 端口是否被占用或被拦截
  • 防火墙或安全软件是否阻止了本地 WebSocket
  • 你是否在本机环境里运行，而不是跨机器连接

Stage API 返回 401 ​

这通常说明 Bearer Token 没带上，或者你复制的是旧 Token。

按这个顺序查：

  1. 在桌面版设置里重新复制 Token
  2. 检查请求头是否为 Authorization: Bearer <token>
  3. 如果你改过设置或重装过应用，重新生成或重新复制一次

为什么 Web 版没有应用内视频录制 ​

这是平台能力差异，Web版本没有这个功能。

桌面版可以做更完整的窗口采集、遥控窗和本地集成，所以有些能力只会放在桌面端。Web 版一般需要改用浏览器录屏、系统录屏或 OBS。

实际上桌面版的内置录制功能也是通过捕获主窗口的画面并编码成视频实现的，建议直接使用OBS等专业的屏幕录制软件捕获主窗口/浏览器。

为什么有些歌曲会灰掉、卡住，或者不能播放 ​

这通常和歌曲本身已下架、资源不可用，或者上游接口拿不到可播放链接有关。

Folia 的处理逻辑大致是：

  1. 不可用歌曲会被标成不可用或直接灰掉
  2. 你单独点击一首不可用歌曲时，如果系统能找到可替代的版本，会先弹窗问你要不要播放替代版本
  3. 如果你确认，就会按替代版本建队列并播放
  4. 如果找不到替代版本，会提示不可播放，然后不继续
  5. 如果你点的是“播放全部”，构建播放队列时会直接跳过不可用歌曲

为什么界面在高缩放、小窗口或高 DPI 下显示不正常 ​

主页面推荐的最低可用视口大约是 800 x 600

如果低于这个范围，某些元素可能互相挤压，例如播放列表标题可能被进度条挡住。这是小视口下的已知限制，建议尽量保持窗口尺寸不低于这个范围。

但是实际上界面是支持响应式布局的，一些极端尺寸下的显示效果可能比较有趣：

alt text

alt text

建议先尝试：

  1. 浏览器缩放恢复到 100%
  2. 把系统缩放改到常见比例后复现
  3. 尽量保证窗口尺寸不低于 800 x 600

为什么风扇转得快，或者首页 GPU 占用偏高 ​

首页背景里的动态几何图形，再叠加模糊等视觉效果，会给 GPU 带来额外压力。

如果你觉得机器负担偏高，可以优先尝试：

  1. 到高级自定义设置里关闭 主页动态背景

alt text

这会在返回主页的情况下停止背景动画渲染，视觉效果影响不是特别大

  1. 在性能较弱的设备上优先使用更轻量级的动画效果

为什么网页和桌面版显示效果、功能不完全一样 ​

这是正常的。

Folia 的 Web 版和桌面版共享了很多核心逻辑，但仍有一部分功能依赖桌面运行时，所以一部分功能只会出现在桌面端，例如：

  • 遥控窗
  • 更完整的 Stage / Now Playing 集成
  • 应用内视频相关能力
  • 某些本地媒体和系统层交互

另外，不同平台的字体、渲染、窗口能力不同，视觉细节略有差异也属于正常现象。

为什么 macOS 上打开应用会提示“已损坏” ​

这是因为 macOS 会拦截未签名的应用。这并不是应用真的损坏了。

你可以参考 macOS App 已损坏指南 里的方法，通过手动允许或移除隔离属性来正常打开应用。

Released under AGPL-3.0

Copyright © Folia contributors