使用插件
Lyrico 本身不提供在线搜索能力。歌词搜索、封面搜索和歌曲信息匹配由 插件 提供，你可以导入第三方插件来扩展这些功能。
什么是插件
插件是用 JavaScript 编写的搜索源，运行在 Lyrico 内置的 QuickJS 引擎中。插件可以声明以下能力：
- 搜索歌曲信息：根据标题和艺术家搜索在线数据库中的匹配歌曲。
- 获取歌词：获取歌曲的完整歌词（包括翻译和罗马音）。
- 搜索封面：搜索在线封面图片。
每种能力都是可选的，不同插件可能只支持其中一部分。
获取插件
官方维护的插件可在 Lyrico-Plugins 下载，覆盖 QQ 音乐、网易云音乐、酷狗音乐、Apple Music 等平台。
插件通常以 ZIP 压缩包 形式分发。一个 ZIP 中可能包含多个插件。
导入插件
完整操作流程：
- 进入
设置→搜索设置→插件管理。 - 点击右上角的添加按钮（或"导入插件"）。
- 在系统文件选择器中找到并选择插件的 ZIP 文件。
- Lyrico 会扫描 ZIP 包并显示"发现插件包"弹窗。弹窗中列出识别到的插件：
- 可安装插件：按版本关系显示（新安装 / 更新 / 覆盖 / 降级）。
- 无法安装：不符合要求的插件，会显示具体原因。
- 勾选要安装的插件，点击 "安装"。
版本关系说明
- 新安装：未安装过该插件。
- 更新：包内版本高于已安装版本，建议安装。
- 覆盖：包内版本与已安装相同。
- 降级：包内版本低于已安装，通常不建议安装。
启用与停用
插件安装后 默认是停用状态，不会参与搜索。在插件管理页打开插件右侧的 启用开关，它才会出现在搜索和批量匹配的流程中。
停用插件不会删除插件文件和配置。需要临时排除某个插件时，关闭开关即可。
调整插件顺序
在插件管理页 上下拖动 插件条目可以调整排序。插件顺序会影响：
- 单曲搜索：搜歌词时各插件源的调用优先级。
- 批量匹配：插件按顺序依次匹配歌曲。
排在前面的插件会优先参与搜索。
配置插件
有些插件需要填写 Token、API Key、地区、封面尺寸等配置才能正常工作。
操作流程：
- 在插件管理页，点击插件条目中的 "配置"。
- 进入配置页，根据提示填写各项配置。配置项类型可能包括文本、密码、数字、开关、下拉选择等。
- 点击 "保存"。
保存配置后，它会在下一次搜索时传递给插件。已经显示出来的搜索结果不会自动刷新，需要重新搜索。
WARNING
密码字段保存后会隐藏显示，但在插件执行时仍会传给插件。只应在可信插件中填写敏感凭据。
字段写入规则
插件搜索到的歌曲信息是候选元数据。Lyrico 根据 "字段写入规则" 决定如何处理每个字段，可对每个插件单独配置。
| 模式 | 行为 |
|---|---|
| 禁用 | 不写入该字段 |
| 补充 | 仅当本地字段为空时才写入 |
| 覆盖 | 使用插件结果替换本地字段 |
配置页中的"全部禁用"、"全部补充"、"全部覆盖"只修改写入模式。你还可以指定写入目标是标准标签还是自定义标签。
插件返回的平台内部信息（如歌曲 ID、歌词 ID、hash、Token 等）不会作为可见标签写入文件。
卸载插件
点击插件条目中的 "卸载" 并确认后，插件文件和配置会被完全删除，无法撤销。
如果只是暂时不希望某插件参与搜索，关闭启用开关即可，无需卸载。
搜索无结果或执行失败
按以下顺序排查：
- 插件是否已 启用。
- 插件是否 支持当前操作（例如部分插件只支持歌曲搜索，不支持歌词或封面）。
- 插件配置中的 必填项 是否已填写并保存。
- 网络是否可用。
- 批量匹配的 并发数 是否过高（尝试降低）。
- 插件或目标平台接口是否已变化（可查看
设置→其他→应用日志，筛选"插件"或"网络"类型）。
进阶：编写自己的插件
如果你想开发搜索源插件，完整的开发者文档请阅读 插件文档。建议按以下顺序阅读：