Erela.js 音乐机器人开发基础指南

2025-06-08 11:28:00作者：贡沫苏Truman

前言

Erela.js 是一个基于 Node.js 的 Discord 音乐机器人框架，它提供了与 Lavalink 服务器交互的便捷方式。本文将详细介绍如何从零开始构建一个基础的 Discord 音乐机器人。

环境准备

在开始之前，请确保您已具备以下条件：

Node.js 环境（建议使用最新 LTS 版本）
基础的 JavaScript 知识
已配置好的 Discord 开发者应用和机器人令牌
可连接的 Lavalink 服务器

安装 Erela.js

Erela.js 可以通过 npm 或 yarn 进行安装：

# 使用 npm 安装
npm install erela.js

# 或者使用 yarn 安装
yarn add erela.js

初始化音乐管理器

基础配置

首先需要创建一个 Manager 实例来管理音乐播放功能：

const { Client } = require("discord.js");
const { Manager } = require("erela.js");

const client = new Client();

// Lavalink 节点配置
const nodes = [
  {
    host: "localhost",  // Lavalink 服务器地址
    password: "youshallnotpass",  // Lavalink 服务器密码
    port: 2333,  // Lavalink 服务器端口
  }
];

// 创建音乐管理器实例
client.manager = new Manager({
  nodes,  // 连接节点配置
  send: (id, payload) => {
    const guild = client.guilds.cache.get(id);
    if (guild) guild.shard.send(payload);
  }
});

事件监听

设置必要的事件监听器来监控连接状态：

// 节点连接成功事件
client.manager.on("nodeConnect", node => {
  console.log(`节点 "${node.options.identifier}" 连接成功`);
})

// 节点错误事件
client.manager.on("nodeError", (node, error) => {
  console.log(`节点 "${node.options.identifier}" 发生错误: ${error.message}`);
})

// 客户端就绪事件
client.once("ready", () => {
  client.manager.init(client.user.id);
  console.log(`已登录为 ${client.user.tag}`);
});

// 必须监听 raw 事件以传递语音状态更新
client.on("raw", d => client.manager.updateVoiceState(d));

// 最后登录 Discord
client.login("你的机器人令牌");

实现播放命令

基础播放功能

下面实现一个简单的播放命令：

client.on("message", async message => {
  if (!message.content.startsWith("!") || !message.guild || message.author.bot) return;

  const [command, ...args] = message.content.slice(1).split(/\s+/g);

  if (command === "play") {
    // 检查用户是否在语音频道
    if (!message.member.voice.channel) {
      return message.reply("请先加入语音频道");
    }
    
    // 检查是否有搜索参数
    if (!args.length) {
      return message.reply("请输入歌曲名称或URL");
    }

    const search = args.join(" ");
    let res;

    try {
      // 搜索歌曲
      res = await client.manager.search(search, message.author);
      
      // 处理不同类型的搜索结果
      if (res.loadType === "LOAD_FAILED") throw res.exception;
      if (res.loadType === "PLAYLIST_LOADED") {
        return message.reply("本命令不支持播放列表");
      }
    } catch (err) {
      return message.reply(`搜索时出错: ${err.message}`);
    }

    if (res.loadType === "NO_MATCHES") {
      return message.reply("未找到匹配的歌曲");
    }

    // 创建播放器实例
    const player = client.manager.create({
      guild: message.guild.id,
      voiceChannel: message.member.voice.channel.id,
      textChannel: message.channel.id,
    });
  
    // 连接语音频道并添加歌曲到队列
    player.connect();
    player.queue.add(res.tracks[0]);
  
    // 如果没有正在播放的歌曲，则开始播放
    if (!player.playing && !player.paused && !player.queue.size) {
      player.play();
    }

    return message.reply(`已添加 ${res.tracks[0].title} 到播放队列`);
  }
});

播放器事件处理

常用事件

Erela.js 提供了多种事件来监控播放状态：

// 歌曲开始播放事件
client.manager.on("trackStart", (player, track) => {
  const channel = client.channels.cache.get(player.textChannel);
  channel.send(`正在播放: \`${track.title}\`, 由 \`${track.requester.tag}\` 点播`);
});

// 队列结束事件
client.manager.on("queueEnd", player => {
  const channel = client.channels.cache.get(player.textChannel);
  channel.send("播放队列已结束");
  player.destroy();  // 销毁播放器释放资源
});

// 歌曲异常事件
client.manager.on("trackError", (player, track, error) => {
  console.error(`播放 ${track.title} 时出错: ${error.message}`);
});

// 播放器断开连接事件
client.manager.on("playerDisconnect", player => {
  console.log(`播放器在 ${player.guild} 断开连接`);
});