写一个自己的插件——从零到能搜歌

适合谁

这页面向有以下基础的读者：

能用 JavaScript 写异步函数（Promise / async-await）
基本了解 HTTP 请求、JSON 解析
能看官方音源的网页端或 App 抓到接口地址（如果音源没有开放 API）

最小插件骨架

一个最小可用的插件需要 module.exports 导出的对象包含 name、version 和至少 search + getMediaUrl 两个接口：

// 自定义音源插件骨架示意
module.exports = {
  name: '我的私有音源',
  version: '1.0.0',
  desc: '接入我自己的音乐服务器',

  // 搜索——返回结构化歌曲数组
  search: async (keyword, type, page) => {
    // 调用你的音源 HTTP API
    const resp = await fetch(`https://你的服务器/api/search?q=${keyword}&page=${page}`);
    const data = await resp.json();
    return data.items.map(item => ({
      id: item.id,
      name: item.name,
      artist: item.singer,
      album: item.album,
      source: 'mine'  // 用于宿主标记音源
    }));
  },

  // 获取播放 URL
  getMediaUrl: async (musicItem, quality) => {
    const resp = await fetch(`https://你的服务器/api/play?id=${musicItem.id}`);
    const data = await resp.json();
    return { url: data.url };
  }
};

宿主会传入什么

宿主调用接口时会传标准化的参数对象。以 search 为例，type 参数的值是 'music'、'album' 或 'artist'，page 是从 1 开始的页码。宿主控制分页逻辑，插件只返回当前页的数据。

返回的数据也有标准结构——歌曲对象需要包含 id、name、artist、album、source 等字段，宿主按这些字段渲染 UI。

测试插件

开发时可以把插件文件保存到本地，然后在 MusicFree 里走「从本地安装插件」流程导入测试。如果插件有语法错误或接口返回数据不符合预期格式，宿主会报错提示。

官方开发文档入口

完整的接口定义、数据结构说明、示例代码在 musicfree.catcat.work/plugin/introduction.html。这份文档比 README 里的简略介绍详细得多，开发前建议通读一遍。

分发插件

开发完成后，如果想分享给其他人：

把 .js 文件托管到任何能被公开 HTTP 访问的地址（GitHub Raw、GitCode Raw、自建服务器）。
如果维护了多个插件，可以像官方示例仓库一样写一个 plugins.json 描述文件，让用户一键批量安装。
在 GitHub / Gitee 创建仓库，写好使用说明，方便他人 issue 反馈。

版权提醒

开发插件时请合理合法使用音源接口。不要做违反音源服务条款或版权法的事。开发者声明本软件及其第三方插件产生的数据仅供学习参考，版权数据请及时删除。