블로그/나만의 디스코드 봇 만들기: Node.js와 discord.js 개발 입문

나만의 디스코드 봇 만들기: Node.js와 discord.js 개발 입문

디스코드봇Nodejsdiscordjs
나만의 디스코드 봇 만들기: Node.js와 discord.js 개발 입문

코딩을 처음 배우기 시작할 때 가장 기억에 남는 순간은 내가 만든 프로그램이 세상에 나와 누군가와 상호작용하는 모습을 처음 볼 때인 것 같아요. 매일 친구들과 대화하던 디스코드 채널에 내가 직접 작성한 코드로 움직이는 봇이 들어와 실시간으로 대답하는 경험은 코딩을 훨씬 더 재미있게 만들어 줍니다.

과거에는 파이썬이나 루비로 간단한 봇을 만드는 가이드가 많았지만, 최근에는 웹 개발의 표준 언어로 자리 잡은 자바스크립트와 Node.js 환경을 활용해 봇을 개발하는 경우가 대다수입니다. 특히 대규모 서버로 확장하거나 대시보드 웹 서비스와 연동할 때 Node.js의 비동기 이벤트 처리 성능이 큰 강점을 발휘하기 때문인데요.

이번 글에서는 자바스크립트 런타임인 Node.js와 대표적인 라이브러리인 discord.js v14를 활용해 슬래시 명령어를 지원하는 디스코드 봇의 기초 뼈대를 구축하는 과정을 자세하게 전해드리려고 합니다.

1. 개발 환경 구축: Node.js 설치와 프로젝트 초기화

자바스크립트 기반의 디스코드 봇을 작동시키려면 컴퓨터에 Node.js가 설치되어 있어야 합니다. Node.js는 브라우저 밖에서도 자바스크립트 코드를 실행할 수 있게 해주는 도구인데요. 봇 개발을 시작하기 전, 컴퓨터의 OS에 맞춰 Node.js를 설치하는 과정부터 꼼꼼하게 알아볼게요.

Node.js 버전 고르기: LTS vs Current

공식 홈페이지에 들어가면 두 가지 버전이 보여요.

  • LTS (Long Term Support): 오랜 기간 안정성과 보안을 보장하는 버전입니다. 실제 서비스를 배포하고 안정적으로 운영할 때 대부분 이 버전을 선택합니다.
  • Current: 최신 자바스크립문법과 기능을 미리 써볼 수 있는 버전이지만, 아직 검증되지 않은 버그가 섞여 있을 수 있습니다.

저희는 패키지 설치 시 발생할 수 있는 호환성 문제를 방지하기 위해, 가장 안정적인 LTS 버전을 설치해 진행할게요.

운영체제별 Node.js 설치하기

Windows 환경

Windows에서는 공식 웹사이트를 통해 편리하게 설치할 수 있습니다.

  1. 공식 홈페이지( https://nodejs.org ) 에 접속합니다.
  2. 초록색 LTS 버튼을 클릭하여 설치 프로그램(.msi)을 내려받습니다.
  3. 다운로드한 파일을 실행하고, 안내에 따라 'Next'를 누르며 설치를 진행합니다.
  4. 설치 중간에 Tools for Native Modules 설치 여부를 묻는 체크박스가 나옵니다. 필수는 아니지만, 나중에 C++ 기반의 특정 라이브러리를 추가할 때 생길 수 있는 에러를 방지하기 위해 체크해 두시는 것을 추천합니다.
  5. 설치가 끝나면 컴퓨터를 한 번 재시작해 주세요.

macOS 환경

macOS에서는 설치 파일을 다운로드받는 방법 외에도 개발 생산성을 높여주는 관리 도구를 많이 활용합니다.

방법 A. 공식 패키지로 설치하기 (가장 쉬운 방법)
  1. 공식 홈페이지에서 macOS용 설치 파일(.pkg)을 내려받아 설치를 마칩니다.
방법 B. Homebrew로 설치하기

macOS의 패키지 관리 도구인 Homebrew가 이미 설치되어 있다면 터미널에서 명령어 한 줄로 편리하게 설치할 수 있습니다.

brew install node
방법 C. NVM(Node Version Manager)으로 설치하기 (추천)

여러 프로젝트를 다루다 보면 프로젝트마다 서로 다른 Node.js 버전을 써야 하는 일이 생깁니다. 이때 NVM이라는 도구를 사용하면 편리하게 여러 버전을 오가며 설치하고 관리할 수 있습니다.

  1. 터미널을 열고 아래 명령어를 입력해 NVM을 설치합니다.
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
  1. 터미널 창을 완전히 종료했다가 다시 열어줍니다. (환경 변수 적용을 위함입니다)
  2. 아래 명령어를 실행하여 가장 최신의 LTS 버전을 설치합니다.
nvm install --lts
  1. 설치가 끝나면 현재 터미널 세션에서 방금 설치한 LTS 버전을 기본값으로 지정해 줍니다.
nvm use --lts

설치 결과 확인하기

설치를 완료했다면 터미널(Windows는 명령 프롬프트나 PowerShell, macOS는 터미널)을 열고 아래 명령어를 실행해 보세요.

node -v
npm -v

이때 화면에 버전을 나타내는 숫자(예: v20.11.0 등)가 잘 나타난다면 성공적으로 설치된 것입니다. 디스코드 봇 개발에 사용되는 라이브러리(discord.js)는 비동기 처리의 편의성을 위해 최소 v18 이상의 Node.js 버전을 요구하므로, 버전 숫자가 18 이상인지 확인해 주시기 바랍니다.

프로젝트 폴더 만들고 초기화하기

이제 봇의 코드를 담을 프로젝트 폴더를 만들고, 프로젝트를 시작해 볼게요.

mkdir my-discord-bot
cd my-discord-bot
npm init -y

npm init -y 명령어를 입력하면 질문 과정을 거치지 않고 기본 설정값이 채워진 package.json 파일이 바로 만들어집니다. 이 파일은 우리 프로젝트의 이름과 버전 정보, 그리고 우리가 다운로드할 라이브러리 목록을 적어두는 지도 같은 역할을 해요.

다음으로 디스코드 서버와 편리하게 소통하기 위해 discord.js 라이브러리와 봇의 로그인 정보를 안전하게 관리하기 위한 dotenv 패키지를 설치하겠습니다.

npm install discord.js dotenv

설치가 완료되면 폴더 안에 실제 패키지 파일들이 들어가는 node_modules 폴더와 정확한 설치 버전을 기록해 두는 package-lock.json 파일이 새로 생긴 것을 확인할 수 있습니다.

2. 디스코드 개발자 포털에서의 봇 등록 과정

코드를 작성하기 전에, 먼저 디스코드 공식 사이트에 우리 봇을 등록하고 로그인을 위한 고유 키(토큰)를 받아야 합니다.

  1. 디스코드 개발자 포털(Discord Developer Portal)에 로그인합니다.
  2. New Application 버튼을 클릭하고 봇의 이름(예: MyNodeBot)을 적고 Create를 클릭합니다.
  3. 왼쪽의 Bot 탭으로 진입하여 Reset Token 버튼을 눌러 영문 대소문자와 숫자가 섞인 긴 마스터 암호 키를 생성하여 복사해 둡니다. 이 문자열이 봇의 토큰(Token)입니다.

[!IMPORTANT] 토큰 값은 봇의 로그인 비밀번호와 동일하므로 외부 깃허브 저장소나 공개 게시판에 노출되는 즉시 악성 해킹 봇들의 침입으로 서버가 손상될 위험이 큽니다.

  1. 동일한 Bot 설정 페이지에서 화면을 아래로 내리면 Privileged Gateway Intents 섹션이 보입니다. 디스코드 보안 정책 강화로 인해 봇이 수신할 수 있는 실시간 정보 범위가 제한되어 있는데요. 이번 기초 봇 구축에서는 봇이 속한 서버의 기본적인 변화를 알아차려야 하기 때문에 Guilds 관련 토글(Intents) 스위치를 켜두어야 접속 오류를 피할 수 있습니다.

3. 슬래시 커맨드 설계 구조 이해: 글로벌 vs 길드 배포

디스코드는 예전의 접두사 방식(예: !ping) 대신 슬래시(/) 기호로 목록을 띄우는 슬래시 커맨드를 채택해 활용하고 있습니다. 이 슬래시 명령어를 작동시키려면, 봇이 어떤 명령어를 가졌는지 디스코드 공식 서버에 미리 알려주는 과정이 필요합니다.

이 등록 과정은 두 가지 방식으로 나뉩니다.

  • 글로벌 배포(Global Commands): 봇이 들어가 있는 전 세계 모든 서버에서 명령어를 사용할 수 있게 하는 방식입니다. 다만 디스코드 API 서버에 반영되어 전파되기까지 최대 1시간가량의 지연 시간(캐싱 처리 등)이 걸릴 수 있다는 단점이 있습니다.
  • 길드별 배포(Guild Commands): 특정 서버의 고유 ID 값을 명시하여 특정 서버 한 곳에만 명령어를 배포하는 방식입니다. 명령어 갱신이 대기 시간 없이 거의 즉시 반영되므로, 개발 중 기능을 신속하게 테스트해야 하는 초기 디버깅 단계에서 매우 유리합니다.

저희는 처음 만든 봇이 제대로 작동하는지 빠르게 확인하기 위해, 특정 서버 전용으로 명령어를 등록하는 스크립트를 작성해 볼 것입니다.

4. 슬래시 커맨드 등록 스크립트 작성 (deploy-commands.js)

개발자 포털에서 받아온 토큰과 봇 ID 정보를 사용해 디스코드에 명령어를 보내주는 등록 스크립트를 만들어 볼게요. deploy-commands.js 파일을 생성하고 아래 코드를 작성합니다.

const { REST, Routes, SlashCommandBuilder } = require('discord.js');

// 1. 등록할 슬래시 명령어의 구성 데이터 정의
const commands = [
  new SlashCommandBuilder()
    .setName('ping')
    .setDescription('봇의 통신 지연 상태를 측정하고 퐁으로 답장합니다.')
].map(command => command.toJSON());

// 2. 디스코드 REST API 통신 모듈 초기화
const rest = new REST({ version: '10' }).setToken('YOUR_BOT_TOKEN_HERE');

// 3. 비동기 함수 실행을 통한 명령어 레이아웃 배포
(async () => {
  try {
    console.log('슬래시 명령어 배포 작업을 시작합니다.');

    // 빠른 실시간 테스트를 위해 특정 서버(길드) 전용 배포 경로로 전송합니다.
    await rest.put(
      Routes.applicationGuildCommands(
        'YOUR_CLIENT_ID_HERE',
        'YOUR_GUILD_ID_HERE'
      ),
      { body: commands }
    );

    console.log('특정 길드 서버에 슬래시 명령어가 무사히 등록 완료되었습니다.');
  } catch (error) {
    console.error('명령어 등록 과정 수행 중 에러 감지:', error);
  }
})();

상세 값 기입 팁

  • YOUR_BOT_TOKEN_HERE: 아까 복사해 둔 봇의 비밀 토큰을 붙여 넣습니다.
  • YOUR_CLIENT_ID_HERE: 봇 포털 메인 화면의 Application ID(Client ID) 값을 적어 줍니다.
  • YOUR_GUILD_ID_HERE: 테스트를 진행할 내 디스코드 서버의 고유 아이디입니다. 디스코드 앱의 설정 - 고급 메뉴에서 개발자 모드를 활성화한 뒤, 좌측의 내 서버 이름을 마우스 우클릭하여 ID 복사 단추를 클릭해 획득할 수 있습니다.

정보를 모두 입력했다면 터미널 창에 아래 실행 명령어를 입력합니다.

node deploy-commands.js

5. 실시간 연결 감지 및 응답 프로그램 구축 (index.js)

명령어가 성공적으로 등록되었다면, 이제 사용자의 입력을 실시간으로 받아 알맞은 행동을 취하는 봇의 핵심 파일을 만들어야 합니다. index.js 파일을 새로 만들어 아래와 같이 코드를 작성해 볼게요.

const { Client, GatewayIntentBits } = require('discord.js');

// 봇이 디스코드에서 받아올 이벤트 범위(인텐트)를 결정합니다
const client = new Client({ 
  intents: [GatewayIntentBits.Guilds] 
});

// 봇이 준비되었을 때 실행되는 이벤트
client.once('ready', () => {
  console.log(`성공: ${client.user.tag} 계정으로 로그인했습니다.`);
});

// 사용자가 메시지 입력 등으로 행동을 취했을 때 반응하는 리스너
client.on('interactionCreate', async interaction => {
  // 유저가 슬래시 명령어를 입력한 것이 아니라면 그냥 넘어갑니다.
  if (!interaction.isChatInputCommand()) return;

  const { commandName } = interaction;

  // 입력한 명령어가 'ping'이라면
  if (commandName === 'ping') {
    // 대답을 보냅니다.
    await interaction.reply('Pong!');
  }
});

// 봇 로그인
client.login('YOUR_BOT_TOKEN_HERE');

봇을 실행하기 위해 터미널에 아래 명령어를 입력해 주세요.

node index.js

로그인 성공 메시지를 확인했다면 디스코드 서버 대화창에 / 키를 입력해 테스트를 해봅니다. 목록에 생성한 봇 아이콘과 설명이 뜨며, 엔터 입력 시 Pong! 메시지가 지연 없이 대답되는 것을 확인할 수 있습니다.

6. 오작동 트러블슈팅과 대처 팁

봇을 시작하는 과정에서 흔히 겪는 두 가지 오류와 그 해결 방법을 정리했어요.

  • DisallowedIntents 오류: 봇이 로그인하려는 시점에 에러 메시지가 뜨며 연결이 끊긴다면, 개발자 포털에서 설정한 Intents 옵션 문제일 수 있어요. 아까 2단계에서 체크했던 Guilds 관련 스위치들이 켜져 있는지 개발자 포털 페이지를 다시 한 번 확인해 보세요.
  • TokenInvalid 또는 로그인 무한 대기: 발급받은 토큰 정보 of 앞뒤에 공백이 섞여 들어갔거나 글자 일부가 지워졌을 때 발생해요. 코드를 다시 차분히 살펴보시거나, 개발자 포털에서 'Reset Token' 버튼을 눌러 토큰을 새로 받아 붙여넣는 편이 가장 확실합니다.

Node.js를 활용한 디스코드 봇 개발은 향후 웹 대시보드 연동이나 데이터베이스 관리 등 더 큰 프로젝트로 나아가는 아주 좋은 출발점이에요. 오늘 시작한 작은 봇이 여러분의 서버를 훨씬 더 풍성하게 만드는 유용한 도구로 자라나기를 바랍니다.

📚 시리즈: bot-development

1. 파이썬으로 디스코드 봇 만들기: 개발 환경 구축부터 토큰 보안까지2. 디스코드 봇 호스팅 : 컴퓨터 안켜놓고 24시간 구동하는 방법3. 나만의 디스코드 봇 만들기: Node.js와 discord.js 개발 입문4. Discord.js에서 Component V2 사용하기