企业官网建设流程全解析

Lyrico 是一款开源的 Android 音乐标签编辑器，它本身不提供在线搜索能力——搜索源插件正是它的"外挂大脑"：导入一个 ZIP 插件，填写 API Key 等配置并启用，就能在线搜索歌曲信息、批量补全歌词与封面，把缺失的元数据一次性写回本地音频文件。本指南面向新手，按"导入 → 配置 → 启用 → 批量匹配"四步走，5 分钟即可完成全部设置。

📌 核心关键词：Lyrico 插件、搜索源插件、批量匹配歌词、批量匹配封面、插件配置

一、搜索源插件是什么？为什么需要它

Lyrico 采用插件化架构：应用本体负责运行时、配置界面、结果处理和标签写入，而在线搜索能力完全由插件提供。一个插件通常声明以下三种能力，可以只支持其中一部分：

插件用 JavaScript 编写，运行在 Lyrico 内置的QuickJS 引擎中，源码位于 plugin/runtime/。对使用者来说无需了解代码细节——插件以ZIP 压缩包分发，导入即可使用。

二、5分钟导入插件：从ZIP到安装

前提：插件 ZIP 包通常从官方插件仓库获取（可覆盖 QQ 音乐、网易云音乐、酷狗音乐、Apple Music 等平台）。一个压缩包内可能同时包含多个插件，导入时会自动识别。

导入操作步骤：

1. 进入设置→搜索设置→插件管理
2. 点击右上角添加按钮（"导入插件"）
3. 在系统文件选择器中选择插件的ZIP 文件
4. 在"发现插件包"弹窗中查看识别结果并勾选要安装的插件
5. 点击安装

导入弹窗会按版本关系提示四种状态：

• 🆕新安装：未安装过该插件
• ⬆️更新：包内版本更高，建议安装
• ♻️覆盖：版本相同
• ⚠️降级：版本更低，通常不建议安装

如果插件包不符合格式（如缺少manifest.json、ID 不合法、超过大小限制），应用会拒绝导入并给出具体原因。整个流程由 SourcePluginInstaller.kt 完成解压、校验与原子安装，无需任何手动干预。

三、配置插件：API Key、地区与封面尺寸

部分插件需要填写配置项才能正常工作，常见的配置项包括：

• API 地址 / 服务器地址（text 类型）
• Token、API Key（password 类型，输入内容会被遮挡）
• 地区、封面尺寸、歌词来源（dropdown 下拉选项）
• 超时时间（number 数字类型）

配置操作步骤：

1. 在插件管理页点击插件条目中的"配置"
2. 进入配置页，按提示填写各项配置（配置界面由插件在manifest.json中声明自动生成）
3. 点击保存

💡 保存后，配置会在下一次搜索、歌词获取或封面搜索时传递给插件。已显示的搜索结果不会自动刷新，需要重新执行搜索。

⚠️ 密码字段保存后会隐藏显示，但执行时仍会传给插件，请只在可信插件中填写敏感凭据。若某个插件没有"配置"入口，说明它没有声明可配置项，直接启用即可。

四、启用插件与调整优先级顺序

插件安装后默认处于停用状态，不会参与搜索。在插件管理页打开对应开关才会生效。插件管理页按元数据源、歌词源、封面源三个 Tab 分类，插件声明的来源类型显示在名称下方。

几个实用细节：

• ✅分开控制：关闭某一类型只停用该类型，不会删除插件文件和配置，也不影响其他类型
• ✅拖动排序：上下拖动插件条目调整优先级，排在前面的插件优先参与搜索，顺序会同时影响单曲搜索与批量匹配
• ✅按需启用：只需歌词能力的插件，只打开"歌词源"开关即可

五、批量补全歌词与封面：插件的真正威力

单个歌曲可以手动搜索，但一次处理几十上百首歌曲时，批量匹配才是插件的高光时刻。Lyrico 提供三个独立的批量任务入口：标签匹配（元数据）、批量匹配歌词、批量匹配封面。

以批量匹配歌词为例：

1. 在歌曲列表中长按任意歌曲进入多选模式，勾选需要处理的歌曲（支持"全选"和滑动区间选择）
2. 点击右下角展开按钮（FAB），选择"批量匹配歌词"
3. 在"批量匹配配置"页面确认并发数，点击开始
4. 任务执行期间实时显示进度，完成后可在设置→其他→任务历史中查看每首歌的成功/失败/跳过详情

匹配前请确认四件事：

💡并发数说明：并发越高处理越快，但更容易触发限流或网络失败。出现频繁请求失败时，应降低并发数重试。

此外，在设置→搜索设置中开启"优先使用文件名匹配"，批量匹配会忽略已有的标题/艺术家标签、改用文件名作为搜索依据，非常适合标签混乱但文件名规范的音乐库。

六、字段写入规则：补充还是覆盖？

插件搜索到的歌曲信息只是候选元数据，最终是否写入音频标签、以什么方式写入，由 Lyrico 的字段写入规则决定（可针对每个插件单独配置）：

批量补全场景通常选择"补充"模式最安全：只填空、不动已有标签。而插件返回的平台内部信息（歌曲 ID、歌词 ID、hash、Token 等）只会原样传回同一个插件用于后续请求，不会作为可见标签写入文件。

七、常见问题快速排查

遇到疑难问题可查看设置→其他→应用日志，筛选"插件"或"网络"类型定位原因。

八、相关文档与源码路径

导入插件 → 填好配置 → 打开开关 → 批量匹配，四步走完，你的本地音乐库就会焕然一新 🎵