使用插件

本文面向插件使用者，说明 Lyrico 中插件的基本使用方式。这里不要求了解 JavaScript、manifest 或宿主 API。

插件负责提供在线搜索能力。启用插件后，Lyrico 可以通过插件搜索歌曲信息、歌词和封面；插件是否支持某项能力，取决于插件自身声明和实现。

插件包

Lyrico 插件通常以 ZIP 压缩包分发。一个插件包中至少包含：

text

plugin.zip
└── com.example.source/
    ├── manifest.json
    └── source.js

有些压缩包可能同时包含多个插件。导入时，应用会扫描包内的 manifest.json 并列出可安装的插件。

导入插件

在 Lyrico 中进入插件管理页面。
选择插件 ZIP 压缩包。
查看应用识别到的插件列表和导入结果。
确认安装需要导入的插件。

如果插件包不符合格式要求，应用会拒绝导入，并显示对应错误原因。

启用与停用

插件安装后不一定立即参与搜索。启用插件后，它才会出现在歌词、封面或批量匹配等相关流程中。

停用插件不会删除插件文件和配置，只是让它暂时不参与搜索。需要彻底移除时，可以卸载插件。

配置插件

插件可以声明自己的配置项，例如：

API 地址
Token 或 API Key
地区
封面尺寸
搜索偏好

这些配置项由插件在 manifest.json 中声明，Lyrico 会根据声明生成对应的配置界面。不同插件的配置项可能不同。

保存配置后，配置会在下一次搜索、歌词获取或封面搜索时传递给插件。

如果某个插件没有配置入口，通常表示它没有声明可配置项。

元数据应用

插件搜索结果会返回标准元数据字段，例如发行日期、专辑名、封面、作曲、作词等。单曲匹配和批量匹配由 Lyrico 负责决定哪些字段可以应用、以及是补充还是覆盖。

平台 ID、hash、歌词 ID 等私有信息只用于同一插件后续请求，不会显示为可写入的标签字段。

更新与卸载

导入相同插件 ID 的新版本时，Lyrico 会根据版本号判断是更新、覆盖还是降级。通常建议安装版本号更高的新版本。

卸载插件会移除插件文件，并清理对应插件配置。卸载前请确认不再需要该插件。

常见问题

插件启用后没有搜索结果

可能原因：

插件本身没有实现对应能力
插件需要配置 Token、API Key 或其他必填项
网络请求失败
对方服务返回格式变化，插件需要更新

插件配置保存后没有立即生效

配置会在插件执行搜索、获取歌词或搜索封面时传递给插件。已经完成的搜索结果不会自动重新刷新，需要重新执行搜索。

插件导入失败

常见原因包括：

压缩包内没有有效的 manifest.json
插件 ID 格式不合法
插件 API 版本不匹配
入口脚本不存在或路径不合法
压缩包或插件目录超过大小限制

使用插件 ​

插件包 ​

导入插件 ​

启用与停用 ​

配置插件 ​

元数据应用 ​

更新与卸载 ​

常见问题 ​

插件启用后没有搜索结果 ​

插件配置保存后没有立即生效 ​

插件导入失败 ​