파이썬 .env 환경변수로 디스코드 토큰 숨기기, 하드코딩 없이 안전하게 관리하는 법

디스코드 봇을 처음 만들 때 토큰을 코드에 그대로 적는 경우가 많습니다.

혼자 테스트할 때는 당장 편해 보이지만, 깃허브 업로드나 화면 공유 한 번으로 바로 사고가 날 수 있습니다.

토큰은 봇의 통제권을 가진 비밀번호라서 처음부터 분리해야 맞습니다.

파이썬에서는 .env 파일과 python-dotenv 조합이 가장 단순합니다.

초반 세팅도 빠르고, 이후 배포 단계까지 그대로 가져가기 좋습니다.

1. 왜 .env를 쓰는가

코드에 토큰을 직접 적는 방식은 아래 문제가 있습니다.

• 깃허브에 실수로 업로드될 수 있음
• 여러 환경에서 토큰을 바꾸기 번거로움
• 화면 공유나 스크린샷에서 노출될 수 있음

반대로 .env 파일로 분리하면 코드와 비밀값을 따로 관리할 수 있습니다.

입문 단계에서 가장 먼저 익혀 두면 좋은 습관입니다.

2. 패키지 설치

프로젝트 폴더에서 아래 명령어를 실행합니다.

pip install python-dotenv

기본 봇을 이미 만들었다면 `discord.py`와 같이 설치했을 가능성이 큽니다.
없다면 지금 같이 넣으면 됩니다.

3. .env 파일 만들기

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

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

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

`DISCORD_TOKEN`에는 Developer Portal에서 복사한 실제 토큰 값을 넣습니다.
큰따옴표는 굳이 넣지 않아도 됩니다.
앞뒤 공백도 없어야 합니다.

4. 파이썬 코드에서 읽는 방법

main.py에서는 아래처럼 불러오면 됩니다.

import os
from dotenv import load_dotenv

load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")
PREFIX = os.getenv("PREFIX", "!")

핵심은 `load_dotenv()`입니다.
이 함수가 `.env` 파일을 읽고 환경변수로 올려 줍니다.
그 뒤 `os.getenv()`로 값을 꺼내 쓰면 됩니다.

5. 실제 봇 코드에 붙이는 예시

아래 정도로 연결하면 충분합니다.

import os

from dotenv import load_dotenv
from discord.ext import commands
import discord

load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")
PREFIX = os.getenv("PREFIX", "!")

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(command_prefix=PREFIX, intents=intents)

if not TOKEN:
    raise ValueError("DISCORD_TOKEN 값이 없습니다.")

bot.run(TOKEN)

토큰 값이 없으면 바로 에러를 내도록 둬야 합니다.
그냥 `None` 상태로 실행하면 어디서 잘못됐는지 찾기 어려워집니다.

6. .env를 썼는데도 로그인 실패가 날 때

아래를 먼저 봅니다.

• 토큰 앞뒤에 공백이 붙었는가
• .env 파일 이름이 정확한가
• 프로젝트 루트에 파일이 있는가
• load_dotenv()를 실제로 호출했는가
• 토큰을 재발급한 뒤 예전 값을 그대로 두지 않았는가

Improper token has been passed가 뜨면 거의 이 구간에서 문제를 찾을 수 있습니다.

7. .gitignore도 같이 넣어 둬야 안전하다

.env를 분리해도 깃 추적에서 빼지 않으면 결국 유출될 수 있습니다.

프로젝트 루트에 .gitignore가 있다면 아래 줄을 넣습니다.

.env
.venv
__pycache__/

`.env`를 분리해 두고도 깃허브에 올려 버리는 경우가 많습니다.
여기서 한 번 더 막아 둬야 맞습니다.

8. 운영용 토큰과 테스트용 토큰을 나눌 수도 있다

봇을 계속 키울 계획이라면 테스트 봇과 운영 봇을 따로 두는 경우도 많습니다.

그때도 .env 구조를 유지하면 관리가 편합니다.

예를 들어 아래처럼 변수를 분리할 수 있습니다.

DISCORD_TOKEN_DEV=개발용_토큰
DISCORD_TOKEN_PROD=운영용_토큰

입문 단계에서는 여기까지 갈 필요는 없지만, 구조를 알아 두면 나중에 편합니다.

9. 지금 단계에서 가장 중요한 것

토큰은 코드에 하드코딩하지 않는 것.
.env 파일을 깃에서 제외하는 것.
토큰이 노출되면 즉시 재발급하는 것.

 

이 세 가지만 지켜도 초반 사고 대부분은 막을 수 있습니다.

10. 다음 단계

기본 봇을 아직 안 만들었다면 파이썬 디스코드 봇 만들기 처음부터 끝까지부터 먼저 보고 와야 합니다.

슬래시 명령어 구조로 넘어갈 준비가 됐다면 다음 글에서 바로 연결하면 됩니다.