首页
/ MusicFree插件示例代码：常见功能实现参考

MusicFree插件示例代码：常见功能实现参考

2026-02-04 04:45:55作者：苗圣禹Peter
MusicFree
插件化、定制化、无广告的免费音乐播放器
项目地址：https://gitcode.com/GitHub_Trending/mu/MusicFree

还在为MusicFree插件开发而烦恼吗？本文为你提供全面的插件开发示例代码，涵盖搜索、播放、歌单导入等核心功能，助你快速上手插件开发！

插件基础结构

每个MusicFree插件都是一个CommonJS模块，必须返回一个符合IPluginDefine接口的对象：

module.exports = {
    // 平台名称（必填）
    platform: "示例音乐平台",
    
    // 插件版本
    version: "1.0.0",
    
    // 支持的MusicFree版本
    appVersion: ">=0.6.0",
    
    // 插件描述
    description: "示例音乐平台插件，支持搜索、播放等功能",
    
    // 支持的搜索类型
    supportedSearchType: ["music", "album", "artist"],
    
    // 默认搜索类型
    defaultSearchType: "music",
    
    // 缓存控制
    cacheControl: "cache",
    
    // 用户自定义变量
    userVariables: [
        {
            key: "apiKey",
            name: "API密钥",
            hint: "请输入音乐平台的API密钥"
        }
    ],
    
    // 搜索功能
    search: async function(query, page, type) {
        // 搜索实现
    },
    
    // 获取媒体源
    getMediaSource: async function(musicItem, quality) {
        // 播放源获取实现
    },
    
    // 其他功能方法...
};

核心功能实现示例

1. 搜索功能实现

// 音乐搜索示例
search: async function(query, page, type) {
    try {
        const pageSize = 20;
        const response = await axios.get('https://api.example.com/search', {
            params: {
                keyword: query,
                type: type,
                page: page,
                pageSize: pageSize
            },
            headers: {
                'User-Agent': 'Mozilla/5.0 (compatible; MusicFree)'
            }
        });
        
        const data = response.data;
        
        // 处理音乐搜索结果
        if (type === 'music') {
            return {
                isEnd: data.isEnd || (data.list && data.list.length < pageSize),
                data: data.list.map(item => ({
                    id: item.id,
                    platform: "示例音乐平台",
                    title: item.name,
                    artist: item.artists.map(a => a.name).join('/'),
                    duration: item.duration / 1000, // 转换为秒
                    artwork: item.album.picUrl,
                    album: item.album.name
                }))
            };
        }
        
        // 处理专辑搜索结果
        if (type === 'album') {
            return {
                isEnd: data.isEnd,
                data: data.list.map(item => ({
                    id: item.id,
                    platform: "示例音乐平台",
                    title: item.name,
                    artist: item.artist.name,
                    artwork: item.picUrl,
                    description: item.description
                }))
            };
        }
        
        // 处理歌手搜索结果
        if (type === 'artist') {
            return {
                isEnd: data.isEnd,
                data: data.list.map(item => ({
                    id: item.id,
                    platform: "示例音乐平台",
                    name: item.name,
                    avatar: item.picUrl,
                    worksNum: item.musicSize
                }))
            };
        }
        
    } catch (error) {
        console.error('搜索失败:', error);
        return {
            isEnd: true,
            data: []
        };
    }
}

2. 播放源获取实现

getMediaSource: async function(musicItem, quality = 'standard') {
    try {
        // 根据音质选择对应的URL
        const qualityMap = {
            'low': '128kbps',
            'standard': '320kbps', 
            'high': 'flac',
            'super': 'hires'
        };
        
        const response = await axios.get('https://api.example.com/song/url', {
            params: {
                id: musicItem.id,
                quality: qualityMap[quality]
            }
        });
        
        const urlInfo = response.data.data[0];
        
        if (!urlInfo.url) {
            throw new Error('无法获取播放地址');
        }
        
        return {
            url: urlInfo.url,
            headers: {
                'Referer': 'https://example.com/',
                'User-Agent': 'Mozilla/5.0 (compatible; MusicFree)'
            },
            quality: quality,
            userAgent: 'Mozilla/5.0 (compatible; MusicFree)'
        };
        
    } catch (error) {
        console.error('获取播放源失败:', error);
        return null;
    }
}

3. 歌词获取实现

getLyric: async function(musicItem) {
    try {
        const response = await axios.get('https://api.example.com/lyric', {
            params: { id: musicItem.id }
        });
        
        const lyricData = response.data;
        
        return {
            rawLrc: lyricData.lrc?.lyric || '',
            translation: lyricData.tlyric?.lyric || ''
        };
        
    } catch (error) {
        console.error('获取歌词失败:', error);
        return null;
    }
}

4. 歌单导入实现

importMusicSheet: async function(urlLike) {
    try {
        // 解析歌单ID
        const match = urlLike.match(/playlist\/(\d+)/);
        if (!match) {
            throw new Error('无效的歌单链接');
        }
        
        const playlistId = match[1];
        const response = await axios.get(`https://api.example.com/playlist/detail`, {
            params: { id: playlistId }
        });
        
        const playlist = response.data.playlist;
        
        // 获取歌单所有歌曲
        const allSongs = [];
        let offset = 0;
        const limit = 500;
        
        while (true) {
            const trackResponse = await axios.get('https://api.example.com/playlist/track/all', {
                params: {
                    id: playlistId,
                    limit: limit,
                    offset: offset
                }
            });
            
            const tracks = trackResponse.data.songs;
            allSongs.push(...tracks);
            
            if (tracks.length < limit) {
                break;
            }
            offset += limit;
        }
        
        return allSongs.map(song => ({
            id: song.id,
            platform: "示例音乐平台",
            title: song.name,
            artist: song.ar.map(a => a.name).join('/'),
            duration: song.dt / 1000,
            artwork: song.al.picUrl,
            album: song.al.name
        }));
        
    } catch (error) {
        console.error('导入歌单失败:', error);
        return null;
    }
}

5. 专辑信息获取

getAlbumInfo: async function(albumItem, page = 1) {
    try {
        const pageSize = 50;
        const response = await axios.get('https://api.example.com/album', {
            params: {
                id: albumItem.id,
                limit: pageSize,
                offset: (page - 1) * pageSize
            }
        });
        
        const albumData = response.data;
        const songs = albumData.songs || [];
        
        return {
            albumItem: {
                ...albumItem,
                description: albumData.album.description,
                publishTime: albumData.album.publishTime
            },
            musicList: songs.map(song => ({
                id: song.id,
                platform: "示例音乐平台",
                title: song.name,
                artist: song.ar.map(a => a.name).join('/'),
                duration: song.dt / 1000,
                artwork: song.al.picUrl,
                album: song.al.name
            })),
            isEnd: songs.length < pageSize
        };
        
    } catch (error) {
        console.error('获取专辑信息失败:', error);
        return null;
    }
}

高级功能示例

6. 用户变量使用

// 在插件中使用用户配置的变量
search: async function(query, page, type) {
    const apiKey = env.userVariables?.apiKey;
    if (!apiKey) {
        throw new Error('请先配置API密钥');
    }
    
    const response = await axios.get('https://api.example.com/search', {
        params: {
            keyword: query,
            type: type,
            page: page,
            api_key: apiKey
        }
    });
    
    // 处理结果...
}

7. 错误处理和重试机制

getMediaSource: async function(musicItem, quality, retryCount = 3) {
    for (let attempt = 1; attempt <= retryCount; attempt++) {
        try {
            const response = await axios.get('https://api.example.com/song/url', {
                params: { id: musicItem.id, quality: quality },
                timeout: 5000
            });
            
            if (response.data.code === 200) {
                return {
                    url: response.data.data[0].url,
                    headers: { 'User-Agent': 'MusicFree' }
                };
            }
            
        } catch (error) {
            if (attempt === retryCount) {
                console.error(`获取播放源失败（尝试${attempt}次）:`, error);
                return null;
            }
            await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
        }
    }
}

8. 缓存策略实现

// 使用内存缓存提高性能
const searchCache = new Map();

search: async function(query, page, type) {
    const cacheKey = `${query}-${type}-${page}`;
    
    // 检查缓存
    if (searchCache.has(cacheKey)) {
        return searchCache.get(cacheKey);
    }
    
    try {
        const result = await actualSearchImplementation(query, page, type);
        
        // 缓存结果（5分钟有效期）
        searchCache.set(cacheKey, result);
        setTimeout(() => searchCache.delete(cacheKey), 5 * 60 * 1000);
        
        return result;
    } catch (error) {
        console.error('搜索失败:', error);
        return { isEnd: true, data: [] };
    }
}

最佳实践和注意事项

代码质量规范

// 1. 统一的错误处理
function withErrorHandling(fn, defaultReturn) {
    return async function(...args) {
        try {
            return await fn(...args);
        } catch (error) {
            console.error('操作失败:', error.message);
            return defaultReturn;
        }
    };
}

// 2. 参数验证
function validateMusicItem(musicItem) {
    if (!musicItem || !musicItem.id || !musicItem.platform) {
        throw new Error('无效的音乐项目');
    }
}

// 3. 使用安全的HTTP请求
async function safeRequest(url, options = {}) {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);
    
    try {
        const response = await fetch(url, {
            ...options,
            signal: controller.signal,
            headers: {
                'User-Agent': 'MusicFree/1.0',
                ...options.headers
            }
        });
        
        clearTimeout(timeoutId);
        return response;
    } catch (error) {
        clearTimeout(timeoutId);
        throw error;
    }
}

性能优化建议

// 1. 批量请求优化
async function batchGetMediaSources(musicItems, quality) {
    const ids = musicItems.map(item => item.id).join(',');
    const response = await axios.get('https://api.example.com/song/url/batch', {
        params: { ids, quality }
    });
    
    return musicItems.map(item => {
        const urlInfo = response.data.find(d => d.id === item.id);
        return {
            url: urlInfo?.url,
            headers: { 'User-Agent': 'MusicFree' }
        };
    });
}

// 2. 请求去重
const pendingRequests = new Map();

async function deduplicatedRequest(key, requestFn) {
    if (pendingRequests.has(key)) {
        return pendingRequests.get(key);
    }
    
    const promise = requestFn();
    pendingRequests.set(key, promise);
    
    try {
        return await promise;
    } finally {
        pendingRequests.delete(key);
    }
}

完整插件示例

module.exports = {
    platform: "ExampleMusic",
    version: "1.0.0",
    appVersion: ">=0.6.0",
    description: "示例音乐平台插件",
    supportedSearchType: ["music", "album", "artist"],
    defaultSearchType: "music",
    cacheControl: "cache",
    
    userVariables: [
        {
            key: "apiKey",
            name: "API密钥",
            hint: "请输入ExampleMusic的API密钥"
        }
    ],
    
    search: async function(query, page, type) {
        const apiKey = env.userVariables?.apiKey;
        if (!apiKey) throw new Error("请配置API密钥");
        
        const response = await axios.get('https://api.example.com/search', {
            params: { q: query, type, page, limit: 20, api_key: apiKey }
        });
        
        return processSearchResult(response.data, type);
    },
    
    getMediaSource: async function(musicItem, quality) {
        const response = await axios.get('https://api.example.com/song/url', {
            params: { id: musicItem.id, quality }
        });
        
        return {
            url: response.data.url,
            headers: { 'User-Agent': 'MusicFree' },
            quality: quality
        };
    },
    
    getLyric: async function(musicItem) {
        const response = await axios.get('https://api.example.com/lyric', {
            params: { id: musicItem.id }
        });
        
        return {
            rawLrc: response.data.lrc,
            translation: response.data.tlyrc
        };
    }
};

function processSearchResult(data, type) {
    // 统一的搜索结果处理逻辑
    switch (type) {
        case 'music':
            return processMusicResults(data);
        case 'album':
            return processAlbumResults(data);
        case 'artist':
            return processArtistResults(data);
        default:
            return { isEnd: true, data: [] };
    }
}

总结

通过本文的示例代码，你应该已经掌握了MusicFree插件开发的核心技能。记住以下关键点：

  1. 遵循接口规范：严格实现IPluginDefine接口定义的方法
  2. 错误处理：完善的错误处理机制确保插件稳定性
  3. 性能优化：合理使用缓存和批量请求提升用户体验
  4. 用户友好：清晰的错误提示和配置指引

现在就开始你的插件开发之旅吧！如有问题，欢迎在MusicFree社区交流讨论。

MusicFree
插件化、定制化、无广告的免费音乐播放器
项目地址：https://gitcode.com/GitHub_Trending/mu/MusicFree
登录后查看全文

相关内容推荐

1 MusicFree的插件生态系统：探索第三方插件 2 MusicFree插件化音乐播放器完全使用指南3 解锁无限音乐体验：MusicFree插件完全攻略手册 🎵4 MusicFree插件系统终极指南：从入门到精通5 终极音乐自由：MusicFree插件如何解锁无限制听歌体验？6 MusicFree插件故障排除：常见问题与解决方案7 告别评论区空白：MusicFree插件评论系统全攻略8 MusicFree插件开发与使用完全指南9 MusicFree插件系统完全指南：从入门到精通10 MusicFree插件系统全攻略：从安装到精通的实用指南
热门项目推荐
相关项目推荐

热门内容推荐

1 【亲测免费】 开源项目 `build-your-own-x` 使用指南2 【亲测免费】 探索科技之旅：《Build Your Own X》项目详解3 GitHub_Trending/bu/build-your-own-x自动化：CI/CD流程在自制项目中的应用4 从零打造智能家居系统：用build-your-own-x实现家庭自动化

最新内容推荐

Degrees of Lewdity中文汉化终极指南：零基础玩家必看的完整教程Unity游戏翻译神器：XUnity Auto Translator 完整使用指南PythonWin7终极指南：在Windows 7上轻松安装Python 3.9+终极macOS键盘定制指南：用Karabiner-Elements提升10倍效率Pandas数据分析实战指南：从零基础到数据处理高手 Qwen3-235B-FP8震撼升级：256K上下文+22B激活参数7步搞定机械键盘PCB设计：从零开始打造你的专属键盘终极WeMod专业版解锁指南：3步免费获取完整高级功能DeepSeek-R1-Distill-Qwen-32B技术揭秘：小模型如何实现大模型性能突破音频修复终极指南：让每一段受损声音重获新生

项目优选

收起
kernelkernel
deepin linux kernel
C
27
11
docsdocs
OpenHarmony documentation | OpenHarmony开发者文档
Dockerfile
567
3.84 K
leetcodeleetcode
🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解
Java
68
20
nop-entropynop-entropy
Nop Platform 2.0是基于可逆计算理论实现的采用面向语言编程范式的新一代低代码开发平台，包含基于全新原理从零开始研发的GraphQL引擎、ORM引擎、工作流引擎、报表引擎、规则引擎、批处理引引擎等完整设计。nop-entropy是它的后端部分，采用java语言实现，可选择集成Spring框架或者Quarkus框架。中小企业可以免费商用
Java
12
1
flutter_flutterflutter_flutter
暂无简介
Dart
799
198
RuoYi-Vue3RuoYi-Vue3
🎉 (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue3 & Vite、Element Plus 的前后端分离权限管理系统
Vue
1.37 K
779
giteagitea
喝着茶写代码！最易用的自托管一站式代码托管平台，包含Git托管，代码审查，团队协作，软件包和CI/CD。
Go
23
0
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
349
200
pytorchpytorch
Ascend Extension for PyTorch
Python
377
450
rainbondrainbond
无需学习 Kubernetes 的容器平台，在 Kubernetes 上构建、部署、组装和管理应用，无需 K8s 专业知识，全流程图形化管理
Go
16
1