시작하기 (Getting started)

원문 보기 위키 갱신 2026.10.07

Workers KV를 처음 사용하는 분들을 위한 시작 가이드예요. 애플리케이션의 모든 사용자 알림 설정(각 사용자는 enabled 또는 disabled 알림을 가질 수 있어요)을 저장하는 기본 키-값 스토어를 만들어요.

출처: 문서

본문

Getting started

애플리케이션의 모든 사용자 알림 구성을 저장하는 기본 키-값 스토어를 만들어 보세요. 각 사용자는 enabled 또는 disabled 알림을 가질 수 있어요.

Workers KV는 Cloudflare Workers 애플리케이션에 저지연·고처리량의 전 세계 스토리지를 제공해요. Workers KV는 사용자 구성 데이터, 라우팅 데이터, A/B 테스트 구성, 인증 토큰을 저장하는 데 이상적이며, 읽기 위주의 워크로드에 잘 맞아요.

이 가이드는 다음을 안내해요.

KV 네임스페이스 만들기
Cloudflare Worker에서 KV 네임스페이스에 키-값 쌍 쓰기
KV 네임스페이스에서 키-값 쌍 읽기

이 작업들은 Wrangler CLI 또는 Cloudflare 대시보드를 통해 수행할 수 있어요.

빠른 시작 (Quick start)

설정 단계를 건너뛰고 빠르게 시작하고 싶다면 아래 버튼을 클릭하세요.

이렇게 하면 GitHub 계정에 리포지토리가 생성되고 애플리케이션이 Cloudflare Workers에 배포돼요. Cloudflare Workers에 익숙하고 단계별 안내를 건너뛰고 싶다면 이 옵션을 사용하세요.

Cloudflare Workers가 처음이라면 단계를 수동으로 따라가는 것이 좋아요.

사전 요구 사항 (Prerequisites)

Cloudflare 계정 ↗︎에 가입하세요.
Node.js ↗︎를 설치하세요.

Node.js 버전 관리자

권한 문제를 피하고 Node.js 버전을 변경하려면 Volta ↗︎나 nvm ↗︎ 같은 Node 버전 관리자를 사용하세요. 이 가이드에서 나중에 다루는 Wrangler는 16.17.0 이상의 Node 버전이 필요해요.

1. Worker 프로젝트 만들기

KV 네임스페이스에 읽고 쓰는 새 Worker를 만들어요.

다음을 실행해 kv-tutorial이라는 새 프로젝트를 만드세요.

npm create cloudflare@latest -- kv-tutorial

yarn create cloudflare kv-tutorial

pnpm create cloudflare@latest kv-tutorial

설정 시 다음 옵션을 선택하세요.

What would you like to start with? 에서 Hello World example을 선택하세요.
Which template would you like to use? 에서 Worker only를 선택하세요.
Which language do you want to use? 에서 TypeScript를 선택하세요.
Do you want to use git for version control? 에서 Yes를 선택하세요.
Do you want to deploy your application? 에서 No를 선택하세요. (배포하기 전에 몇 가지를 변경할 거예요.)

이렇게 하면 아래와 같은 새 kv-tutorial 디렉터리가 생성돼요.

kv-tutorial/
- node_modules/
- test/
- src/
  - index.ts
- package-lock.json
- package.json
- testconfig.json
- vitest.config.mts
- worker-configuration.d.ts
- wrangler.jsonc

새 kv-tutorial 디렉터리에는 다음이 포함돼요.

index.ts에 있는 "Hello World" Worker
wrangler.jsonc 구성 파일. wrangler.jsonc는 kv-tutorial Worker가 kv 데이터베이스에 접근하는 방식이에요.
방금 만든 Worker 프로젝트 디렉터리로 이동하세요.

cd kv-tutorial

Cloudflare 대시보드에서 Workers & Pages 페이지로 이동하세요. Workers & Pages로 이동 ↗
Create application을 선택하세요.
Start with Hello World! > Get started를 선택하세요.
Worker 이름을 지정하세요. 이 튜토리얼에서는 kv-tutorial로 이름을 지어요.
Deploy를 선택하세요.

2. KV 네임스페이스 만들기

KV 네임스페이스는 Cloudflare의 전 세계 네트워크에 복제되는 키-값 데이터베이스예요.

Wrangler를 사용해 새 KV 네임스페이스를 만들 수 있어요. 또한 이를 사용해 KV 네임스페이스 안에서 put, list, get, delete 같은 작업을 수행할 수도 있어요.

Wrangler로 KV 네임스페이스를 만들려면:

터미널을 열고 다음 명령을 실행하세요.

npx wrangler kv namespace create <BINDING_NAME>

npx wrangler kv namespace create <BINDING_NAME> 하위 명령은 새 바인딩 이름을 인자로 받아요. KV 네임스페이스는 Worker의 이름(Wrangler 파일에서)과 제공한 바인딩 이름을 연결해 만들어져요. <BINDING_ID>는 무작위로 생성돼요. 이 튜토리얼에서는 바인딩 이름 USERS_NOTIFICATION_CONFIG를 사용해요.

npx wrangler kv namespace create USERS_NOTIFICATION_CONFIG

🌀 Creating namespace with title "USERS_NOTIFICATION_CONFIG"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
{
	"kv_namespaces": [
		{
			"binding": "USERS_NOTIFICATION_CONFIG",
			"id": "<BINDING_ID>"
		}
	]
}

Cloudflare 대시보드에서 Workers KV 페이지로 이동하세요. Workers KV로 이동 ↗
Create instance를 선택하세요.
네임스페이스 이름을 입력하세요. 이 튜토리얼에서는 kv_tutorial_namespace를 사용해요.
Create를 선택하세요.

3. Worker를 KV 네임스페이스에 바인딩하기

Worker를 KV 네임스페이스에 연결하려면 바인딩을 만들어야 해요. 바인딩을 통해 Workers가 Cloudflare 개발자 플랫폼의 KV 같은 리소스에 접근할 수 있어요.

KV 네임스페이스를 Worker에 바인딩하려면:

Wrangler 파일에 2단계에서 터미널에 생성된 값들을 사용해 다음을 추가하세요.

{
	"kv_namespaces": [
		{
			"binding": "USERS_NOTIFICATION_CONFIG",
			"id": "<BINDING_ID>"
		}
	]
}

[[kv_namespaces]]
binding = "USERS_NOTIFICATION_CONFIG"
id = "<BINDING_ID>"

바인딩 이름은 생성한 네임스페이스와 일치할 필요가 없어요. 바인딩 이름은 단지 참조일 뿐이에요. 구체적으로:

binding에 설정하는 값(문자열)은 Worker에서 이 KV 네임스페이스를 참조하는 데 사용돼요. 이 튜토리얼에서는 USERS_NOTIFICATION_CONFIG이어야 해요.
바인딩은 유효한 JavaScript 변수 이름 ↗︎이어야 해요. 예를 들어 binding = "MY_KV" 또는 binding = "routingConfig"는 모두 바인딩의 유효한 이름이에요.
바인딩은 Worker 안에서 env.<BINDING_NAME>으로 접근할 수 있어요. 이 튜토리얼에서는 env.USERS_NOTIFICATION_CONFIG로 접근할 수 있어요.
Cloudflare 대시보드에서 Workers & Pages 페이지로 이동하세요. Workers & Pages로 이동 ↗
1단계에서 만든 kv-tutorial Worker를 선택하세요.
Bindings 탭으로 이동한 뒤 Add binding을 선택하세요.
KV namespace > Add binding을 선택하세요.
Variable name에 바인딩 이름(BINDING_NAME)을 지정하고, 드롭다운 메뉴에서 2단계에서 만든 KV 네임스페이스(kv_tutorial_namespace)를 선택하세요.
바인딩을 배포하려면 Add binding을 선택하세요.

4. KV 네임스페이스와 상호작용하기

Wrangler를 통해 또는 Workers 애플리케이션에서 직접 KV 네임스페이스와 상호작용할 수 있어요.

4.1. 값 쓰기

Wrangler를 사용해 빈 KV 네임스페이스에 값을 쓰려면:

터미널에서 wrangler kv key put 하위 명령을 실행하고 키와 값을 각각 입력하세요. <KEY>와 <VALUE>는 원하는 값이에요.

npx wrangler kv key put --binding=<BINDING_NAME> "<KEY>" "<VALUE>"

이 튜토리얼에서는 2단계에서 만든 KV 네임스페이스에 키 user_1, 값 enabled를 추가해요.

npx wrangler kv key put --binding=USERS_NOTIFICATION_CONFIG "user_1" "enabled"

Writing the value "enabled" to key "user_1" on namespace <BINDING_ID>.

Cloudflare 대시보드에서 Workers KV 페이지로 이동하세요. Workers KV로 이동 ↗
만든 KV 네임스페이스(kv_tutorial_namespace)를 선택하세요.
KV Pairs 탭으로 이동하세요.
원하는 <KEY>를 입력하세요.
원하는 <VALUE>를 입력하세요.
Add entry를 선택하세요.

4.2. 값 가져오기

Wrangler를 사용해 KV 네임스페이스에서 값을 접근하려면:

터미널에서 wrangler kv key get 하위 명령을 실행하고 키 값을 입력하세요.

npx wrangler kv key get --binding=<BINDING_NAME> "<KEY>"

이 튜토리얼에서는 2단계에서 만든 KV 네임스페이스에서 키 user_1의 값을 가져와요.

npx wrangler kv key get --binding=USERS_NOTIFICATION_CONFIG "user_1" --text

put 명령과 마찬가지로 get 명령도 --binding 또는 --namespace-id 두 가지 방법으로 KV 네임스페이스에 접근할 수 있어요.

주어진 KV 네임스페이스에 여러 키-값 쌍의 파일을 쓰려면 kv bulk 문서를 참조하세요.

대시보드에서 직접 키-값 쌍을 볼 수 있어요.

Cloudflare 대시보드에서 Workers KV 페이지로 이동하세요. Workers KV로 이동 ↗
만든 KV 네임스페이스(kv_tutorial_namespace)로 이동하세요.
KV Pairs 탭으로 이동하세요.

5. Worker에서 KV 네임스페이스 접근하기

Worker 스크립트에서 Env 인터페이스에 KV 바인딩을 추가하세요. 프로젝트를 JavaScript로 부트스트랩했다면 이 단계는 필요하지 않아요.

interface Env {
	USERS_NOTIFICATION_CONFIG: KVNamespace;
	// ... other binding types
}

USERS_NOTIFICATION_CONFIG에 put() 메서드를 사용해 새 키-값 쌍을 만들어요. KV 네임스페이스에 키 user_2, 값 disabled를 추가할 거예요.

let value = await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");

KV get() 메서드를 사용해 KV 네임스페이스에 저장한 데이터를 가져와요. KV 네임스페이스에서 키 user_2의 값을 가져올 거예요.

let value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");

Worker 코드는 다음과 같아야 해요.

export default {
	async fetch(request, env, ctx) {
		try {
			await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");
			const value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");
			if (value === null) {
				return new Response("Value not found", { status: 404 });
			}
			return new Response(value);
		} catch (err) {
			console.error(`KV returned error:`, err);
			const errorMessage =
				err instanceof Error
					? err.message
					: "An unknown error occurred when accessing KV storage";
			return new Response(errorMessage, {
				status: 500,
				headers: { "Content-Type": "text/plain" },
			});
		}
	},
};

export interface Env {
  USERS_NOTIFICATION_CONFIG: KVNamespace;
}

export default {
  async fetch(request, env, ctx): Promise<Response> {
    try {
      await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");
      const value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");
      if (value === null) {
        return new Response("Value not found", { status: 404 });
      }
      return new Response(value);
    } catch (err) {
      console.error(`KV returned error:`, err);
      const errorMessage =
        err instanceof Error
          ? err.message
          : "An unknown error occurred when accessing KV storage";
      return new Response(errorMessage, {
        status: 500,
        headers: { "Content-Type": "text/plain" },
      });
    }
  },
} satisfies ExportedHandler<Env>;

위 코드는:

KV의 put() 메서드를 사용해 KV 네임스페이스에 키를 써요.
KV의 get() 메서드를 사용해 같은 키를 읽어요.
키가 null인지 확인하고, null이면 404 응답을 반환해요.
키가 null이 아니면 키의 값을 반환해요.
JavaScript의 try...catch ↗︎ 예외 처리를 사용해 잠재적 오류를 잡아요. Workers KV 같은 서비스나 fetch()를 사용하는 외부 API에 쓰거나 읽을 때는 예외를 명시적으로 처리할 것을 기대해야 해요.
Cloudflare 대시보드에서 Workers & Pages 페이지로 이동하세요. Workers & Pages로 이동 ↗
만든 kv-tutorial Worker로 이동하세요.
Edit Code를 선택하세요.
workers.js 파일의 내용을 지운 뒤 다음 코드를 붙여넣으세요.

export default {
	async fetch(request, env, ctx) {
		try {
			await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");
			const value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");
			if (value === null) {
				return new Response("Value not found", { status: 404 });
			}
			return new Response(value);
		} catch (err) {
			console.error(`KV returned error:`, err);
			const errorMessage =
				err instanceof Error
					? err.message
					: "An unknown error occurred when accessing KV storage";
			return new Response(errorMessage, {
				status: 500,
				headers: { "Content-Type": "text/plain" },
			});
		}
	},
};

export interface Env {
  USERS_NOTIFICATION_CONFIG: KVNamespace;
}

export default {
  async fetch(request, env, ctx): Promise<Response> {
    try {
      await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");
      const value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");
      if (value === null) {
        return new Response("Value not found", { status: 404 });
      }
      return new Response(value);
    } catch (err) {
      console.error(`KV returned error:`, err);
      const errorMessage =
        err instanceof Error
          ? err.message
          : "An unknown error occurred when accessing KV storage";
      return new Response(errorMessage, {
        status: 500,
        headers: { "Content-Type": "text/plain" },
      });
    }
  },
} satisfies ExportedHandler<Env>;

위 코드는:

KV의 put() 메서드를 사용해 BINDING_NAME에 키를 써요.
KV의 get() 메서드를 사용해 같은 키를 읽고, 키가 null이면(또는 키가 설정되지 않았거나 존재하지 않는 경우) 오류를 반환해요.
JavaScript의 try...catch ↗︎ 예외 처리를 사용해 잠재적 오류를 잡아요. Workers KV 같은 서비스나 fetch()를 사용하는 외부 API에 쓰거나 읽을 때는 예외를 명시적으로 처리할 것을 기대해야 해요.

브라우저는 get() 메서드로 지정한 KEY에 해당하는 VALUE를 그냥 반환해야 해요.

Deploy 옆의 드롭다운 화살표를 선택하고 Save를 선택하세요.

6. Worker 배포하기

Worker를 Cloudflare의 전 세계 네트워크에 배포해요.

KV를 Cloudflare의 전 세계 네트워크에 배포하려면 다음 명령을 실행하세요.

npm run deploy

새로 만든 Workers KV 애플리케이션의 URL을 방문하세요. 예를 들어 새 Worker의 URL이 kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev라면, https://kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev/에 접근하면 Workers KV에 쓰고(그리고 읽는) 요청이 Worker로 전송돼요.
Cloudflare 대시보드에서 Workers & Pages 페이지로 이동하세요. Workers & Pages로 이동 ↗
kv-tutorial Worker를 선택하세요.
Deployments를 선택하세요.
Version History 테이블에서 Deploy version을 선택하세요.
Deploy version 페이지에서 Deploy를 선택하세요. 이렇게 하면 최신 버전의 Worker 코드가 프로덕션에 배포돼요.

요약 (Summary)

이 튜토리얼을 마치면 다음을 수행했을 거예요.

KV 네임스페이스 만들기
그 네임스페이스에서 읽고 쓰는 Worker 만들기
프로젝트를 전 세계에 배포하기

다음 단계 (Next steps)

기능 요청이 있거나 버그를 발견했다면 Cloudflare Developers 커뮤니티 Discord ↗︎에 가입해 Cloudflare 팀에 직접 피드백을 공유하세요.

KV API에 대해 자세히 알아보세요.
Workers KV에서 Environments를 사용하는 방법을 이해하세요.
Wrangler kv 명령 문서를 읽어보세요.