Artifacts를 로컬에서 개발할 수 있게 됐지만, 로컬 저장소와 배포된 저장소는 서로 분리돼 있어요. 시작하기 전에는 개발 도구의 버전과 바인딩의 remote 값을 함께 확인해 주세요. 같은 이름의 namespace를 쓴다고 배포 저장소가 내 컴퓨터로 자동 복사되는 것은 아닙니다.
Cloudflare는 2026년 11월 16일 Artifacts 로컬 개발 지원을 발표했습니다. 17일 현재 공식 가이드에는 구형 Vite·Vitest 경로의 예외와 이벤트·데이터 보존 조건도 설명돼 있어요. 이 글은 Workers에서 Git 저장소를 만들거나 저장소 이벤트로 작업을 연결하려는 개발자를 위한 비교 안내입니다. 직접 저장소를 생성·복제·배포한 사용 후기는 아닙니다.
먼저 로컬과 원격 중 어디에 연결할지 정해요
바인딩은 Worker 코드가 서비스에 접근할 때 쓰는 연결 이름이라고 생각하면 편해요. namespace는 저장소를 구분하는 이름공간이에요. 현재 지원 도구에서 Artifacts 바인딩으로 로컬 Worker를 실행하면 로컬 시뮬레이터가 기본 경로입니다. remote를 생략하거나 false로 정하면 로컬 저장소를 사용하고, true로 정하면 배포된 Artifacts 서비스를 사용합니다.
이 선택은 단순한 실행 속도 옵션이 아닙니다. 로컬 저장소와 토큰은 배포 자원과 분리되며, 로컬 저장소를 만들거나 push·삭제해도 배포 저장소를 바꾸지 않는다고 문서가 설명해요. 반대로 원격 바인딩을 선택했다면 개발 서버를 내 컴퓨터에서 실행했다는 이유로 변경 대상까지 로컬이라고 판단하면 안 됩니다.
가령 테스트용 Git 저장소를 만들고 생성 이벤트를 관찰하려는 상황을 생각해 보세요. 원하는 대상이 새 로컬 저장소인지, 이미 배포한 저장소인지 먼저 적을 수 있습니다. 이는 선택 기준을 설명하는 가상 상황입니다. 실제 계정에서 자원이나 이벤트를 만들었다는 뜻은 아니에요.
remote를 생략한 경우 현재 Wrangler의 개발 경로와 Vite 플러그인 등은 로컬 시뮬레이터를 쓴다는 경고를 표시합니다. 로컬 사용을 명확하게 하려면 false, 배포 자원을 사용하려면 true로 설정하는 취지예요. cloudflare.config.ts에서는 dev 아래의 remote 설정을 사용하므로 서로 다른 설정 파일의 위치도 구분해야 합니다.
특히 예전에 원격 기본값을 이용하던 프로젝트는 업그레이드 뒤에도 같은 저장소를 본다고 추측하지 않는 편이 좋아요. 실제 버전, 프로젝트 설정 파일, namespace와 반환된 remote 주소를 한 묶음으로 확인해 두세요. 원격 바인딩과 로컬 저장소 사이에 자동 동기화가 있다는 가정도 문서의 설명과 다릅니다.
버전 표와 구형 도구의 예외를 같이 읽으세요
11월 17일 확인한 로컬 가이드는 다음 지원 기준을 제시합니다. 아래 숫자는 공식 문서의 조건이며 이 글을 작성한 컴퓨터에 설치해 시험한 버전 목록은 아니에요. 도구 이름이 비슷해도 같은 실행 경로로 취급하지 말아 주세요.
| 도구 | 문서의 로컬 지원 기준 |
| Git | 2.32 이상, 개발 서버·테스트 프로세스의 PATH에 있어야 함 |
| Wrangler | 4.163.0 이상 |
| Cloudflare Vite plugin | 2.0.0-rc.0 이상 |
| @cloudflare/vitest-plugin | 1.8.3 이상 |
여기서 rc 표시는 정식 안정 버전과 같은 뜻으로 넓히지 않는 것이 좋아요. 현재 프로젝트가 사용하는 버전과 업그레이드 정책을 먼저 확인할 부분입니다. 공지의 ‘최신 버전 필요’라는 안내와 상세 문서의 숫자는 확인한 날짜를 붙여 함께 읽어 주세요. 다음 날에도 모든 조건이 고정돼 있다고 보장하지는 않습니다.
Vite 플러그인 1.x는 이전 기본값을 유지한다는 예외가 있습니다. 원격 바인딩이 켜진 상태에서는 remote를 생략하면 배포 저장소를 사용하며, 로컬 시뮬레이터를 쓰려면 false로 정하도록 문서가 안내해요. 따라서 새 기본값만 기억하고 오래된 Vite 프로젝트에 적용하면 연결 대상을 잘못 이해할 수 있습니다.
이름이 비슷한 예전 @cloudflare/vitest-pool-workers 패키지도 별도로 봐야 합니다. 이 경로는 이전 원격 기본값을 유지하며 Cloudflare 인증 정보가 없으면 실패한다고 설명돼 있어요. 로컬 테스트를 위해 현재 @cloudflare/vitest-plugin으로 옮기는 안내와, 기존 패키지의 행동을 구분해야 합니다.
cloudflare.config.ts에서 Workflow 이벤트를 선언하는 경로에도 별도 버전 조건이 있습니다. 문서는 cf 1.0.0-rc.0 이상을 안내하고 직접 설정 패키지를 가져오는 경우의 조건도 설명해요. 바인딩이 동작한다는 확인을 이벤트 선언까지 모두 지원된다는 결론으로 넓히지 않는 이유입니다.
Git과 토큰, 가져오기 경로를 나누어 확인해요
로컬 시뮬레이터는 개발 기계의 Git을 사용합니다. 터미널 어딘가에 Git이 설치돼 있다는 사실보다 개발 서버나 테스트를 시작하는 프로세스의 PATH에서 Git을 찾을 수 있는지가 중요해요. 공식 가이드의 git --version은 그 환경에서 버전을 확인하기 위한 읽기용 명령입니다. 이 글에서는 명령을 실행하지 않았습니다.
Git이 없거나 2.32보다 오래되면 시작 시 설치·업그레이드 안내와 함께 실패한다고 문서가 설명합니다. PATH를 바꿨다면 개발 도구를 다시 시작해야 하는 조건도 있어요. 이 경우를 Cloudflare 계정에서 로그아웃됐다는 증거로 바로 해석하지 말고 로컬 실행 환경부터 구분할 수 있습니다.
저장소 생성 결과에는 remote 주소와 초기 토큰이 포함됩니다. 로컬 remote는 루프백 HTTP 주소를 사용하며 표준 Git 클라이언트로 clone·push할 수 있다고 안내해요. 여기의 저장소 토큰은 Cloudflare API 토큰과 다른 자격 정보입니다. 실제 비밀값을 원고·소스·Git 설정이나 로그에 복사하는 방식으로 확인하지 말아 주세요.
원격 바인딩은 배포 서비스 접근을 위한 Cloudflare 인증이 필요합니다. 반면 로컬 바인딩은 Git이 필요하고 로컬 개발을 위한 Cloudflare 자격 정보는 필요하지 않다는 비교가 있어요. 다만 외부의 비공개 Git 저장소를 가져오려면 그 원본 저장소에 접근하는 별도 조건이 있을 수 있으므로 ‘모든 인증이 필요 없다’로 일반화하면 안 됩니다.
HTTPS import는 내 개발 기계의 Git이 원본 호스트에 접속하는 방식입니다. 원본에 내 기계에서 도달할 수 있어야 하며 신뢰하는 최종 HTTPS Git URL을 사용하도록 안내해요. HTTP 리디렉션을 따라가지 않는다는 조건도 있습니다. 인증서 문제를 보안 검증 해제로 해결하라고 이 글에서 안내하지는 않습니다.
저장소 작업 성공과 Workflow 실행은 다른 확인이에요
현재 로컬 가이드는 저장소 생성·가져오기·포크·삭제와 저장소 토큰 생성·회수 이벤트를 지원한다고 설명합니다. 생성·가져오기·포크 때는 초기 토큰의 생성 이벤트도 나와요. 한 작업에서 여러 이벤트가 생길 수 있으므로 이벤트 하나와 저장소 작업 한 번을 항상 같은 개수로 세면 안 됩니다.
반면 push·clone·fetch 이벤트는 아직 로컬에서 발행하지 않는다고 명시돼 있습니다. 배포 환경의 이벤트 안내에는 이런 이벤트가 있더라도 로컬 지원 범위가 같다는 뜻은 아니에요. push로 빌드·배포를 시작하는 Workflow는 이 로컬 경로에서 시작하지 않는다는 제한을 함께 읽어 주세요.
이벤트가 연결되는 대상도 확인해야 합니다. 로컬 전달은 Workflows를 대상으로 하며 큐로 전달하지 않습니다. 같은 Worker에 정의된 Workflow를 대상으로 설정하고, 메시지는 해당 인스턴스의 event.payload에 전달됩니다. 단순히 로그에 저장소 변경이 보였다는 사실과 올바른 Workflow가 메시지를 받았다는 확인은 다른 단계예요.
로컬 메시지는 배포 환경과 같은 type·source·payload·metadata 필드를 가지지만 accountId가 local이라는 차이가 있습니다. 또 이벤트 순서를 보장하지 않습니다. 저장소 생성과 초기 토큰 생성처럼 연이어 일어난 작업도 도착 순서를 전제로 처리하지 않도록 설계를 검토할 부분이에요.
이벤트 전달이 실패하면 개발 서버가 오류를 기록하고 재시도하지 않는다고 문서가 설명합니다. 저장소 작업은 이미 성공할 수 있어요. 따라서 저장소가 있다는 사실만으로 후속 자동화까지 끝났다고 기록하지 않는 것이 좋습니다. Vite 플러그인 1.x는 로컬 이벤트에서 Workflow를 시작하지 않는 예외도 별도로 확인해 주세요.
로컬 데이터의 보존 위치와 지원하지 않는 기능을 살펴봐요
로컬 저장소 메타데이터와 Git 객체는 개발 도구의 자원 보존 디렉터리에 저장됩니다. 보존이 켜진 Wrangler·Vite 플러그인 1.x는 일반적으로 .wrangler/state/를, Vite 플러그인 2.x는 .cloudflare/state/를 쓴다고 안내해요. 같은 프로젝트 루트와 보존 설정을 사용해야 재시작 뒤에도 이어서 볼 수 있습니다.
보존을 끄면 데이터가 임시 상태가 될 수 있습니다. 그래서 서버가 다시 시작됐다는 사건과 저장소가 사라졌다는 관찰을 한 원인으로 단정하기 전에 프로젝트 위치·도구·보존 설정을 대조해 주세요. 로컬 토큰과 저장소 데이터가 원격 바인딩으로 옮겨지는 것은 아니라는 조건도 중요합니다.
로컬 Git 포트는 상태와 함께 저장돼 재시작 때 재사용됩니다. 다른 프로세스가 그 포트를 차지하면 새 포트를 고를 수 있으므로 기존 clone이 계속 같은 주소를 쓴다고 보장할 수는 없어요. 문서는 이런 경우 바인딩에서 새 remote를 얻어 기존 clone의 remote를 갱신하도록 안내합니다. 실제 주소를 확인하기 전 임의 포트로 바꾸지는 마세요.
초기화가 필요하더라도 전체 상태 폴더를 무작정 지우는 방식은 피해야 합니다. 공식 안내는 개발 서버를 중지하고 필요한 저장소를 백업한 뒤 해당 도구의 보존 디렉터리 안 artifacts/만 대상으로 삼는 순서예요. 이 글은 삭제 명령을 제공하거나 실제 데이터를 초기화하지 않습니다.
로컬 시뮬레이터가 제공하지 않는 표면도 있습니다. 로컬 REST API·Artifacts CLI·대시보드·SSH 엔드포인트·Git LFS 서버까지 생긴 것은 아니에요. 또한 파일 하나가 32MiB를 넘는 push의 거절 등 문서의 제한이 있습니다. Git 저장소를 한 번 만들었다는 사실을 모든 개발 기능의 호환성으로 넓히지 않는 편이 좋습니다.
작은 실행 메모에는 대상과 관찰 결과를 함께 남겨요
실제 도입을 준비한다면 먼저 도구·버전·설정 파일과 remote 값을 적어 보세요. 이어 반환된 주소의 대상, 로컬 상태 위치, 보존 여부를 확인할 수 있습니다. 민감한 토큰 원문 대신 담당자가 다시 찾을 수 있는 안전한 식별 정보만 남기는 메모를 제안합니다.
다음으로 시험할 질문을 하나씩 나눠 보세요. 저장소 생성 결과를 얻었는지, Git에서 같은 저장소를 볼 수 있는지, 지원되는 생성 이벤트가 도착했는지, 목표 Workflow가 메시지를 처리했는지가 각각 다른 질문입니다. 본문의 체크 순서는 준비 제안이며 이런 작업을 실제 수행해 통과했다는 기록은 아닙니다.
배포 환경에서만 확인할 조건도 따로 남겨야 합니다. 로컬에서 아직 제공하지 않는 push 이벤트·큐 전달·관리 화면의 동작을 로컬 성공으로 대신할 수는 없어요. 원격 시험은 대상 계정과 기존 저장소·비용·권한에 영향을 줄 수 있으므로 승인 범위와 복구 계획을 확인한 뒤 별도로 판단할 문제입니다.
자주 생길 혼동을 정리해 볼게요. namespace 이름이 같으면 데이터도 같나요? 로컬과 배포 자원은 분리됩니다. local 모드라면 모든 도구 버전에서 같은가요? 구형 Vite·Vitest 경로의 예외를 봐야 해요. 저장소 생성 성공이면 Workflow도 성공했나요? 전달과 실행 결과를 따로 확인해야 합니다.
새 로컬 지원의 이익은 배포 자원을 바로 건드리기 전에 Git 저장소와 일부 이벤트 흐름을 준비할 수 있다는 점입니다. 그 이익을 살리려면 무엇을 로컬에서 확인했고 무엇이 아직 원격 확인으로 남았는지 적어 주세요. 이 구분이 있어야 다음 담당자도 같은 테스트 결과를 과장 없이 이어받을 수 있습니다.
자료 확인일은 2026년 11월 17일입니다. 공식 발표와 현재 문서로 확인한 범위이며, 실제 계정 설정 변경·명령 실행·성능 시험은 하지 않았어요. 적용 시점의 계정·버전·환경과 승인 범위는 담당자가 다시 확인해 주세요.
함께 읽어 볼 글: Browser Run 로컬 시뮬레이션의 실제 검증 범위를 나누는 글.

'소프트웨어개발' 카테고리의 다른 글
| Cloudflare 비콘 트래픽 탐지 추가: 악성 판정 전에 확인할 조건 (0) | 2026.11.18 |
|---|---|
| RealtimeKit 참가 토큰 시간 설정: 갱신과 회수를 나눠 보세요 (0) | 2026.11.17 |
| D1 가상 테이블 내보내기 지원: SQLite 확인용 덤프와 복원을 구분하세요 (0) | 2026.11.17 |