배포 후 환경변수가 적용 안 될 때

배포 후 환경변수를 바꿨는데 앱이 여전히 옛날 값을 쓰고 있다. 또는 롤백했는데도 예전 버전의 동작이 나타난다. 이럴 땐 앱 재시작, 캐시, 또는 빌드 시점의 설정 때문이다.

첫 번째: 환경변수가 런타임에 읽혀야 하는지, 빌드 시점에 읽혀야 하는지 확인한다

// Next.js 예제

// 빌드 시점에 고정됨 (클라이언트 사이드)
const API_URL = process.env.NEXT_PUBLIC_API_URL;

// 런타임에 읽힘 (서버 사이드)
export async function getServerSideProps() {
  const dbUrl = process.env.DATABASE_URL; // 런타임에 읽음
  return { props: {} };
}

NEXT_PUBLIC_ 접두사가 있으면 빌드 시점에 번들에 고정된다. 따라서 배포 후 환경변수를 바꿔도 클라이언트에선 반영이 안 된다.

두 번째: 앱을 재시작했는지 확인한다

# Docker Compose
docker-compose down
docker-compose up -d

# 또는 Kubernetes
kubectl rollout restart deployment/my-app

# Node.js 직접 실행
# PM2 사용 시
pm2 restart app-name
env pm2 reload

환경변수는 프로세스 시작 시점에 메모리에 로드된다. 프로세스를 재시작하지 않으면 기존 값을 계속 쓴다.

세 번째: 빌드 캐시를 확인한다

# Next.js의 경우
rm -rf .next
npm run build

# 또는 Docker
docker build --no-cache -t my-app:latest .

빌드 과정에서 환경변수를 읽어서 번들에 넣는 경우가 있다. 이전 빌드의 캐시가 남아있으면 변경이 반영 안 될 수 있다.

네 번째: 배포 후 실제 값을 확인한다

// 엔드포인트를 추가해서 현재 환경변수 값을 본다 (주의: 프로덕션에선 제거)
app.get('/api/config', (req, res) => {
  res.json({
    api_url: process.env.API_URL,
    node_env: process.env.NODE_ENV,
    // 민감한 정보는 빼기
  });
});

또는 앱 로그를 본다.

# Docker logs
docker logs my-app 2>&1 | grep -i 'api_url\|config'

# 또는 앱 시작 시 환경변수를 출력하게 한다
console.log('Starting with:', {
  API_URL: process.env.API_URL,
  DATABASE_URL: process.env.DATABASE_URL ? '***' : 'undefined'
});

다섯 번째: 이전 이미지가 실행 중인지 확인한다

# Docker Compose의 경우
docker-compose ps

# 컨테이너 ID로 이미지 확인
docker inspect <container-id> | grep -i image

# 배포할 때 이미지 태그가 제대로 업데이트되었는지
docker images | grep my-app

K8s나 Dokploy에서 이전 이미지 버전이 계속 실행 중이면, 아무리 새로 배포해도 적용이 안 된다.

체크리스트

1. 환경변수가 빌드 시점에 고정되는지, 런타임에 읽혀야 하는지 확인한다
2. 앱을 완전히 재시작한다 (프로세스 kill + restart)
3. 빌드 캐시를 지우고 재빌드한다
4. 배포 후 실행 중인 컨테이너/프로세스의 이미지 버전을 확인한다
5. 앱 로그에서 실제 환경변수 값을 본다
6. 필요하면 /api/config 같은 엔드포인트로 현재 값을 확인한다

환경변수는 대부분 프로세스 시작 시점에 로드되므로, 배포 후엔 반드시 앱을 재시작해야 한다.