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

Folia 本地曲库增量重扫原理新文件、改动与删除如何自动同步完整指南【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-majorFolia 是一款专注于绚丽歌词动画的本地音乐播放器同时支持 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。想彻底恢复文件原始标签可手动选择使用本地信息。如何手动触发重新导入操作路径非常直观打开本地音乐首页即上图中带刷新按钮的文件夹视图进入某个文件夹在文件夹与歌单集合操作中点击重新导入也可以在全部歌曲集合中执行一次性重新扫描所有已导入的根目录。重复选择已导入过的目录时Folia 会直接更新原根目录不会产生重复曲库localMusicService.ts。更多细节可参考官方文档 local-library-management.md。小结变化类型Folia 的处理新增音频解析元数据后加入曲库音频修改重新读取该文件仅受影响文件歌词文件变化仅重新关联对应歌曲歌词文件夹封面变化该目录歌曲回退读取内嵌封面文件被删除从索引与歌单中移除磁盘文件不动未变化的歌曲直接复用现有数据一句话总结指纹判断变化 → 快照树对比 → 三类分流处理 → 未变部分复用 → 快照更新落库再配合保护手工整理数据的机制Folia 的本地曲库就能始终保持与磁盘内容一致而代价只是每次扫描一次轻量遍历。【免费下载链接】folia-major专注于绚丽的歌词动画效果的本地音乐/navidrome/第三方多平台在线音乐播放器项目地址: https://gitcode.com/GitHub_Trending/fo/folia-major创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考