앱에 데이터베이스 URL이 필요합니다. 랩탑에서는 로컬 데이터베이스이고, CI에서는 일회용 데이터베이스이고, 프로덕션에서는 관리형 클러스터입니다. 이들 중 하나를 하드 코딩한다는 것은 각 환경에 맞게 코드를 변경하는 것을 의미합니다. 환경 변수가 이 문제를 해결합니다. 코드는 DATABASE_URL이며 각 환경은 고유한 값을 제공합니다.

이 아이디어는 배포마다 달라지는 구성이 환경에 속한다는 Twelve-Factor App 방법의 핵심입니다. Windows에서 Python 3.13을 사용하여 아래 동작을 테스트했습니다. 표시된 모든 출력은 해당 실행에서 나온 것입니다.

환경 변수란 무엇입니까?

실행 중인 모든 프로세스에는 환경이라는 명명된 텍스트 값 집합이 있습니다. 익숙한 예로는 쉘에 프로그램을 찾을 위치를 알려주는 PATH과 HOME 또는 USERPROFILE이 있습니다. 여러분의 앱은 APP_PORT, LOG_LEVEL 또는 DATABASE_URL과 같은 설정에 대해 동일한 메커니즘을 사용할 수 있습니다.

환경 변수 설정

이는 현재 터미널 세션 동안에만 지속됩니다. 이를 영구적으로 만들려면 ~/.bashrc과 같은 셸 프로필에 추가하거나 Windows의 경우 시스템 환경 설정 또는 setx를 사용합니다. 애플리케이션의 경우 일반적으로 시스템 전체에 설정하는 것보다 배포 시 제공하는 것이 더 좋습니다.

코드로 읽기

import os

port = os.environ.get("APP_PORT", "8000")   # default if missing
print(port)                                  # 8000

db = os.environ["DATABASE_URL_MISSING_DEMO"]
# KeyError: 'DATABASE_URL_MISSING_DEMO'

선택적 설정에는 기본값으로 .get()을 사용하십시오. 앱이 없으면 작동하지 않는 설정에는 KeyError를 나타내는 대괄호를 사용합니다. 다른 언어도 비슷합니다. Node.js에서는 process.env.APP_PORT, Java에서는 System.getenv("APP_PORT"), Go에서는 os.Getenv("APP_PORT")입니다.

모든 것은 문자열이다

이것은 모든 언어로 사람들을 사로잡습니다. 포트를 설정한 다음 “1”을 추가했습니다.

os.environ["APP_PORT"] = "8080"
port = os.environ["APP_PORT"]
print(type(port).__name__, repr(port), port + "1")
# str '8080' 80801

os.environ["APP_PORT"] = 8080
# TypeError: str expected, not int

값이 텍스트로 반환되었으며 추가하면 8081이 아닌 80801이 생성되었습니다. int(os.environ["APP_PORT"])와 같이 명시적으로 변환합니다. 부울은 더 나쁩니다.

os.environ["DEBUG"] = "false"
print(bool(os.environ["DEBUG"]))   # True

비어 있지 않은 문자열은 Python에서 참이므로 "false"은 True가 되었습니다. 디버그 모드는 프로덕션 환경에서 켜져 있었을 것입니다. 부울을 의도적으로 구문 분석합니다.

def env_bool(name, default=False):
    value = os.environ.get(name)
    if value is None:
        return default
    return value.strip().lower() in {"1", "true", "yes", "on"}

env_bool("DEBUG")                   # False
env_bool("NOT_SET", default=True)   # True

프로세스가 이를 상속하는 방법

하위 프로세스는 상위 환경의 사본을 받습니다. 우리는 이를 확인하기 위해 하위 Python 프로세스를 시작했습니다.

child sees: 8080 inherited     # default: full copy of the parent's environment
child sees: 9000 None          # given a custom env: only what we passed
parent sees child var: None    # a child's changes never flow back

세 가지 실습 수업이 이어집니다. 내보낸 변수는 작성하지 않은 스크립트를 포함하여 시작하는 모든 프로그램에서 볼 수 있으며 이는 비밀에 중요합니다. 사용자 정의 환경을 전달하면 모든 것이 대체되므로 자녀에게 필요한 모든 것을 포함하십시오. 그리고 스크립트는 상위 쉘의 변수를 변경할 수 없습니다. 이것이 바로 도구가 파일을 실행하는 대신 파일을 source하도록 요청하는 이유입니다.

.env 파일

많은 변수를 직접 입력하는 것은 지루하므로 대부분의 프로젝트에서는 로컬 개발 값을 .env 파일에 유지합니다.

# local development only
APP_PORT=8080
DATABASE_URL="postgres://dev:devonly@localhost:5432/shop"
FEATURE_SEARCH=true

Python-dotenv 및 Node.js용 dotenv와 같은 라이브러리는 시작 시 이 파일을 로드합니다. Node.js 20.6 이상에서는 --env-file을 사용하여 기본적으로 로드할 수도 있습니다. 아이디어를 확인하기 위해 위의 파일을 다음과 같이 변환하는 작은 파서를 작성했습니다.

{'APP_PORT': '8080',
 'DATABASE_URL': 'postgres://dev:devonly@localhost:5432/shop',
 'FEATURE_SEARCH': 'true'}

실제로 실제 라이브러리를 사용하십시오. 10줄 버전에서는 무시되는 인용, 이스케이프, 주석 및 여러 줄 값을 처리합니다. 기본적으로 대부분의 dotenv 로더는 이미 설정된 변수를 재정의하지 않으므로 실제 환경 값이 파일을 우선합니다. 그것은 일반적으로 당신이 원하는 것입니다.

시작 시 구성 유효성 검사

변수가 누락되면 명확한 메시지와 함께 앱이 즉시 중지되어야 하며, 한 시간 후에 혼란스러운 오류가 발생하지 않아야 합니다. 로드할 때 필수 설정을 확인했습니다.

REQUIRED = ["DATABASE_URL", "SECRET_KEY"]

def check_required(env):
    missing = [k for k in REQUIRED if not env.get(k)]
    if missing:
        raise SystemExit(f"Missing required settings: {', '.join(missing)}")

# Missing required settings: SECRET_KEY

형식화된 구성 라이브러리가 더 발전합니다. Python의 Pydantic 설정, Node.js의 zod 또는 envalid, Java의 Spring 구성 속성은 모두 유형을 변환하고 모든 문제를 한 번에 보고합니다.

환경 변수 및 비밀

환경 변수는 API 키와 같은 비밀을 앱에 전달하는 일반적인 방법이며, 하드 코딩하는 것보다 훨씬 낫습니다. 그들이 알아야 할 약점은 다음과 같습니다.

• 테스트에서 알 수 있듯이 하위 프로세스는 이를 상속합니다.
• 이는 충돌 보고서, 디버그 페이지 및 환경을 덤프하는 로그에 나타날 수 있습니다.
• 일부 시스템에서는 동일한 사용자가 실행하는 다른 프로세스에서 이를 읽을 수 있습니다.

프로덕션의 경우 많은 팀이 HashiCorp Vault, AWS Secrets Manager, Azure Key Vault 또는 Google Secret Manager와 같은 전용 관리자에 비밀을 보관하고 런타임에 주입합니다. 일부는 변수 대신 파일로 비밀을 마운트하는 것을 선호합니다. 어느 쪽이든 로그에 구성을 인쇄하지 말고 Git에 커밋된 비밀을 기록에서 제거한 후에도 교체하세요.

도커와 CI에서

# Docker (not run for this article)
docker run -e APP_PORT=8080 --env-file .env.production myapp

# GitHub Actions (not run for this article)
env:
  APP_PORT: 8080
  API_KEY: ${{ secrets.API_KEY }}

CI 플랫폼은 비밀을 암호화하여 저장하고 로그에 마스킹합니다. Dockerfile의 ENV을 사용하여 비밀 정보를 Docker 이미지에 굽지 마세요. 이미지 레이어에서 읽을 수 있는 상태로 유지되기 때문입니다. 전체 설정은 Docker Compose 튜토리얼 및 GitHub Actions CI/CD 가이드를 참조하세요.

모범 사례

• SHOP_DB_URL과 같이 접두사가 붙은 명확한 대문자 이름을 사용하십시오.
• 하나의 모듈에서 모든 구성을 읽고 거기에서 유형을 변환하고 시작 시 유효성을 검사합니다.
• 민감하지 않은 설정에만 안전한 기본값을 제공하세요.
• Git에서 .env을 유지하고 .env.example를 유지합니다.
• 민감한 값에 대해서는 프로덕션 환경에서 비밀 관리자를 사용하세요.
• 모든 변수, 해당 유형 및 예제 값을 문서화하십시오.

환경 변수 문제 디버깅

앱이 설정이 누락된 것처럼 작동하는 경우 다음 검사를 순서대로 수행하세요.

1. 올바른 위치에 설정되어 있습니까? 한 터미널 탭에서 내보낸 변수가 다른 터미널 탭이나 시스템에서 시작한 서비스에 존재하지 않습니다.
2. 앱이 다시 시작되었나요? 실행 중인 프로세스는 시작된 환경을 유지합니다. 나중에 변수를 변경해도 다시 시작할 때까지는 아무런 영향이 없습니다.
3. 이름이 정확합니까? Linux와 macOS에서는 이름이 대소문자를 구분하므로 App_Port와 APP_PORT은 다른 변수입니다. Windows에서는 이를 동일하게 취급합니다.
4. .env 파일이 이를 재정의합니까, 아니면 무시됩니까? 로더가 기존 값을 재정의하는지 여부와 실제로 어떤 파일을 읽는지 확인하십시오.
5. 흩어진 따옴표나 공백이 있습니까? 후행 공백이나 추가 따옴표와 함께 복사된 값은 찾기 어려운 방식으로 구문 분석에 실패하거나 일치하지 못할 수 있습니다.

프로세스가 실제로 수신한 내용을 확인하려면 비밀 값이 아닌 변수 이름을 인쇄하세요. Linux 및 macOS에서 printenv은 현재 셸 환경을 나열하고 PowerShell Get-ChildItem Env:에서는 동일한 작업을 수행합니다. 컨테이너 내부에서 env부터 docker exec까지 실행하면 컨테이너의 보기가 표시되는데, 이는 종종 사용자의 셸과 다릅니다.

마지막 팁: 시작할 때 기본값을 사용하는 옵션 설정을 나열하는 한 줄을 기록하십시오. 비용도 들지 않고, “왜 그러는 거지?”라는 질문에 대부분 답해 줍니다. 바로 질문.

마무리

환경 변수는 간단하지만 몇 가지 함정을 숨깁니다. 모든 것이 문자열이고 자식이 이를 상속하며 비밀이 이를 통해 유출될 수 있습니다. 이를 앱에 대한 입력으로 처리하십시오. 한 곳에서 읽고, 조기에 변환 및 검증하고, 커밋되는 파일에 대한 실제 비밀을 유지하세요.

자주 묻는 질문

계속 학습하세요