企业官网建设流程全解析

Folia 本地曲库增量重扫原理：新文件、改动与删除如何自动同步（完整指南）

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

Folia 是一款专注于绚丽歌词动画的本地音乐播放器，同时支持 Navidrome 与多平台在线音乐。它的本地曲库功能通过增量重扫机制，让新增、修改和删除的音乐文件自动同步到曲库索引，而无需每次全量重读成千上万个文件——这正是大曲库用户刷新秒级完成的关键。

为什么需要增量重扫？

想象你的曲库有 5 万首歌。如果每次点击"刷新"都从头解析每个文件的元数据（标题、艺术家、封面、ReplayGain……），等待时间会非常漫长。

Folia 的做法是：只处理真正变化的文件。未变化的歌曲直接复用上次导入时保存的数据，只有"有变动的部分"才进入昂贵的元数据解析流程。

文件指纹：如何判断一首歌"没变"？

增量重扫的核心是文件指纹。每个音频文件在扫描时会被计算一个签名：

相对路径::文件大小::最后修改时间

对应源码见 localMusicService.ts。签名一致，说明文件内容几乎可以确定没有变化；不一致，则标记为"需要重新读取"。

💡 用大小 + 修改时间做指纹，比逐字节哈希快得多，足以覆盖绝大多数"复制新文件、替换歌词、重编码"等日常场景。

快照树：把整个目录存成一张"地图"

每次扫描，Folia 会递归遍历所选文件夹，构建一棵目录快照树：每个目录记录它包含的文件、每个文件的指纹，并计算一个目录哈希（见 localMusicService.ts）。

下次重扫时，新快照与旧快照逐文件对比。此外，扫描过程中还会读取各目录的.foliaignore规则（语法类似.gitignore），被忽略的文件和目录不会进入曲库，规则文件为 foliaIgnore.ts。

三类变化，分别怎么处理？

对比逻辑集中在 collectImportDiffPlan 函数中，它会把结果分成三组：

📁 新增文件：直接进入曲库

磁盘上存在、但指纹库或曲库里没有的音频文件，会被加入"待处理"列表，读取元数据后写入本地曲库。

✏️ 修改文件：只重读受影响的部分

• 音频文件本身变了（大小或修改时间变化）→ 重新解析该文件的元数据与内嵌封面。
• 同目录歌词文件变了（.lrc、.vtt、.yrc等）→ 触发对应歌曲重新关联歌词，而不必重读音频。
• 文件夹封面变了或被删除（cover.png/cover.jpg）→ 该文件夹下的歌曲会重新读取各自的内嵌封面。

这个"关联更新"设计避免了不必要的音频解析，是重扫速度快的重要原因。

🗑️ 删除文件：从曲库索引中移除

旧快照里存在、但磁盘上已找不到的音频，对应的歌曲会被移出曲库索引与本地歌单引用（见 localMusicService.ts）。

⚠️ 注意：删除操作只影响 Folia 的本地索引，绝不会删除或移动磁盘上的音乐文件。

未变化的歌曲：原地复用

对比完成后，指纹一致的歌曲不会重新解析，只会更新文件句柄、大小和修改时间，然后直接沿用数据库中的现有记录（localMusicService.ts）。这就是"万首曲库秒级刷新"的底气所在。

后台元数据读取：扫描快，解析不卡界面

元数据解析是重 CPU 的操作，Folia 将其放在后台多路并发进行：扫描阶段只记录文件信息，真正的标签解析（标题、时长、内嵌封面等）由若干并行 worker 分批处理并批量写库（localMusicService.ts）。界面不会因此卡顿，扫描进度也会实时反馈。

手工整理的东西不会被重扫覆盖

这是很多用户关心的问题。Folia 会保护两类数据：

• 已应用的在线匹配结果（在线元数据、在线封面）；
• 手工修改的艺术家/专辑实体关系（如手动合并、拆分得到的结果）。

普通重扫时，这些非"导入来源"的关联会被标记保留，不会被重新解析出的原始标签直接覆盖（localLibraryImportCatalog.ts）。想彻底恢复文件原始标签，可手动选择"使用本地信息"。

如何手动触发重新导入？

操作路径非常直观：

1. 打开本地音乐首页（即上图中带"刷新"按钮的文件夹视图）；
2. 进入某个文件夹，在"文件夹与歌单"集合操作中点击重新导入；
3. 也可以在"全部歌曲"集合中执行，一次性重新扫描所有已导入的根目录。

重复选择已导入过的目录时，Folia 会直接更新原根目录，不会产生重复曲库（localMusicService.ts）。更多细节可参考官方文档 local-library-management.md。

小结

一句话总结：指纹判断变化 → 快照树对比 → 三类分流处理 → 未变部分复用 → 快照更新落库，再配合保护手工整理数据的机制，Folia 的本地曲库就能始终保持与磁盘内容一致，而代价只是每次扫描一次轻量遍历。

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