서버 없이 코드가 돌아간다고? npx, wrangler, Cloudflare Worker 이해하기

정적 사이트 하나를 Cloudflare에 배포하려다가 "디플로이 커맨드"라는 말을 만났다. 기본값은 npx wrangler deploy라고 하는데, 여기 나오는 단어 하나하나가 낯설었다. npx는 뭐고, wrangler는 뭐고, 이걸 왜 실행해야 하는지. 이번 글에서는 그 과정에서 정리한 개념들을 순서대로 풀어본다.

 

Node.js: 이 도구들이 돌아가는 무대

npx와 wrangler를 이해하려면 그 둘이 딛고 서 있는 Node.js부터 짚어야 한다. Node.js는 원래 브라우저 안에서만 돌아가던 JavaScript를, 브라우저 밖(내 컴퓨터나 서버)에서도 실행할 수 있게 만든 실행 환경(runtime)이다. 그 덕분에 JS로 서버를 만들거나, wrangler 같은 커맨드라인 도구를 만드는 것도 가능해졌다. npm과 npx는 Node.js를 설치하면 함께 딸려오는 부속 도구다.

 

 

(왜 애초에 브라우저용 언어를 굳이 서버에서까지 돌리려 했는지는 파다 보니 이야기가 길어져서, 별도 글로 따로 정리했다.)

https://dwnc.tistory.com/166

Node.js 굳이 브라우저용 언어를 서버에서 돌릴 필요가 있었을까

 

 

npx: 도구를 설치하지 않고 빌려 쓰는 실행기

npx는 이 Node.js 생태계에 딸려오는 실행 도구다. 원래 npm(Node Package Manager)은 '패키지를 컴퓨터에 설치'하는 도구인데, npx는 "패키지를 굳이 내 컴퓨터에 영구 설치하지 않고 한 번만 실행하고 싶을 때" 쓴다. npx wrangler deploy라고 치면, 컴퓨터에 wrangler가 깔려 있지 않아도 npx가 알아서 최신 버전을 그때그때 받아와 실행해준다(단, 프로젝트에 이미 설치돼 있으면 그걸 그대로 쓴다). "도구를 설치하지 않고 잠깐 빌려 쓴다"고 생각하면 이해가 쉽다.

wrangler: Cloudflare용 배포 리모컨

wrangler는 Cloudflare가 만든 커맨드라인 도구(CLI)다. Node.js 환경에서 만들어졌고 npm 레지스트리(Node.js 용 패키지들 저장해두는 곳)에 패키지로 올라와 있어서, 실행하려면 Node가 설치돼 있어야 한다. wrangler는 Cloudflare Workers나 Pages 같은 서비스에 코드를 배포하거나, 로컬에서 미리 실행해보거나, 설정을 관리할 때 쓴다. git에 commit, push, pull 같은 하위 명령어가 있듯, wrangler에도 dev(로컬 미리보기), deploy(실제 배포), tail(로그 확인) 같은 하위 명령어들이 있다. npx wrangler deploy는 결국 "wrangler라는 도구를 Node의 패키지 생태계를 통해 빌려와서, 그 도구의 deploy 명령으로 지금 이 폴더 내용을 Cloudflare에 배포(업로드)해라"라는 뜻인 셈이다. Cloudflare가 wrangler를 영구 설치 없이 npx로 부르는 기본값을 쓰는 이유도, 프로젝트 내에 설치되어있는지와 상관없이 항상 동작하게 하기 위해서다.

Cloudflare Worker : "서버 없이 코드를 실행한다?"

Cloudflare Worker는 흔히 "서버 없이 코드를 실행해주는 서비스"라고 소개된다. 이 말을 들으면 자연스럽게 의문이 든다. 그럼 원래는 서버가 있어야 코드가 실행된다는 건가? 그 코드는 뭘 말하는 거고, 어떤 서버에서 실행된다는 걸까?

웹사이트를 이루는 코드는 크게 두 종류로 나뉜다.

하나는 프론트엔드 코드(HTML, CSS, JS)다. 이건 사용자의 브라우저에서 실행된다. 버튼을 눌렀을 때 색이 바뀌는 것 같은 동작은 전부 사용자 컴퓨터 안에서 처리되기 때문에, 회사가 해당 파일을 "실행해주는" 별도의 서버를 운영할 필요가 없다. 앞서 말한 "정적 자산(static assets)"이 바로 이런 종류다. HTML 파일을 어딘가에 올려두면, 접속할 때마다 그 파일을 내려받아 "각자의 브라우저에서 실행"하는 구조다.

다른 하나는 백엔드 코드(서버 코드)다. 이건 브라우저가 아니라 회사가 관리하는 컴퓨터(서버)에서 실행돼야 하는 코드다. 로그인할 때 비밀번호가 맞는지 데이터베이스에서 확인하는 로직, 예약 가능한 재고를 조회하는 로직, 결제를 처리하는 로직 같은 것들이 여기 속한다. 이런 코드를 그대로 브라우저에 넘기면 비밀번호 검증 로직이나 데이터베이스 접속 정보가 그대로 노출되기 때문에 보안상 위험하다. 그래서 사용자 눈에 보이지 않는 어딘가의 서버에서 실행하고, 브라우저는 그 서버에 결과만 물어보는 방식으로 동작한다.

 

전통적인 방식은 이 백엔드 코드를 돌리기 위해 회사가 서버(가상 컴퓨터)를 하나 빌리거나 사서 24시간 켜두는 것이었다. 요청이 오든 안 오든 서버는 계속 켜져 있고, 회사는 그 시간만큼 요금을 낸다.

 

서버리스(serverless)는 여기서 조금 다르다. 이름 때문에 "서버가 아예 없다"고 오해하기 쉽지만, 사실 서버는 있다. 다만 그 서버를 직접 관리하지 않고, Cloudflare나 AWS 같은 회사가 이미 운영 중인 데이터센터 위에서, 요청이 들어올 때만 내 코드 조각을 잠깐 실행시켜주는 방식이다. 평소엔 아무것도 돌고 있지 않다가, 누군가 접속하는 순간 코드를 실행해 결과를 돌려준다. 그래서 서버를 직접 관리할 필요도 없고, 요청이 없을 때는 비용도 들지 않는다.

 

Cloudflare Worker가 바로 이 서버리스 코드 실행 서비스다. Cloudflare가 전 세계에 깔아둔 데이터센터 위에서, 올려둔 JS 코드 조각을 요청이 올 때마다 실행해준다. 원래는 이런 백엔드 로직 실행이 Worker의 본래 목적이었는데, 나중에 정적 파일 서빙 기능도 함께 지원하도록 확장됐다. 

wrangler.jsonc: 무엇을 어떻게 배포할지 정의하는 설정 파일

Worker가 정적 HTML을 서빙하게 하려면, "이 폴더가 정적 자산이다"라는 걸 Worker에게 알려줘야 한다. 이걸 정의하는 게 저장소에 두는 wrangler.jsonc(또는 wrangler.toml) 설정 파일이다. 대략 이런 형태다.

{
  "name": "rent-a-car",
  "compatibility_date": "2026-07-13",
  "assets": { "directory": "./public" }
}

여기서 핵심은 "assets": { "directory": "./public" } 부분이다. "정적 파일들은 public 폴더 안에 있으니 그 폴더 내용을 웹사이트로 서빙해라"라고 wrangler에게 알려주는 역할을 한다.

자산 디렉터리를 루트로 잡으면 안 되는 이유

여기서 주의할 점이 하나 있다. 이 디렉터리를 저장소 루트(./)로 잡아버리면 .git 폴더(커밋 기록 전체), README, 엑셀 모델 파일, 이전 버전 파일들까지 전부 "정적 자산"으로 취급되어 인터넷에 그대로 공개된다. 대외비 문서가 있다면 노출 위험이 생기는 셈이다. 그래서 배포할 파일만 public/ 같은 별도 폴더에 모아두고, 그 폴더만 가리키도록 설정하는 게 안전하다.

Worker vs Pages -> Workers & Pages

순수하게 정적 HTML만 서빙하는 사이트라면 Cloudflare Pages를 쓰는 방법도 있다. 아니, 정확하게는 그런 방법도 있었다. Pages는 wrangler.jsonc 같은 설정 없이도 폴더를 연결하기만 하면 index.html을 자동으로 서빙해준다. 그래서 "디플로이 커맨드"라는 개념 자체가 필요 없어진다. 그런데, 그건 예전 문서에 나오는 이야기고, Page 를 Worker 쪽으로 통합중이라고 한다. 표기도 Workers & Pages 라고 하나의 기능인 것처럼 하고 있고, 생성할 때 그 둘을 따로 구분하지 않고 create application (create worker) 라고 부른다.

 

정리

• Node.js: 브라우저 밖에서 JS를 실행할 수 있게 해주는 실행 환경. npx, npm, wrangler 모두 이 위에서 돌아감
• 프로젝트: package.json이 있는 폴더 단위. 그 폴더의 node_modules에 패키지가 개별 설치됨
• npx: 도구를 설치하지 않고 한 번 빌려서 실행하는 명령
• wrangler: Cloudflare 배포/관리용 커맨드라인 도구, deploy는 그 하위 명령어 중 하나
• Cloudflare Worker: 서버리스 방식으로 코드(원래는 백엔드 로직)를 실행해주는 서비스, 이후 정적 파일 서빙 기능도 추가됨
• wrangler.jsonc: Worker에게 "무엇을 어디서 서빙할지" 알려주는 설정 파일
• 자산 디렉터리는 반드시 배포용 파일만 모아둔 폴더로 좁혀야 함 (루트로 잡으면 비공개 파일까지 노출