插件到底是什么——CommonJS 模块定义的音源对接

一句话概括

MusicFree 的插件是一个 导出特定接口对象的 CommonJS 模块。宿主（MusicFree 播放器）加载模块，调用它的接口函数，拿回结构化的数据，然后渲染给用户。插件不需要关心 UI、缓存、分页——只管"给定输入、返回数据"。

插件需要实现什么

一个最小可用的插件需要在 module.exports 中导出以下接口（全部为异步函数）：

宿主会在需要时调用对应接口——比如用户搜索"周杰伦"，宿主调用插件的 search('周杰伦', 'music', 1)，拿到结果后渲染到搜索列表。

插件可以不实现哪些

并不是所有插件都需要实现全部接口。一个插件可以只支持搜索+播放，不支持歌单导入；也可以只支持元数据刮削（封面、歌词），作为其他插件的补充。宿主会检查插件声明支持哪些功能，只在搜索结果中展示有实现的接口。

插件和宿主的边界

• 插件做什么：对接音源的 HTTP API、处理登录态签名、解析返回数据、错误重试。
• 宿主做什么：UI 渲染、播放控制、数据持久化、插件生命周期管理、跨插件结果合并。

这个边界让 MusicFree 保持"小而美"的同时，获得了几乎无限的扩展能力——只要音源还在、插件还在维护，播放器就有用。

插件安全提醒

插件是可以执行任意 JavaScript 代码的模块——理论上一个恶意插件可以偷偷请求外部服务器、窃取本地存储的歌单数据、或者执行其他不受欢迎的操作。官方建议：

1. 尽量用知名的、star 数多的插件仓库。
2. 安装前可以看看插件源码——不需要看得很细，大概扫一眼有没有奇怪的网络请求（比如发到陌生域名的 fetch）。
3. 不要安装来路不明的插件——尤其是在陌生论坛或群里看到的、没有公开仓库的 .js 文件。

进一步了解

官方插件开发文档在 musicfree.catcat.work/plugin/introduction.html，包含完整的接口定义、数据结构说明和示例代码。