Cloudflare Workers로 서버리스 애플리케이션 만들기
서버리스 애플리케이션을 만들고 싶은데 AWS Lambda는 너무 복잡하고, 배포도 번거롭다고 느껴본 적 있으신가요? 🤔 Cloudflare Workers를 사용하면 간단한 자바스크립트 코드 몇 줄로 전 세계 300개 이상의 엣지 로케이션에서 실행되는 서버리스 함수를 만들 수 있습니다.
이번 포스팅에서는 Cloudflare Workers의 기본 개념부터 실제 배포까지 단계별로 알아보겠습니다.
Cloudflare Workers란?
Cloudflare Workers는 Cloudflare의 엣지 네트워크에서 실행되는 서버리스 플랫폼입니다. 기존 서버리스 플랫폼과 다른 점은 V8 자바스크립트 엔진을 사용해서 콜드 스타트가 거의 없고, 전 세계 엣지 로케이션에서 실행되기 때문에 사용자와 가까운 곳에서 빠르게 응답할 수 있다는 점입니다.
Cloudflare Workers의 가장 큰 장점은 속도입니다. 기존 서버리스 플랫폼의 고질적인 문제인 콜드 스타트가 1ms 미만으로 사실상 없다고 봐도 무방합니다. 게다가 전 세계 300개 이상의 데이터 센터에서 자동으로 실행되기 때문에 어느 나라에서 접속하든 사용자와 가까운 곳에서 빠르게 응답할 수 있습니다. 비용 측면에서도 매력적인데, 하루 10만 건의 요청까지 무료로 사용할 수 있어서 개인 프로젝트나 사이드 프로젝트에 부담 없이 적용할 수 있습니다. 배포 과정도 간단해서 CLI 도구 하나로 몇 초 만에 전 세계에 배포할 수 있습니다.
Cloudflare 가입
Cloudflare Workers를 사용하려면 먼저 Cloudflare 계정이 필요합니다. Cloudflare 웹사이트에서 무료로 가입할 수 있습니다.
Worker 프로젝트 생성
이제 Wrangler CLI를 사용하여 Worker를 만들어보겠습니다. Wrangler는 Cloudflare Workers를 개발하고 배포하는 데 사용하는 공식 CLI 도구입니다. Wrangler의 설치부터 다양한 명령어까지 자세히 알고 싶으시다면 Wrangler CLI 사용법을 참고하세요.
wrangler init 명령어로 새 프로젝트를 생성할 수 있습니다.
$ npx wrangler init our-worker차세대 런타임 Bun을 사용하신다면 다음 명령어를 사용합니다.
$ bunx wrangler init our-worker터미널에서 몇 가지 질문에 답하면 바로 프로젝트가 생성됩니다.
╭ Create an application with Cloudflare Step 1 of 3
│
├ In which directory do you want to create your application?
│ dir ./our-worker
│
├ What would you like to start with?
│ category Hello World example
│
├ Which template would you like to use?
│ type Worker only
│
├ Which language do you want to use?
│ lang TypeScript
│
├ Copying template files
│ files copied to project directory
│
├ Updating name in `package.json`
│ updated `package.json`
│
├ Installing dependencies
│ installed via `npm install`
│
╰ Application created
╭ Configuring your application for Cloudflare Step 2 of 3
│
├ Installing wrangler A command line tool for building Cloudflare Workers
│ installed via `npm install wrangler --save-dev`
│
├ Retrieving current workerd compatibility date
│ compatibility date 2025-12-30
│
├ Do you want to use git for version control?
│ no git
│
╰ Application configured
╭ Deploy with Cloudflare Step 3 of 3
│
├ Do you want to deploy your application?
│ no deploy via `npm run deploy`
│
╰ Done생성된 프로젝트 디렉토리로 이동하면 src/index.ts 파일이 있습니다.
이 파일에 Worker 코드를 작성하면 됩니다.
export default {
async fetch(request, env, ctx): Promise<Response> {
return new Response('Hello World!');
},
} satisfies ExportedHandler<Env>;Worker는 fetch 핸들러를 export 해야 합니다.
이 핸들러는 HTTP 요청이 들어올 때마다 실행되며, Request 객체를 받아서 Response 객체를 반환합니다.
개발 서버 구동
코드를 작성했으면 로컬에서 테스트해볼 수 있습니다.
wrangler dev 명령어를 실행하면 로컬 개발 서버가 시작됩니다.
$ npx wrangler dev
⛅️ wrangler 4.54.0
───────────────────
╭──────────────────────────────────────────────────────────────────────╮
│ [b] open a browser [d] open devtools [c] clear console [x] to exit │
╰──────────────────────────────────────────────────────────────────────╯
⎔ Starting local server...
[wrangler:info] Ready on http://localhost:8787기본적으로 http://localhost:8787에서 Worker가 실행됩니다.
브라우저나 curl로 접속하면 “Hello World!” 메시지를 확인할 수 있습니다.
$ curl http://localhost:8787Hello World!배포하기
로컬 테스트가 완료되면 실제 Cloudflare 네트워크에 배포할 수 있습니다.
배포는 wrangler deploy 명령어 하나로 끝납니다.
$ npx wrangler deploy
Total Upload: 0.19 KiB / gzip: 0.16 KiB
Uploaded our-worker (1.88 sec)
Deployed our-worker triggers (0.87 sec)
https://our-worker.daleseo.workers.dev
Current Version ID: 7684fad8-4c2e-4452-9f05-907be04f7d8b브라우저가 열리면서 Cloudflare 계정 인증을 진행하게 됩니다. 인증이 완료되면 터미널에서 Workers를 생성하고 배포할 수 있습니다.
배포가 완료되면 Worker가 실행되는 URL이 출력됩니다.
일반적으로 https://our-worker.<your-subdomain>.workers.dev 형식의 URL이 생성됩니다.
이 URL로 접속하면 전 세계 어디서든 가장 가까운 Cloudflare 엣지 로케이션에서 Worker가 실행되어 응답을 받을 수 있습니다. 🚀
요청 처리하기
Worker에서 HTTP 요청을 처리하는 방법을 좀 더 자세히 알아보겠습니다.
Request 객체를 통해 URL, 메서드, 헤더, 바디 등의 정보에 접근할 수 있습니다.
export default {
async fetch(request, env, ctx): Promise<Response> {
const url = new URL(request.url);
const path = url.pathname;
if (path === '/') {
return new Response('홈페이지입니다');
}
if (path === '/about') {
return new Response('소개 페이지입니다');
}
return new Response('페이지를 찾을 수 없습니다', { status: 404 });
},
} satisfies ExportedHandler<Env>;이렇게 URL 경로에 따라 다른 응답을 반환할 수 있습니다.
$ curl http://localhost:8787/
홈페이지입니다
$ curl http://localhost:8787/about
소개 페이지입니다
$ curl http://localhost:8787/unknown
페이지를 찾을 수 없습니다JSON 응답 반환하기
API를 만들 때는 JSON 형식으로 응답을 반환하는 경우가 많습니다.
Response 객체를 만들 때 헤더를 설정하면 됩니다.
export default {
async fetch(request, env, ctx): Promise<Response> {
const data = {
message: 'Hello from Cloudflare Workers!',
timestamp: new Date().toISOString(),
};
return new Response(JSON.stringify(data), {
headers: {
'Content-Type': 'application/json',
},
});
},
} satisfies ExportedHandler<Env>;더 간단하게는 Response.json() 메서드를 사용할 수도 있습니다.
export default {
async fetch(request, env, ctx): Promise<Response> {
const data = {
message: "Hello from Cloudflare Workers!",
timestamp: new Date().toISOString(),
};
return Response.json(data);
},
} satisfies ExportedHandler<Env>;테스트해보면 다음과 같은 결과가 출력됩니다.
$ curl http://localhost:8787/
{"message":"Hello from Cloudflare Workers!","timestamp":"2025-02-16T24:59:04.123Z"}환경 변수 사용하기
API 키나 데이터베이스 연결 정보 같은 민감한 정보는 환경 변수로 관리하는 것이 좋습니다.
Cloudflare Workers에서는 wrangler.jsonc 파일에 환경 변수를 정의할 수 있습니다.
{
"$schema": "node_modules/wrangler/config-schema.json",
"name": "our-project",
"main": "src/index.ts",
"compatibility_date": "2025-02-16",
"vars": {
"ENVIRONMENT": "production"
}
}민감한 정보는 Cloudflare 대시보드에서 Secret으로 등록하거나, wrangler secret put 명령어를 사용할 수 있습니다.
$ npx wrangler secret put API_KEY
⛅️ wrangler 4.54.0
───────────────────
✔ Enter a secret value: … ****
🌀 Creating the secret for the Worker "our-project"
✨ Success! Uploaded secret API_KEY코드에서는 env 객체를 통해 환경 변수에 접근할 수 있습니다.
interface Env {
ENVIRONMENT: string;
}
export default {
async fetch(
request: Request,
env: Env,
ctx: ExecutionContext
): Promise<Response> {
return Response.json({
environment: env.ENVIRONMENT,
API_KEY: env.API_KEY,
});
},
};테스트해보면 다음과 같은 결과가 출력됩니다.
$ curl http://localhost:8787/
{"environment":"production","API_KEY":"****"}외부 API 호출하기
Worker에서 외부 API를 호출할 수도 있습니다.
fetch API를 사용하면 됩니다.
interface GitHubUser {
name: string;
bio: string;
followers: number;
}
export default {
async fetch(request, env, ctx): Promise<Response> {
const response = await fetch("https://api.github.com/users/github", {
headers: {
"User-Agent": "Cloudflare-Worker",
},
});
const data: GitHubUser = await response.json();
return Response.json({
name: data.name,
bio: data.bio,
followers: data.followers,
});
},
} satisfies ExportedHandler<Env>;테스트해보면 다음과 같은 결과가 출력됩니다.
$ curl http://localhost:8787/
{"name":"GitHub","bio":"How people build software.","followers":65647}이렇게 Worker를 프록시나 API 게이트웨이로 사용할 수 있습니다. 예를 들어 여러 API를 조합하거나, 응답을 가공하거나, 캐싱을 추가하는 등의 작업을 할 수 있습니다.
CORS 처리하기
API를 만들 때는 CORS(Cross-Origin Resource Sharing) 설정이 필요한 경우가 많습니다. Worker에서는 응답 헤더에 CORS 관련 헤더를 추가하면 됩니다.
export default {
async fetch(request, env, ctx): Promise<Response> {
const data = { message: "Hello, CORS!" };
return new Response(JSON.stringify(data), {
headers: {
"Content-Type": "application/json",
"Access-Control-Allow-Origin": "*",
"Access-Control-Allow-Methods": "GET, POST, PUT, DELETE",
"Access-Control-Allow-Headers": "Content-Type",
},
});
},
} satisfies ExportedHandler<Env>;프리플라이트 요청(OPTIONS)도 처리해야 합니다.
export default {
async fetch(
request: Request,
env: Env,
ctx: ExecutionContext
): Promise<Response> {
// OPTIONS 요청 처리
if (request.method === "OPTIONS") {
return new Response(null, {
headers: {
"Access-Control-Allow-Origin": "*",
"Access-Control-Allow-Methods": "GET, POST, PUT, DELETE",
"Access-Control-Allow-Headers": "Content-Type",
},
});
}
// 실제 요청 처리
const data = { message: "Hello, CORS!" };
return new Response(JSON.stringify(data), {
headers: {
"Content-Type": "application/json",
"Access-Control-Allow-Origin": "*",
},
});
},
};테스트해보면 다음과 같은 결과가 출력됩니다.
$ curl -i http://localhost:8787/
HTTP/1.1 200 OK
Content-Length: 26
Date: Tue, 16 Feb 2025 21:13:27 GMT
Content-Type: application/json
Access-Control-Allow-Origin: *
Server: cloudflare
Vary: Accept-Encoding
CF-Ray: 9b648a8c8c1852cf-YYZ
{"message":"Hello, CORS!"}%커스텀 도메인 연결하기
기본적으로 제공되는 workers.dev 도메인 대신 자신의 도메인을 사용할 수도 있습니다.
Cloudflare에서 도메인을 관리하고 있다면 대시보드에서 쉽게 연결할 수 있습니다.
Workers 대시보드에서 해당 Worker를 선택하고, “Triggers” 탭에서 “Add Custom Domain”을 클릭합니다. 원하는 도메인이나 서브도메인을 입력하면 자동으로 DNS 레코드가 생성되고 SSL 인증서도 발급됩니다. 🎉
마치며
지금까지 Cloudflare Workers의 기본 사용법을 알아봤습니다. 간단한 API부터 프록시, 엣지 컴퓨팅까지 다양한 용도로 활용할 수 있는 강력한 플랫폼입니다.
특히 무료 플랜으로도 하루 10만 건의 요청을 처리할 수 있어서 개인 프로젝트나 사이드 프로젝트에 부담 없이 사용할 수 있습니다. 콜드 스타트가 거의 없고 전 세계 엣지에서 실행되기 때문에 성능도 뛰어나죠. 💪
Cloudflare Workers로 여러분만의 서버리스 애플리케이션을 만들어보시는 건 어떨까요? Wrangler CLI의 KV, R2, D1 관리 기능이나 환경 분리 같은 고급 기능이 궁금하시다면 Wrangler CLI 사용법도 함께 읽어보세요. 더 자세한 내용은 Cloudflare Workers 공식 문서를 참고해보세요!
This work is licensed under
CC BY 4.0
