Cloudflare Workers에 페이지를 배포하는 방법

완성된 페이지 폴더는 있지만 링크는 없습니다. Cloudflare Workers에 배포하고, 그 절차는 Claude Code에 맡기겠습니다. 게시와 업데이트를 짧은 요청으로 줄여주는 스킬을 만들 것입니다.

1. 정적 사이트용 Cloudflare Workers란

Workers라는 이름은 "서버에서 실행되는 프로그램"처럼 들리고, 틀린 말은 아닙니다. 하지만 전부도 아닙니다. 워커에는 파일 폴더를 붙일 수 있고, 그러면 서버는 일반 호스팅처럼 그 파일들을 그대로 내려줄 뿐입니다. 코드는 한 줄도 작성할 필요가 없습니다.

HTML, CSS, 이미지로 만든 페이지라면 이런 모드면 충분합니다. 문서에서 이 폴더는 정적 에셋(static assets)이라고 불리며, 프로젝트 설정에서는 경로를 적는 필드 하나만 차지합니다.

Cloudflare는 자체 서버 네트워크를 통해 파일을 제공하고 방문자에게 더 가까운 위치에서 캐시합니다.

2. 비용은 얼마입니까?

정적 파일에 대한 요청은 무료이며 수량 제한이 없습니다. 이것은 요금제 조건일 뿐, 방문 통계가 집계되지 않는다는 약속은 아닙니다.

그렇다면 자주 듣는 숫자, 하루 요청 100,000건은 어디서 나온 걸까요? 이것은 Worker 스크립트, 즉 서버에서 실행되는 프로그램 호출에 대한 제한입니다. 폴더만 연결된 페이지에는 스크립트가 없으므로 이 카운터에 포함되지 않습니다.

다이어그램의 위쪽 경로는 우리 페이지에 해당합니다. 서버 프로그램을 호출하지 않고 파일이 전달됩니다. 아래쪽은 나중에 Worker 스크립트를 추가할 때 필요합니다.

무료 요금제에도 제한은 있지만, 다른 부분, 즉 여러분이 올리는 파일의 크기에 관한 것입니다:

이미지가 열 장 남짓한 페이지라면 보통 이 제한으로 충분합니다. 규모가 큰 프로젝트라면 시작 전에Cloudflare의 최신 조건을 확인하세요. 제한이 변경될 수 있습니다. 참고로 파일당 25 MB는 첫 동영상을 올리기 전까지만 넉넉해 보입니다.

3. 계정

cloudflare.com가입 절차는 평범합니다. 이메일과 비밀번호를 입력하면 확인 메일이 옵니다. 무료 요금제에는 카드가 필요하지 않습니다. 자신의 도메인을 추가할 필요도 없습니다. 서비스가 권하긴 하지만, 그 제안은 제품의 다른 절반, 즉 기존 웹사이트를 보호하고 빠르게 하는 쪽에 해당합니다.

로그인한 뒤 필요한 섹션의 이름은 "Workers & Pages"인데, 눈에 잘 띄는 곳에 있지 않습니다. 왼쪽 메뉴에서 먼저 Build 그룹, 그 안에 Compute, 그리고 그 안에 "Workers & Pages"가 있습니다. 대시보드는 시간이 지나며 구성이 바뀌므로 이 경로에 섹션이 없으면 이름으로 검색하세요. 왼쪽 상단의 검색은 Ctrl + K로 열립니다. 이름의 두 단어는 두 개의 Cloudflare 제품입니다. 필요한 것은 앞쪽 절반인 Workers이고, 따로 무언가를 고르지 않아도 그쪽으로 들어가게 됩니다.

첫 배포 때 한 가지가 더 나옵니다. Cloudflare가 계정용 서브도메인 이름을 정하라고 요청합니다. 여러분의 모든 프로젝트가 이 서브도메인 아래에 놓이고, 주소는 프로젝트 이름과 여러분의 서브도메인, 이렇게 두 부분으로 이루어집니다:

my-landing.example-account.workers.dev
|          |               |
|          |               Cloudflare 공통 도메인
|          계정의 서브도메인
프로젝트 이름

이 이름은 나중에 바꾸기 번거로우니, 처음 떠오른 이름을 그대로 적지는 않는 편이 좋습니다.

4. 첫 번째 배포

먼저 대시보드에서 게시가 어떻게 이루어지는지 간단히 살펴보겠습니다. 서비스와 가볍게 친해지는 선택 단계입니다. 에이전트로 배포를 바로 설정하고 주소 하나를 계속 유지하고 싶다면 아래 준비 단계로 넘어가세요.

landing/          <- 이 폴더를 전달합니다
  index.html      <- 메인 페이지, 이 이름이어야 합니다
  wrangler.jsonc  <- 에이전트가 첫 배포 전에 생성합니다
  style.css
  img/
    hero.png

게시 전에 선택한 폴더의 내용을 확인하세요. 그 안의 파일은 모두 공개됩니다. 보여 줄 생각이 없던 개인 파일과 초안은 빼 두세요.

대시보드에서 수동으로

프로젝트 섹션에는 새 프로젝트를 시작하는 버튼이 있습니다. 다음으로 파일을 전달하라는 메시지가 표시됩니다. 한 파일을 선택하거나 전체 폴더를 선택할 수 있습니다. 업로드하고 확인하면 Cloudflare가 파일을 자기 쪽에 올려 두고 링크를 돌려줍니다. 버튼 이름과 화면 순서는 글이 나오는 속도보다 더 자주 바뀌므로, 버튼 이름보다 흐름을 기억하세요: 프로젝트 만들기, 파일 전달, 주소 받기.

받은 주소 https://…workers.dev를 열고 페이지와 이미지를 확인하세요. 같은 컴퓨터에서 확인해도 됩니다. 휴대폰은 다른 기기에서도 열리는지, 모바일 화면은 어떤지 추가로 확인할 때 유용합니다.

대시보드에서 게시하면 로컬 구성 파일이 생기지 않습니다. 이 글 예제의 스킬은 폴더를 이런 프로젝트와 알아서 연결하지 않습니다. 구성 파일이 없으면 새 이름을 만들고 두 번째 주소가 생깁니다. Cloudflare에서는 Wrangler로 기존 Worker를 업데이트할 수 있지만, 그러려면 해당 Worker 이름에 맞춘 구성 파일을 따로 설정해야 합니다.

에이전트가 이 일을 하게 하려면

이후 게시를 위해 스킬을 설정하겠습니다. 준비는 여러분 컴퓨터에서 한 번만 하면 됩니다.

필요한 프로그램은 많지 않습니다. 계정은 이미 있고, 여기에 Node.js가 필요합니다. node -v 명령으로 확인하고, 명령을 찾을 수 없다고 나오면 먼저 설치해야 합니다. wrangler 자체는 설치하지 않아도 됩니다. npx가 필요한 시점에 최신 버전을 알아서 내려받습니다.

다이어그램의 두 번째 단계는 로그인입니다. 다른 무엇보다 먼저, 지금 바로 끝내 두는 것이 좋습니다:

npx wrangler login    # 브라우저가 열리고, 거기에 승인 버튼이 있습니다

이 명령은 터미널에서 실행하세요. 이 단계를 건너뛰면 첫 실행에서 절차 전체가 여기서 막히고, 스킬이 고장 난 것처럼 보입니다. 실제로는 스킬과 전혀 상관이 없는데도요. 제대로 됐는지는 npx wrangler whoami 명령으로 확인할 수 있습니다. 어떤 계정으로 로그인했는지 보여 줍니다.

이 경로라면 브라우저 로그인만으로 충분합니다. API 토큰은 글 끝의 선택 섹션에서 다룹니다.

다이어그램의 세 번째 단계인 npx wrangler deploy는 에이전트가 페이지 폴더에서 실행합니다. 그 전에 구성 파일을 준비하고 게시하는 규칙부터 알려 주겠습니다.

5. 배포용 자체 스킬

페이지가 하나일 때는 채팅으로 부탁해도 충분합니다. 하지만 두 번째, 세 번째, 열 번째 페이지가 생기면 매번 에이전트에게 같은 것을 설명해야 합니다. 어떤 폴더를 쓸지, 프로젝트 이름은 어떻게 지을지, 설정 파일은 어떻게 할지. 세 번째쯤 되면 지겨워집니다.

스킬이 할 수 있어야 할 것

다섯 단계이고, 모두 구색을 맞추려고 넣은 것이 아니라 각자 구체적인 문제를 해결합니다:

1. 지정된 폴더를 받아 그 루트에 index.html이 있는지 확인합니다. 가장 흔한 실수를 배포 후가 아니라 배포 전에 잡아내는 간단한 확인입니다.
2. 프로젝트 이름을 정합니다. 매번 묻지 않고 폴더 이름에서 만들어 냅니다.
3. 폴더 안, index.html 옆에 wrangler.jsonc 파일이 있는지 봅니다. 없으면 만들고, 있으면 거기서 이름을 가져오되 파일 내용은 아무것도 고쳐 쓰지 않습니다.
4. 이 폴더에서 배포를 실행하되, 실행 전에 명령을 보여 줍니다.
5. 공개 주소를 돌려주고, 그 주소에서 페이지와 이미지를 확인하라고 알려 줍니다.

프로젝트 이름은 폴더에서 나옵니다

이것이 절차 전체에서 가장 중요한 결정이고, 바로 이 부분을 에이전트의 즉흥에 맡기면 안 됩니다. 규칙으로 정해 두지 않으면 에이전트가 이름을 직접 지어내고, 다음번에는 다른 이름을 지어냅니다. 결국 주소가 다른 두 번째 프로젝트가 생기고, 첫 번째는 그대로 방치됩니다.

규칙은 간단합니다. 폴더 이름이 곧 프로젝트 이름입니다. 워커 이름에는 소문자 라틴 문자, 숫자, 하이픈만 쓸 수 있으므로 나머지(마침표, 공백, 밑줄)는 모두 하이픈으로 바꾸고, 무작위 문자 네 개로 된 짧은 접미사를 붙입니다:

landing/                 ->  landing-42c2
my.first.page/           ->  my-first-page-8e10
portfolio-2026/          ->  portfolio-2026-b7a3

접미사는 서로 다른 프로젝트에 있는 같은 이름의 폴더 두 개가 한 주소를 두고 겹치지 않게 하려고 붙입니다. 접미사는 설정 파일을 만들 때 한 번만 생성하고, 반드시 에이전트가 머릿속으로 지어내지 않고 명령으로 만듭니다. 그렇지 않으면 에이전트가 예제의 접미사를 그대로 가져다 쓰고, 같은 글을 읽은 모든 사람의 접미사가 똑같아집니다. 그 이후로 접미사는 항상 구성 파일에서 읽습니다. 스킬이 무언가를 쓰기 전에 기존 구성 파일부터 확인하는 이유가 바로 이것입니다.

에이전트가 설정 파일을 작성합니다

에이전트는 wrangler.jsonc에 프로젝트 이름과 게시 설정을 적어 둡니다. 그래야 터미널에서 질문 없이 배포를 실행할 수 있습니다. 구성 파일은 index.html 옆에 있으므로 그 안의 파일 경로는 마침표, 즉 "바로 이 폴더"입니다:

{
  "name": "landing-42c2",
  "compatibility_date": "2026-09-07",
  "assets": { "directory": "." }
}

compatibility_date 필드는 지정한 날짜 기준의 플랫폼 동작을 선택합니다. 새 구성 파일에는 Cloudflare 문서의 권장대로 에이전트가 오늘 날짜를 넣고, 다시 게시할 때는 기존 날짜를 유지합니다.

구성 파일을 한 단계 위, 폴더 옆에 두는 것은 좋지 않습니다. 파일 이름이 고정되어 있어 한 디렉터리에 이런 파일은 하나만 둘 수 있고, 두 번째 폴더는 첫 번째 폴더의 구성을 덮어쓰거나 그 이름으로 배포되어 버립니다. 폴더 안에 두면 프로젝트마다 독립적이고, 배포도 그 폴더에서 바로 실행됩니다.

이 배치에는 부작용이 하나 있습니다. 구성 파일이 페이지와 같은 폴더에 있으니 함께 호스팅에 올라가고, 링크로도 열립니다. 비밀 정보는 없습니다(이름, 날짜, 마침표뿐). 그래도 신경 쓰인다면 옆에 .assetsignore 파일을 두고, 올리지 않을 파일을 거기에 적으면 됩니다.

작업 지시에 명시해야 할 규칙이 세 가지 있습니다. 적어 두지 않으면 에이전트가 짐작하지 못합니다:

• 파일이 없으면 만들고, 무엇을 적었는지 보여 준다;
• 파일이 있으면 오늘 날짜가 다르더라도 이름과 날짜는 그대로 둔다;
• 내용이 실제로 바뀔 때만 파일을 다시 쓴다.

곁에 두면 좋은 네 가지 요청

첫 번째는 스킬을 만드는 작업 지시 그 자체입니다. 절차 전체를 설명하는 건 이번 한 번뿐이라 나머지보다 깁니다:

Cloudflare Workers에 정적 페이지를 배포하는 skill을 만들어 주세요.
이 프로젝트의 .claude/skills/에 두세요.
마지막에 생성한 SKILL.md의 경로와 스킬을 명시적으로 호출하는 방법을 보여 주세요.

먼저 Workers와 static assets에 관한 Cloudflare 최신 문서를 읽으세요.
명령과 구성 필드가 바뀌었을 수 있습니다.
아래 설명 중 문서와 어긋나는 부분이 있으면 저에게 말해 주고,
말없이 고쳐 쓰지 마세요.

스킬 설명에는 스킬이 실행되어야 하는 문구를 적어 주세요.
최소한 "폴더를 배포해 줘", "다시 배포해 줘", "Cloudflare에 배포해 줘".

절차: 폴더를 받아 루트에 index.html이 있는지 확인한다.
프로젝트 이름은 이 폴더 이름에서 만든다. 이름에는 소문자 라틴 문자,
숫자, 하이픈만 남기고, 나머지(공백, 밑줄, 대문자,
키릴 문자)는 하이픈으로 바꾼다.
끝에 하이픈으로 이어서 4자리 접미사를 붙인다.
접미사는 지어내지 않고 다음 명령으로 얻는다:
node -e "console.log(crypto.randomUUID().slice(0,4))"
구성 파일 wrangler.jsonc는 게시할 폴더 안, index.html 옆에 있고,
그 안의 assets.directory 값은 "."이다.
구성 파일이 없으면 만든다: name, compatibility_date,
assets.directory. 새 compatibility_date에는 오늘 날짜를
YYYY-MM-DD 형식으로 넣는다. 무엇을 적었는지 보여 준다.
구성 파일이 있으면 이름과 날짜를 거기서 가져오고 고쳐 쓰지 않는다.
파일은 내용이 실제로 바뀔 때만 다시 쓴다.
구성 파일은 있는데 assets.directory가 이 폴더를 가리키지 않거나
구성 파일에 main 필드가 있으면 멈추고 알린다. 배포는 실행하지 않는다.
다시 배포해 달라는 요청인데 폴더에 구성 파일이 없으면 멈추고
물어본다. 새 프로젝트는 만들지 않는다.
배포: 프로젝트 폴더에서 npx wrangler deploy. 실행 전에 명령을 보여 준다.
응답에는 공개 주소를 돌려주고, 그 주소에서 페이지와 이미지를
확인하라고 알려 준다. 업데이트할 때는 주소가 그대로여야 한다.
Node.js가 없거나 인증이 안 되어 있으면 그 사실을 알리고,
우회하려고 하지 않는다.
계정에 아직 workers.dev 서브도메인이 없으면 그 사실을 알린다:
비대화형 배포는 이 지점에서 실패한다.

스킬이 만들어지면 에이전트가 보여 준 .claude/skills/<이름>/SKILL.md 파일을 열어 보세요. 위의 규칙이 들어 있어야 합니다. 두 번째 요청을 보내기 전에, 에이전트가 알려 준 방법으로 새 스킬을 명시적으로 호출하세요. 스킬을 찾지 못한다면 경로와, 현재 프로젝트에서 스킬을 쓸 수 있는지 확인해 달라고 요청하세요.

두 번째는 실행 전 점검입니다. 폴더를 처음 배포하기 전, 무언가가 외부로 나가기 전에 계획부터 보고 싶을 때 유용합니다. 폴더가 여러 개라면 폴더마다 따로 요청합니다:

파일을 만들거나 바꾸지 말고, wrangler도 실행하지 마세요. 대신
landing 폴더로 무엇을 할지만 보여 주세요: 프로젝트 이름,
작성할 구성 파일, 실행할 명령.

한 가지 주의할 점이 있습니다. 접미사는 구성 파일을 쓰는 순간에 생기므로, 아직 구성 파일이 없는 폴더라면 계획에 나온 이름과 실제 실행 때의 이름이 다를 수 있습니다. 나머지는 모두 일치합니다.

세 번째와 네 번째는 실제로 쓰는 요청이고, 이것 때문에 지금까지 준비한 것입니다:

Cloudflare Workers에 landing 폴더를 배포해 주세요.

landing의 index.html을 수정했습니다. Cloudflare Workers에 다시 배포해 주세요.

첫 게시가 끝나면 받은 링크를 열어 텍스트와 이미지를 확인하세요. 그다음 landing/index.html에서 눈에 띄는 문장 하나를 바꾸고 네 번째 요청을 보냅니다. 같은 주소에서 페이지를 새로 고치면 바뀐 문장이 보여야 합니다. 주소가 바뀌었다면 다음 배포 전에 구성 파일의 이름을 확인해 달라고 에이전트에게 요청하세요.

이것으로 기본 경로는 끝입니다. 스킬을 만들었고, 페이지를 게시했고, 같은 링크에서 업데이트까지 확인했습니다. 앞으로는 게시할 때마다 올바른 폴더를 고르고 에이전트가 보여 주는 명령만 확인하면 됩니다.

6. 추가 시나리오

한 번에 많은 폴더를 준비하거나 브라우저 로그인 없이 배포를 실행할 일이 아직 없다면, 여기서부터는 읽지 않아도 됩니다.

절차만으로 부족해질 때

지침 형태의 스킬은 폴더가 몇 개에서 수십 개일 때까지는 잘 동작합니다. 그 이상이 되면 에이전트가 매번 절차를 다시 읽고 손으로 실행한다는 점이 걸림돌이 됩니다. 폴더가 쉰 개쯤 되면 오래 걸리고, 결과가 늘 똑같지도 않습니다.

그때는 절차를 스크립트로 옮깁니다. 스크립트가 폴더를 알아서 돌면서 구성 파일을 쓰고, 바뀐 것이 없는 폴더는 건너뛰고, 요약을 출력합니다. 스킬은 그대로 남습니다. 구성 파일을 직접 쓰는 대신 스크립트를 부를 뿐이고, 배포는 여전히 스킬이 직접 실행합니다.

스크립트를 작성하는 것도 여러분이 아닙니다. 에이전트는 이미 절차를 자세히 설명한 문서, 즉 여러분의 스킬을 가지고 있으니 요청은 짧아집니다:

제 배포용 skill에 적힌 것과 같은 일을 하되, 프로젝트의 모든 폴더를
한 번에 처리하는 Python 스크립트를 작성해 주세요.

루트에 index.html이 있는 폴더를 대상으로 하고,
node_modules, .git, dist는 들여다보지 않습니다.
각 폴더마다 우리 규칙대로 이름을 만들고 wrangler.jsonc를
폴더 안에 씁니다.
구성 파일이 이미 있으면 이름과 compatibility_date는 거기서 가져오고,
파일은 내용이 실제로 바뀌었을 때만 다시 씁니다.
구성 파일을 읽을 수 없으면 건드리지 말고, 그 사실을 알린 뒤
그 폴더는 건너뜁니다.
기본 동작은 계획만 보여 주고 아무것도 쓰지 않는 것이고,
쓰기는 명시적인 플래그를 줄 때만 합니다.
선택한 폴더만 처리할 수 있는 필터가 필요합니다.
스크립트는 구성 파일만 준비하고, 배포는 실행하지 않습니다.
마지막에 표를 출력합니다: 폴더, 프로젝트 이름, 수행한 작업.
이 설명에서 애매한 부분이 있으면 말없이 짐작하지 말고 물어봐 주세요.

계획 보기 모드 덕분에 쓰기 전에 폴더 목록을 확인할 수 있습니다. 이름과 날짜를 유지하는 규칙은 기존 구성 파일이 실수로 바뀌는 것을 막아 줍니다. 스크립트는 설정만 준비하고, 게시는 여전히 스킬이 맡습니다.

액세스 토큰

여러분 컴퓨터에서는 이미 npx wrangler login으로 로그인했습니다. Wrangler는 인증 정보를 저장해 두고, 에이전트가 실행하는 명령도 그것을 사용합니다.

브라우저 로그인 없이 자동으로 실행해야 하거나 권한을 더 좁히고 싶다면 API 토큰을 사용합니다. 토큰은 프로필에서 만들 수 있습니다: 아바타, 프로필, API 토큰 섹션 순서입니다. 바로 가는 주소는 dash.cloudflare.com/profile/api-tokens입니다.

생성 양식은 권한 그룹, 리소스, 무슨 필터 같은 것들로 복잡해 보입니다. 하지만 실제로 정할 것은 네 가지뿐이고, 필드의 절반은 아예 건드리지 않아도 됩니다.

1. 토큰 이름. 반년만 지나도 무엇에 쓰던 토큰인지 기억나지 않으니, 용도를 알 수 있게 적으세요. "token 2"가 아니라 "노트북에서 페이지 배포"처럼요.
2. 권한. 권한을 하나씩 고를 필요도 없고, 그러지 않는 편이 낫습니다. 준비된 템플릿 목록에 Edit Cloudflare Workers가 있고, 게시에 필요한 권한이 모두 들어 있습니다.
3. 리소스. 토큰은 배포하는 계정 하나로 제한하세요. 계정이 하나뿐이라도 명시적으로 선택하세요. 계정은 늘어날 수 있지만 토큰은 그대로 남습니다.
4. 유효 기간과 IP 필터. 선택 입력 필드입니다. 유효 기간은 토큰이 하룻저녁만 필요하거나 남의 컴퓨터에서 쓸 때 정해 두면 좋고, 평소 작업에서는 그대로 둡니다.

그다음 토큰은 환경 변수 CLOUDFLARE_API_TOKEN에 넣고, 계정은 CLOUDFLARE_ACCOUNT_ID에 지정합니다. 환경 변수는 프로그램이 알아서 읽어 가는 컴퓨터 설정이고, wrangler는 여러분이 따로 알려 주지 않아도 두 변수를 모두 찾습니다. 환경 변수가 어떻게 동작하고 어디에 두는 게 맞는지는 별도의 주제입니다. 여기서는 토큰이 대화 속 문자열이 아니라 이런 "장소"에 있어야 한다는 것만 알면 충분합니다.