지니제스트 테크 블로그 배너
지니제스트Tech Archive
Cloudflare8분 소요

Cloudflare Workers 환경 변수가 undefined일 때 확인할 것

•
지지니제스트

로컬 wrangler dev에서는 되는데 배포 후 env 값이 undefined인 이유를 .dev.vars와 .env 규칙, wrangler secret put, 환경별 vars 비상속, process.env 조건, 변수 개수 제한으로 나눠 확인하는 방법을 정리했습니다.

Cloudflare Workers 환경 변수가 undefined일 때 확인할 것

Worker 코드에서 env.API_KEY가 undefined로 나오는 원인은 거의 항상 "값이 읽히는 위치"가 환경마다 다르다는 데 있습니다. 로컬 wrangler dev는 .dev.vars나 .env를 읽고, 배포된 Worker는 설정 파일의 vars와 따로 올린 시크릿만 읽습니다. 로컬에서만 되고 배포 후에 깨지는 경우는 대부분 이 차이입니다.

아래 표로 어느 환경이 어디서 값을 읽는지 먼저 정리하고, 그다음 증상별로 확인 순서를 따라갑니다.

wrangler dev, wrangler deploy, --env 배포 각각이 환경 변수를 읽는 위치와 주의점
환경별로 변수를 읽는 위치


먼저 어느 환경에서 undefined인지 구분하기

값이 없다는 증상은 비슷해도 확인할 곳이 다릅니다.

  • 로컬 wrangler dev에서만 undefined: .dev.vars, .env 파일 이름과 위치, 둘을 같이 쓰고 있는지 확인합니다.
  • 배포 후에만 undefined: 로컬 파일은 배포되지 않습니다. vars에 넣었는지, wrangler secret put을 실행했는지 확인합니다.
  • --env production으로 배포했을 때만 undefined: 환경 섹션에 변수를 다시 적었는지 확인합니다.
  • process.env.X만 undefined: nodejs_compat 플래그와 호환성 날짜를 확인합니다.

배포된 Worker에 어떤 시크릿 이름이 올라가 있는지는 다음 명령으로 볼 수 있습니다. 값은 표시되지 않고 이름만 나옵니다.

BASH
wrangler secret list

vars에는 일반 값만, 민감한 값은 시크릿으로

설정 파일의 vars는 평문으로 저장되고 Git에 올라가는 파일에 적힙니다. API 키, 토큰은 여기에 넣지 말아야 합니다. 신규 프로젝트에서 wrangler.jsonc를 쓰면 같은 설정을 JSON으로 적고, 이 글의 예시는 wrangler.toml 기준입니다.

TOML
name = "my-worker"
main = "src/index.ts"
compatibility_date = "2025-04-01"

[vars]
API_BASE_URL = "https://api.example.com/v1"
CONFIG_JSON = '{"key": "value", "enabled": true}'

코드에서는 fetch 핸들러의 두 번째 인자 env로 읽습니다.

JAVASCRIPT
export default {
  async fetch(request, env) {
    const base = env.API_BASE_URL;
    const config = JSON.parse(env.CONFIG_JSON); // JSON도 문자열로 들어옵니다
    return new Response(`${base} ${config.key}`);
  },
};

모듈 최상위(핸들러 밖)에서 쓰려면 import { env } from "cloudflare:workers"로 가져옵니다.


시크릿은 따로 올려야 한다

시크릿은 wrangler secret put으로 올리고, 올린 뒤에는 값을 다시 볼 수 없습니다. 값을 바꾸려면 같은 이름으로 다시 put 하면 덮어써집니다.

BASH
wrangler secret put MY_API_KEY
wrangler secret list
wrangler secret delete MY_API_KEY

코드에서는 일반 변수와 똑같이 env.MY_API_KEY로 읽습니다. 없을 때 바로 알 수 있도록 방어 코드를 두면 원인을 찾기 쉽습니다.

JAVASCRIPT
if (!env.MY_API_KEY) {
  return new Response("MY_API_KEY가 설정되지 않았습니다", { status: 500 });
}

여러 환경을 쓰면 시크릿도 환경마다 따로 올려야 합니다.

BASH
wrangler secret put MY_API_KEY --env production

로컬 개발은 .dev.vars 또는 .env 중 하나만

로컬에서 wrangler dev를 실행하면 프로젝트 루트의 .dev.vars나 .env를 읽습니다. 공식 문서는 둘 중 하나만 쓰라고 안내하고, .dev.vars가 있으면 .env는 무시됩니다.

INI
# .dev.vars (또는 .env)
API_KEY=dev_api_key_12345

환경별 파일 규칙은 이렇습니다.

  • .dev.vars.<환경>이 있으면 그 파일만 읽고 일반 .dev.vars는 읽지 않습니다.
  • .env는 .env, .env.<환경>, .env.local, .env.<환경>.local 순으로 겹쳐 읽고 뒤쪽이 우선합니다.
  • .env 읽기를 끄려면 CLOUDFLARE_LOAD_DEV_VARS_FROM_DOT_ENV=false를 지정합니다.

wrangler secret put으로 올린 시크릿은 기본 로컬 실행에서 읽히지 않는 것이 보통입니다. 로컬에서도 같은 값을 쓰려면 .dev.vars에 따로 적습니다. 두 파일은 .gitignore에 반드시 넣어야 합니다.

INI
.env
.env.*
.dev.vars
.dev.vars.*

process.env로 읽을 때

Workers에서 process.env는 기본으로 비어 있습니다. nodejs_compat 플래그를 켜야 하고, 호환성 날짜가 2025-04-01 이후이면 nodejs_compat_populate_process_env가 자동으로 적용되어 vars와 시크릿이 process.env에 채워집니다.

TOML
compatibility_date = "2025-04-01"
compatibility_flags = ["nodejs_compat"]

날짜가 더 오래됐다면 nodejs_compat_populate_process_env 플래그를 직접 추가하거나 env 객체를 쓰세요.


환경(--env)을 나눌 때

vars는 환경에 상속되지 않습니다. 공식 문서도 "vars is a non-inheritable key"라고 설명하는 부분이라, 최상위에 적은 값은 [env.production] 안에서 보이지 않습니다. 환경마다 다시 적어야 합니다.

TOML
[vars]
LEVEL = "default"

[env.production]
name = "my-worker-prod"
[env.production.vars]
LEVEL = "production"
API_BASE_URL = "https://api.example.com/v1"
BASH
wrangler deploy --env production

--env를 빼고 배포하면 최상위 설정이 올라가므로, 어느 이름의 Worker에 배포되는지도 같이 확인하세요.


대시보드와 설정 파일을 같이 쓸 때

대시보드의 Settings > Variables and Secrets에서 값을 직접 추가했는데, 이후 wrangler deploy로 설정 파일 기준 배포를 하면 대시보드에서 만든 평문 변수가 설정 파일의 vars로 덮여 사라질 수 있습니다. 한쪽을 기준으로 정하고 그쪽에서만 관리하는 편이 안전합니다. 설정 파일을 기준으로 삼는다면 대시보드에서는 시크릿만 건드리세요.

변수 개수에도 한도가 있습니다. 공식 제한 문서 기준으로 변수와 시크릿을 합쳐 Free 플랜은 Worker당 64개, Paid 플랜은 128개이고, 변수 하나는 5KB까지입니다. 큰 설정 데이터는 변수 대신 KV, R2, D1 바인딩에 두세요.


자주 묻는 질문

로컬에서는 되는데 배포하면 undefined입니다

.dev.vars와 .env는 배포되지 않습니다. 일반 값은 vars에, 민감한 값은 wrangler secret put으로 올렸는지 확인하세요.

시크릿 값을 확인할 수 없는데 정상인가요

정상입니다. wrangler secret list는 이름만 보여 주고, 값은 다시 조회할 수 없습니다. 값을 잊었다면 같은 이름으로 새 값을 올립니다.

환경을 나눴더니 production에서만 값이 없습니다

[env.production.vars]에 변수를 다시 적었는지, 시크릿을 --env production으로 올렸는지 확인하세요. vars는 환경에 상속되지 않습니다.

함께 읽으면 좋은 글: Astro와 Cloudflare D1 연동, 바뀐 바인딩 접근법까지


참고 자료