Cloudflare Workers 시크릿 설정: 소스를 설치하기 전에 쓰는 설정 규칙
Cloudflare Workers 시크릿 설정은 프로젝트를 구성하는 두 가지 방식, 즉 평문 vars와 암호화된 secrets를 구분하는 것부터 시작해요. 이 둘을 헷갈리면 키가 버전 관리 시스템에 새어나가는 가장 빠른 지름길이 됩니다.
세 줄 요약: vars는 민감하지 않은 설정을 위한 평문 또는 JSON 바인딩이며, Worker 환경에서 그대로 읽힙니다. secrets는 민감한 값을 위한 암호화된 바인딩으로, 역시 환경을 통해 읽히지만 저장소에 평문으로 남지 않아요. 로컬에서는 Cloudflare 공식 문서에 따르면 .dev.vars 또는 .env를 쓸 수 있고, .dev.vars가 존재하면 .env 값은 포함되지 않는다고 명시되어 있어요. 그러니 둘 다 쓰지 말고 하나만 선택하고, 어느 쪽이든 버전 관리에서 제외해야 합니다.
이건 생각보다 중요한 문제예요. 저는 제 소스 팩을 판매용으로 준비하는 과정에서 Cloudflare 설치 설정을 검토하는데, vars와 secrets를 뒤바꿔 쓰는 경우가 가장 흔한 실수예요. 보통은 타이핑이 빠르다는 이유로 API 키를 vars에 넣으면서 시작됩니다.
직접 실행 기록
실행 명령: npx --yes wrangler secret list --name builderlog-mailbox
환경: Darwin 25.5.0 / python 3.12.13
실행 시각: 2026-09-12T09:39:00+09:00
종료 코드: 1
[31m✘ [41;31m[[41;97mERROR[41;31m][0m [1mIt looks like you've run a Workers-specific command in a Pages project.[0m
For Pages, please run `wrangler pages secret list` instead.
🪵 Logs were written to "/Users/sso/.wrangler/logs/wrangler-2026-09-12_00-39-01_699.log"아래는 위 환경에서 실제로 실행한 결과를 그대로 붙인 것이다. 다른 환경에서는 다르게 나올 수 있다.
검증된 실행 기록
명령어: npx --yes wrangler secret list --name builderlog-mailbox
환경: Darwin 25.5.0 / python 3.12.13
실행 시각: 2026-09-12T09:39:00+09:00
종료 코드: 1
[31m✘ [41;31m[[41;97mERROR[41;31m][0m [1mIt looks like you've run a Workers-specific command in a Pages project.[0m
For Pages, please run `wrangler pages secret list` instead.
🪵 Logs were written to "/Users/sso/.wrangler/logs/wrangler-2026-09-12_00-39-01_699.log"아래 블록은 위 실행에서 캡처된 출력 그대로예요. 환경이 다르면 결과도 다를 수 있습니다.
이 구분이 왜 존재하는가
Cloudflare의 환경 변수 문서는 이 부분을 명확히 밝히고 있어요. vars는 평문 텍스트나 JSON을 담고, 민감한 값은 secrets를 써야 한다고 명시합니다. secrets는 암호화된 바인딩으로, 같은 Worker 환경 객체를 통해 접근하지만 한 번 설정하면 평문으로 다시 보여주지 않아요. 이 비대칭성이 핵심이에요 — var는 확인하기 위한 것이고, secret은 쓰고 잊기 위한 것입니다.
공개 GitHub diff에 노출됐을 때 곤란해질 값이라면, vars가 아니라 secrets에 들어가야 합니다.
이 실패 패턴은 특별한 게 아니에요. 설정 가이드가 경계를 명확히 긋지 않아서 실제 키가 [vars]에 들어간 wrangler.toml이 커밋되는 식이죠. Cloudflare 문서는 스타일을 지시하지 않아요 — 메커니즘만 설명할 뿐이고, 분류에 대한 판단은 사용자 몫입니다.
실제로 쓰는 판단표
Worker 소스를 설치하기 전에 제가 사용하는 분류 규칙이에요. 클라이언트 프로젝트든, 재판매를 위해 검토 중인 소스 팩이든 마찬가지입니다.
| 값의 종류 | 어디로 가는가 | 이유 |
|---|---|---|
| 앱 이름, 기능 플래그, 공개 설정 | vars | 평문이어도 괜찮음 — 민감하지 않고 읽을 수 있어야 함 |
| 공개 API 기본 URL | vars | 비밀이 아니고, 환경마다 다를 수 있음 |
| 데이터베이스 연결 문자열, 비공개 API 키 | secrets | Cloudflare 문서가 secrets를 써야 할 “민감한 값”으로 표시함 |
| 인증 토큰, 서명 키 | secrets | 암호화된 바인딩, 설정 후 다시 출력되지 않음 |
| 로컬 개발용 오버라이드 | .dev.vars(권장) 또는 .env, 둘 다는 안 됨 | 문서에서 .dev.vars가 우선한다고 확인됨; 존재하면 .env는 건너뜀 |
| 로컬 파일 안의 모든 값 | git에서 제외 | 로컬 시크릿 파일은 버전 관리에서 빼야 한다고 Cloudflare가 명시함 |
패턴 참고용 가짜 예시일 뿐이에요 — 실제 값으로 복사하지 마세요:
# .dev.vars (로컬 전용, 절대 커밋하지 않음)
DATABASE_URL="postgres://demo_user:demo_pass@localhost/demo_db"
SIGNING_KEY="demo_signing_key_placeholder_000"# wrangler.toml — 커밋해도 안전함
[vars]
APP_NAME = "demo-app"
FEATURE_FLAG_BETA = "false"한국 사주 소스에서 사람들이 걸리는 지점
저는 빌더로그 제품으로 등록된 한국 사주 웹앱 소스 라이선스를 판매하고 있는데, 리뷰어들이 설치 전에 secrets에 뭘 넣어야 하는지 묻곤 해요. 솔직히 말하자면, 여기서 유료 AI 키 요구사항을 지어내지는 않을 거예요 — 이 소스 팩이 실제로 요구하는 게 아니고, 그렇다고 주장하면 이 블로그가 피하려는 바로 그런 검증 불가능한 세부사항이 되니까요. 실제로 적용되는 건 위와 같은 일반적인 구분이에요. 설치 가이드가 민감하다고 명시한 설정(데이터베이스 자격 증명, 인증 토큰이 있다면)은 secrets로, 그 외 평문 설정(앱 이름이나 로케일 기본값 같은)은 vars로 가면 됩니다. 현재 설치 요구사항의 출처는 제품 페이지예요 — 제 것이든 다른 누구의 것이든 요약을 믿기보다 직접 확인하세요.
설정 체크리스트는 소스 팩이 무엇을 요구하는지 추측할 필요가 없어야 해요 — 설치 가이드가 이미 알려주니까요.
실패와 한계
이건 실제 테스트된 설치 로그가 아니에요. 오늘 새로운 Worker 배포를 실행한 적이 없고, 측정된 전후 비교를 주장하는 것도 아닙니다 — 그건 지어낸 실험이 될 테고, 이 글의 편집 원칙은 비용, 사용자, 결과를 지어내지 않는다는 점을 명확히 하고 있어요. 제가 제공할 수 있는 건 Cloudflare 공식 secrets 및 environment-variables 문서(둘 다 2026년 9월 9일 기준 검토됨)에 근거한 분류 방법이에요.
가장 중요한 한계는 이거예요: 실제 런타임과 프로젝트 구성이 여기서 설명한 것과 다를 수 있다는 점이요. 프레임워크별 래퍼, 오래된 Wrangler 버전, 또는 시크릿을 다르게 주입하는 CI 파이프라인 모두 메커니즘을 바꿀 수 있어요. 실제로 배포하기 전에 최신 공식 문서를 확인하세요.
Worker 설치 전 재사용 가능한 체크리스트
- 프로젝트에 필요한 모든 설정 값을 나열한다.
- 이 값이 공개 diff에 노출되면 위험한가? 그렇다면 → secrets로.
- 디버깅 중에 사람이 읽을 필요가 있는가? 그렇고 민감하지 않다면 → vars로.
- 로컬 파일은
.dev.vars또는.env중 하나만 선택한다. 둘 다 있으면.dev.vars가 우선한다. - 첫 커밋 전에(후가 아니라) 로컬 파일이
.gitignore에 있는지 확인한다. - 문서화되지 않은 AI 키나 데이터베이스 요구사항을 가정하지 말고, 설치 가이드 자체의 “필수” 값 목록을 다시 확인한다.
관련 빌드 로그
민감하지 않은 평문 설정은 vars에, 민감한 값은 secrets에 넣으세요. 로컬 오버라이드는 파일 하나에만 두고(.dev.vars가 .env보다 우선), 절대 버전 관리에 포함하지 마세요.
근거와 범위
| 근거 | 뒷받침하는 내용 | 한계 |
|---|---|---|
| Google 자동완성, 2026-09-16 기준 검토 | 정확히 Cloudflare Workers secrets 쿼리가 현재 제안 화면에 나타남 | 검색어 노출 신호일 뿐, 검색량·순위·구매 의도·성과가 아님 |
| 가상의 편집용 예시 | 여기서 다룬 필드 또는 판단 절차를 보여줌 | 측정된 실제 운영 결과가 아님 |
2026-09-16에 가상의 편집 조건에서 검토됨. 개인 데이터, 외부 전송, 실제 운영 결과는 사용되지 않았음.