discord.js v14 디스코드 봇 만들기 처음부터 끝까지

파이썬 쪽 흐름을 한 번 익힌 뒤에는 Node.js 기반으로도 같은 구조를 만들 수 있어야 선택지가 넓어집니다.

디스코드 봇 생태계에서는 discord.js 수요가 여전히 큽니다.

특히 버튼, 모달, 슬래시 명령어 예제를 찾다 보면 대부분 discord.js v14 기준으로 만나는 경우가 많습니다.

Node.js 쪽에서 가장 먼저 손에 익혀 둘 기본 골격은 discord.js v14입니다.

토큰 분리, 패키지 설치, 기본 명령어, 서버 초대, 실행 테스트까지 한 번에 정리합니다.

파이썬 쪽 흐름과 비교해 보고 싶다면 파이썬 디스코드 봇 만들기 처음부터 끝까지, discord.py 입문 가이드를 같이 열어 두면 구조 차이를 보기에 좋습니다.

1. Node.js 버전부터 맞춘다

discord.js v14는 너무 오래된 Node 버전에서는 문제를 일으킬 수 있습니다.

처음에는 코드보다 실행 환경에서 더 자주 막힙니다.

Node 18 이상을 맞춰 둬야 안전합니다.

터미널에서 아래 명령어로 버전을 확인합니다.

node -v
npm -v

Node가 없거나 버전이 너무 낮다면 먼저 설치를 마칩니다.
이 단계가 어긋나면 패키지 설치는 되는데 실행 시점에서 경고가 뜨는 경우가 나옵니다.

2. 프로젝트 폴더 만들기

빈 폴더를 하나 만들고 터미널에서 이동합니다.

그다음 npm init으로 기본 프로젝트를 시작합니다.

mkdir my-discordjs-bot
cd my-discordjs-bot
npm init -y
npm install discord.js dotenv

`discord.js`는 디스코드 API 통신용 패키지입니다.
`dotenv`는 토큰을 `.env`에 분리해서 읽어오는 용도입니다.

3. Developer Portal에서 봇 만들기

브라우저에서 Discord Developer Portal로 들어갑니다.

새 애플리케이션을 만든 뒤 Bot 메뉴에서 봇을 추가합니다.

토큰을 복사할 수 있으면 일단 안전한 곳에 잠깐 보관합니다.

여기서 Message Content Intent도 같이 켜 둡니다.

지금 단계에서는 접두사 명령어를 테스트할 예정이라 이 설정이 빠지면 !핑이 반응하지 않습니다.

이 문제는 Message Content Intent 설정법, 디스코드 봇이 명령어를 읽지 못할 때 먼저 볼 것에서 더 자세히 다뤘습니다.

4. .env 파일 만들기

프로젝트 루트에 .env 파일을 만듭니다.

내용은 아래처럼 두면 됩니다.

DISCORD_TOKEN=여기에_디스코드_봇_토큰
PREFIX=!

토큰을 코드에 직접 적어 두면 화면 공유나 깃 업로드 때 그대로 노출될 수 있습니다.
파이썬과 마찬가지로 JS 쪽도 처음부터 분리해야 합니다.

5. main.js 작성하기

루트에 main.js 파일을 만들고 아래 코드를 넣습니다.

const { Client, GatewayIntentBits, EmbedBuilder } = require("discord.js");
const dotenv = require("dotenv");

dotenv.config();

const token = process.env.DISCORD_TOKEN;
const prefix = process.env.PREFIX || "!";

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,
  ],
});

client.once("ready", () => {
  console.log(`로그인 성공: ${client.user.tag}`);
});

client.on("messageCreate", async (message) => {
  if (message.author.bot) {
    return;
  }

  if (!message.content.startsWith(prefix)) {
    return;
  }

  const args = message.content.slice(prefix.length).trim().split(/\s+/);
  const command = args.shift()?.toLowerCase();

  if (command === "핑") {
    await message.reply(`퐁, 현재 지연 시간은 ${client.ws.ping}ms 입니다.`);
    return;
  }

  if (command === "도움") {
    await message.reply([
      "사용 가능한 명령어",
      `${prefix}핑 - 응답 속도 확인`,
      `${prefix}도움 - 명령어 목록 확인`,
      `${prefix}서버정보 - 현재 서버 정보 확인`,
    ].join("\n"));
    return;
  }

  if (command === "서버정보") {
    if (!message.guild) {
      await message.reply("이 명령어는 서버에서만 사용할 수 있습니다.");
      return;
    }

    const embed = new EmbedBuilder()
      .setTitle("서버 정보")
      .addFields(
        { name: "서버 이름", value: message.guild.name, inline: false },
        { name: "멤버 수", value: String(message.guild.memberCount), inline: true },
        { name: "채널 수", value: String(message.guild.channels.cache.size), inline: true }
      );

    await message.reply({ embeds: [embed] });
  }
});

if (!token) {
  throw new Error("DISCORD_TOKEN 값이 없습니다.");
}

client.login(token);

파이썬의 `commands.Bot`처럼 편하게 명령어를 다루는 구조도 만들 수 있지만, 처음에는 `messageCreate` 이벤트를 직접 보면 흐름 이해에 유리합니다.
메시지가 들어오고, 접두사를 자르고, 명령어를 분기하는 방식이 눈에 바로 들어오기 때문입니다.

6. 서버 초대 링크 만들기

OAuth2 -> URL Generator로 들어갑니다.

bot 스코프를 고르고, 최소한 아래 권한을 켭니다.

View Channels
Send Messages
Read Message History
Embed Links

`!핑` 정도만 테스트할 때는 이 정도면 충분합니다.
초대 링크 생성 흐름이 익숙하지 않다면 [디스코드 봇 초대 링크 생성법, 권한이 꼬이지 않게 링크 만드는 방법](https://blog.dishost.kr/59)을 먼저 봐야 빠릅니다.

7. 실행하기

터미널에서 아래 명령어를 실행합니다.

node main.js

정상 실행되면 `로그인 성공` 로그가 뜹니다.
그다음 서버 채널에서 아래 명령어를 넣어 봅니다.

!핑
!도움
!서버정보

초반 테스트는 봇 명령어 전용 채널에서 해야 합니다.
잡담 채널에서 바로 실험하면 로그가 섞여서 확인이 느려집니다.

8. 여기서 자주 막히는 문제

• messageCreate가 아예 안 들어오는 경우: Developer Portal의 Message Content Intent 누락이 가장 흔합니다.
• Used disallowed intents나 관련 경고가 뜨는 경우: 코드에서는 MessageContent를 켰는데 Portal에서는 저장하지 않은 경우가 많습니다.
• 토큰 오류가 나는 경우: .env 공백, 잘못 복사한 토큰, 재발급 후 예전 값 사용을 먼저 봅니다.

JS 쪽은 코드 문법보다 환경값과 인텐트에서 더 자주 멈춥니다.

9. 다음 단계

기본 JS 봇이 켜졌다면 다음에는 슬래시 명령어 구조로 넘어가거나 AI 기능을 붙이면 됩니다.

지금 순서에서는 먼저 AI 챗봇 확장으로 이어지는 흐름이 자연스럽습니다.

24시간 운영까지 바로 올릴 계획이라면 24시간 디스코드 봇 무료 호스팅, 디스호스트처럼 별도 서버에 올려 두는 단계가 필요합니다.