DEV_MANUAL

VS Code 설치 및 Cloudflare 배포 매뉴얼 (D1 데이터베이스 생성)

•2026-05-07T07:16:58Z•56 read

Cloudflare Workers + D1 개발 환경 구축

이 문서는 Cloudflare Workers 프로젝트 생성부터 D1 데이터베이스 생성, 테이블 구축, 로컬 개발 및 최초 배포까지의 과정을 순서대로 정리한 매뉴얼입니다. 처음 Cloudflare를 사용하는 경우에도 그대로 따라 하면 개발 환경을 구축할 수 있습니다.

1. 로컬 개발 환경 준비

Cloudflare Workers는 Node.js 기반으로 개발되므로 먼저 개발 환경을 준비해야 합니다. Windows에서는 Scoop을 이용하면 Node.js와 VS Code를 간편하게 설치할 수 있습니다.

1-1. PowerShell 실행

Windows의 PowerShell 또는 Windows Terminal을 실행합니다.

TIP

PowerShell 버전이 오래되면 Scoop 설치가 정상적으로 진행되지 않을 수 있습니다.
가능하면 최신 PowerShell을 설치한 후 진행하는 것을 권장합니다.

1-2. Scoop 설치

PowerShell에서 아래 명령어를 차례대로 실행합니다.

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

iwr -useb get.scoop.sh | iex

설치가 완료되면 scoop 명령어를 사용할 수 있습니다.

1-3. Node.js 설치

아래 명령어를 실행합니다.

scoop install nodejs

Node.js는 Cloudflare Workers 및 Wrangler 실행에 반드시 필요합니다.

1-4. Visual Studio Code 설치

아래 명령어를 실행합니다.

scoop install vscode

설치가 완료되면 VS Code를 실행합니다.

1-5. 작업 폴더 열기

VS Code에서 프로젝트를 저장할 폴더를 엽니다.

메뉴 → File → Open Folder

예시

Z:\workspace\nodejs

2. Cloudflare Workers 프로젝트 생성

2-1. 프로젝트 생성

VS Code에서 Ctrl + ~를 눌러 터미널을 연 뒤 아래 명령어를 실행합니다.

npm create cloudflare@latest 프로젝트명

예시

npm create cloudflare@latest my-worker

잠시 후 여러 질문이 나타나며 아래와 같이 선택합니다.

2-2. 프로젝트 생성 옵션

질문	선택	설명
Which template would you like to use?	Worker only	가장 기본적인 Workers 프로젝트를 생성합니다.
Which language do you want to use?	JavaScript	빠르게 개발하기에 가장 적합합니다.
Do you want to add an AGENTS.md file?	Yes	AI 코딩 도구가 프로젝트 구조를 이해하는 데 도움이 됩니다.
Do you want to use git?	Yes	버전 관리를 위해 Git 사용을 권장합니다.
Do you want to deploy your application?	No	먼저 로컬에서 테스트 후 배포합니다.

3. 로컬 실행 및 최초 배포

3-1. 프로젝트 폴더 이동

cd 프로젝트명

VS Code를 현재 프로젝트로 다시 엽니다.

code . -r

3-2. 코드 수정

Explorer에서

src/index.js

파일을 열고 원하는 코드를 작성한 후 저장합니다.

3-3. 로컬 서버 실행

npx wrangler dev

브라우저에서 아래 주소를 열어 정상적으로 동작하는지 확인합니다.

http://localhost:8787

수정한 내용이 출력되면 로컬 실행이 성공한 것입니다.

3-4. Cloudflare 로그인 (최초 1회)

로컬 서버를 종료합니다.

Ctrl + C

이후 아래 명령어를 실행합니다.

npx wrangler login

브라우저가 열리며 Cloudflare 로그인을 진행하면 Wrangler와 계정이 연결됩니다. 최초 한 번만 수행하면 됩니다.

3-5. Workers 배포

npx wrangler deploy

배포가 완료되면 Workers URL이 출력됩니다. 브라우저에서 접속하여 정상적으로 서비스되는지 확인합니다.

4. Cloudflare D1 데이터베이스 생성 (선택 사항)

4-1. Cloudflare Dashboard 접속

Cloudflare Dashboard에 로그인합니다.

4-2. D1 메뉴 이동

왼쪽 메뉴에서

Workers & Pages
    └── D1

을 선택합니다.

4-3. 데이터베이스 생성

Create database 버튼을 클릭합니다.

Database Name에 원하는 이름을 입력한 뒤 생성합니다.

4-4. Database ID 저장

데이터베이스 상세 화면에서 Database ID를 복사하여 보관합니다.

이 값은 나중에 wrangler.jsonc 또는 wrangler.toml 설정 시 필요합니다.

5. D1 테이블 생성

5-1. SQL Console 열기

생성한 D1 데이터베이스를 선택한 뒤 상단의 Console 탭을 클릭합니다.

5-2. SQL 작성

예시

CREATE TABLE tb_dream (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    content TEXT,
    reg_date DATETIME DEFAULT CURRENT_TIMESTAMP
);

필요한 컬럼을 프로젝트에 맞게 수정합니다.

5-3. SQL 실행

오른쪽 아래의 Execute 버튼을 클릭합니다.

Success 메시지가 출력되면 테이블 생성이 완료됩니다.

다음 단계

이제 Workers에서 D1을 바인딩한 후 SQL을 실행하여 데이터를 조회하거나 저장할 수 있습니다.