Cloudflare Workers Vite 플러그인 로컬 프리뷰 설정 순서

결론부터 말하면, Cloudflare Workers Vite 플러그인 로컬 프리뷰 설정은 “Vite 개발 서버에서 Workers 런타임 차이를 최대한 일찍 확인하는 장치”로 잡는 것이 좋습니다. 새 프로젝트라면 Cloudflare 공식 get started 흐름으로 시작하고, 기존 Vite 앱이라면 플러그인을 추가한 뒤 로컬 실행, preview, 환경 변수, 빌드 결과를 한 번에 점검하는 순서가 안전합니다. 이 글은 업로드나 공개 전 단계에서 팀이 반복 확인할 수 있는 실무용 체크리스트로 정리했습니다.

요약: Cloudflare Workers Vite 플러그인은 Vite 기반 앱을 Workers 환경에 맞춰 개발·빌드·프리뷰하기 위한 연결 도구입니다. 먼저 프로젝트 구조를 확인하고, 플러그인 설치와 설정 파일 반영, npm run dev 실행, npm run build 및 preview 확인, 환경 변수 분리, 로그 확인, 배포 전 체크 순서로 진행하세요. Cloudflare 대시보드, Wrangler, Vite, Workers 기능과 화면 이름은 플랜·버전·계정 상태에 따라 바뀔 수 있으므로 실제 작업 전 공식 문서를 다시 확인하는 것이 좋습니다.

1. 이 설정이 필요한 상황부터 구분하기

Vite 앱을 로컬에서만 실행하면 빠르게 화면을 볼 수 있지만, 실제 Workers 환경에서 동작할 때와 완전히 같다고 보기 어렵습니다. 예를 들어 라우팅 처리, 서버 코드 위치, 환경 변수 접근 방식, 정적 자산 처리, preview 명령의 결과가 일반 Vite 프로젝트와 다르게 느껴질 수 있습니다. Cloudflare Workers Vite 플러그인은 이런 차이를 개발 초기에 드러내기 위한 선택지입니다.

가장 먼저 확인할 것은 “새 Workers 프로젝트를 만들 것인가, 기존 Vite 프로젝트를 Workers에 맞게 옮길 것인가”입니다. 새 프로젝트는 공식 get started 흐름을 따르면 구조가 단순합니다. 반면 이미 React, Vue, Svelte 같은 프런트엔드 프로젝트가 있다면 기존 빌드 스크립트와 Cloudflare 설정이 충돌하지 않게 차근차근 붙여야 합니다.

팀 업무에서는 이 구분이 중요합니다. 새 프로젝트는 템플릿을 기준으로 담당자가 같은 명령을 반복하면 되지만, 기존 프로젝트 전환은 라우팅, API 호출, 빌드 산출물, 외부 서비스 연결을 따로 점검해야 합니다. 그래서 처음부터 “로컬 프리뷰 체크리스트”를 문서로 만들어 두면 이후 운영 담당자와 개발자가 같은 기준으로 대화할 수 있습니다.

2. 준비물: Node, Vite, Wrangler, 계정 권한

작업 전에는 Node.js 버전, 패키지 매니저, Cloudflare 계정 권한, Wrangler 로그인 상태를 확인합니다. 이미 프로젝트가 npm, pnpm, yarn 중 무엇을 쓰는지도 정해야 합니다. 명령어가 섞이면 lock 파일이 늘어나고, 로컬과 배포 환경에서 의존성 차이가 생길 수 있습니다.

Cloudflare Workers 관련 작업은 대시보드에서 만든 프로젝트 정보와 로컬 설정 파일이 연결되어야 합니다. 보통 wrangler 설정 파일, Vite 설정 파일, package script가 함께 움직입니다. 저장소를 여러 사람이 다룬다면 누가 어떤 계정으로 preview를 보는지, 어떤 값은 저장소에 두지 않을지, 로컬 전용 파일은 무엇인지 먼저 정리해 두는 편이 좋습니다.

• Node.js와 패키지 매니저 버전을 팀 문서에 기록합니다.
• Vite 설정 파일 위치와 기존 플러그인 목록을 확인합니다.
• Wrangler 로그인 및 프로젝트 연결 상태를 확인합니다.
• 로컬 전용 값과 공유 가능한 예시 값을 분리합니다.
• 공식 문서의 명령어가 현재 프로젝트 구조와 맞는지 비교합니다.

3. 새 프로젝트와 기존 프로젝트의 설정 흐름

새 프로젝트라면 공식 get started 문서에서 안내하는 방식으로 시작하는 편이 가장 빠릅니다. 생성 명령으로 기본 구조를 만들고, 개발 서버를 실행해 Workers 런타임 메시지가 보이는지 확인합니다. 이때 중요한 것은 첫 성공 화면 자체보다 “어떤 스크립트가 어떤 파일을 읽는지”를 기록하는 일입니다. 나중에 프로젝트가 커지면 이 초기 구조가 문제 해결의 기준점이 됩니다.

기존 Vite 프로젝트는 조금 다릅니다. 먼저 현재 vite.config 파일에 이미 쓰는 플러그인과 빌드 옵션을 확인합니다. 그 다음 Cloudflare Workers Vite 플러그인을 추가하고, package script를 정리합니다. 기존 앱의 개발 서버가 정상 동작하는지, Workers preview에서 같은 화면이 보이는지, API 경로가 어긋나지 않는지 순서대로 비교합니다.

실무에서는 한 번에 모든 설정을 바꾸지 않는 것이 좋습니다. 플러그인 설치, 설정 파일 변경, 로컬 실행, 빌드 확인을 각각 커밋 단위로 나누면 원인 추적이 쉽습니다. 특히 팀원이 많은 저장소에서는 “Vite 기본 dev는 통과, Workers preview는 실패” 같은 상태를 분리해서 적어 두어야 담당자가 빠르게 이어받을 수 있습니다.

4. 로컬 프리뷰 명령 순서

기본 순서는 단순합니다. 의존성을 설치하고, 개발 서버를 실행하고, 빌드를 만들고, preview로 최종 동작을 확인합니다. 다만 프로젝트마다 스크립트 이름이 다를 수 있으므로 package.json의 scripts를 먼저 봐야 합니다. 공식 예시는 출발점이고, 실제 저장소의 스크립트가 최종 기준입니다.

로컬 프리뷰에서 첫 화면이 보이더라도 바로 완료로 보지 말아야 합니다. 새로고침, 직접 URL 접근, 폼 제출, API 요청, 정적 파일 경로, 브라우저 콘솔 오류를 함께 확인해야 합니다. 블로그 운영, 내부 도구, 랜딩 페이지처럼 단순해 보이는 앱도 라우팅 한두 곳에서 차이가 생길 수 있습니다.

5. 환경 변수와 로컬 전용 값 분리

Workers 프로젝트에서 자주 헷갈리는 부분은 환경 변수입니다. 로컬 개발 값, preview 값, 실제 배포 값이 섞이면 정상 화면이 우연히 뜨더라도 나중에 운영 과정에서 문제가 됩니다. 따라서 저장소에 넣을 예시 파일과 개인 로컬 파일, Cloudflare 쪽에서 관리할 값을 분리합니다.

예를 들어 공개되어도 되는 샘플 이름은 문서에 남길 수 있지만, 실제 토큰, 비밀 키, 서비스 연결 값은 저장소에 쓰지 않습니다. 팀원에게 공유해야 할 때도 값 자체가 아니라 어디에서 발급하고 어디에 넣는지 절차만 기록합니다. 이 글의 목적은 설정 흐름 안내이며, 민감한 계정 정보나 내부 운영 값은 각 팀의 규칙에 맞춰 관리해야 합니다.

또한 Vite 모드와 Cloudflare 환경 이름을 어떻게 대응시킬지도 정해야 합니다. 개발, 스테이징, 운영 같은 이름을 쓰는 팀이라면 preview가 어떤 값을 읽는지 표로 남기면 좋습니다. 이 표가 있어야 “내 PC에서는 되는데 팀원 PC에서는 안 된다”는 상황을 줄일 수 있습니다.

6. 배포 전 체크리스트

로컬 프리뷰가 통과했다면 배포 전에는 기능보다 재현성을 확인합니다. 같은 명령을 다른 팀원 PC나 CI 환경에서 돌렸을 때도 같은 결과가 나와야 합니다. 특히 Cloudflare Workers와 Vite가 빠르게 개선되는 도구이기 때문에 문서의 화면, 옵션 이름, 기본 동작이 달라질 수 있습니다.

아래 체크리스트는 글을 읽고 바로 실행할 수 있는 최소 점검표입니다.

• package.json scripts가 팀 문서와 일치하는가?
• Vite 설정 파일에 Cloudflare Workers 관련 설정이 명확히 남아 있는가?
• 로컬 개발 서버와 Workers preview에서 주요 URL이 모두 열리는가?
• 환경 변수 예시와 실제 값 관리 위치가 분리되어 있는가?
• 정적 파일, 이미지, 폰트 경로가 preview에서 깨지지 않는가?
• 빌드 경고를 무시하지 않고 별도 메모로 남겼는가?
• Cloudflare 공식 문서의 최신 안내와 현재 설정이 크게 어긋나지 않는가?

7. 팀 문서 템플릿으로 남기는 방법

이 설정은 한 번 성공하고 끝나는 작업이 아닙니다. 프로젝트에 새 팀원이 들어오거나, Cloudflare 설정을 바꾸거나, Vite 버전이 올라갈 때 다시 확인해야 합니다. 따라서 README나 내부 위키에 짧은 템플릿을 남기는 것이 좋습니다. 템플릿에는 설치 명령, 실행 명령, preview 명령, 자주 보는 오류 위치, 공식 문서 링크를 넣습니다.

문서에는 “현재 확인한 버전”도 같이 적습니다. 예를 들어 Node.js 버전, Vite 버전, Wrangler 버전, 확인 날짜를 남기면 나중에 화면이 달라졌을 때 원인을 좁히기 쉽습니다. 도구 화면과 명령 옵션은 언제든 바뀔 수 있으므로, 문서를 고정된 정답이 아니라 최신 확인 기록으로 다루는 편이 안전합니다.

운영 관점에서는 이 템플릿이 비용을 줄입니다. 같은 질문에 반복 답변하지 않아도 되고, preview 실패가 생겼을 때 담당자가 체크리스트를 따라가며 문제 범위를 좁힐 수 있습니다. 특히 외주, 파트타임, 여러 프로젝트를 오가는 팀에서는 이런 짧은 문서가 작업 품질을 크게 안정시킵니다.

8. 자주 막히는 지점과 해결 방향

첫 번째로 많이 막히는 부분은 포트와 서버 실행 상태입니다. 기존 Vite 서버가 이미 켜져 있거나 다른 도구가 같은 포트를 쓰면 preview 주소가 바뀔 수 있습니다. 이때는 콘솔에 표시된 실제 주소를 기준으로 확인해야 합니다. 문서에 적힌 기본 주소만 고집하면 문제를 놓치기 쉽습니다.

두 번째는 환경 변수입니다. 로컬에서는 값이 있는데 preview에서는 비어 있거나, 반대로 preview에서는 되는데 팀원 PC에서는 값이 없는 경우가 많습니다. 이런 경우 값 자체를 공유하기보다 “어떤 파일 또는 대시보드 위치에서 어떤 이름으로 넣어야 하는지”를 확인합니다.

세 번째는 라우팅입니다. 홈 화면은 열리지만 하위 주소 새로고침에서 실패하는 경우가 있습니다. SPA 라우팅, API 경로, 정적 파일 경로가 Workers 쪽 처리 방식과 맞는지 확인해야 합니다. 이때 브라우저 콘솔과 터미널 로그를 함께 봐야 원인을 좁힐 수 있습니다.

9. 수익화 관점에서 글을 확장하는 방향

이 키워드는 단순 개발 팁으로 끝내기보다 서버리스 배포, 도메인 연결, SSL, 로그 관리, 백업, 협업 문서화 같은 IT 운영 기초 콘텐츠로 확장하기 좋습니다. 독자는 “설정 하나”를 찾고 들어오지만, 실제로는 배포 전 확인 체계, 팀 문서, 운영 안정성까지 함께 필요로 합니다.

연관 글로는 Cloudflare Workers 배포 체크리스트, 도메인 연결 전 DNS 확인, 서버리스 함수 로그 확인, Vercel과 Cloudflare 배포 흐름 비교, 정적 사이트 preview 자동화 같은 주제를 붙일 수 있습니다. 단, 각 글은 실제 도구 사용법과 공식 문서를 기준으로 작성하고, 민감한 계정 정보나 내부 키를 노출하지 않는 선에서 설명해야 합니다.

10. 마무리: 로컬 프리뷰는 배포 전 안전장치다

Cloudflare Workers Vite 플러그인 로컬 프리뷰 설정의 핵심은 “배포 후에 알게 될 차이”를 개발 중에 먼저 보는 것입니다. 설치 명령을 따라 하는 것보다 중요한 것은 팀이 같은 순서로 확인하고, 같은 위치에 기록하고, 도구 변경을 주기적으로 반영하는 습관입니다.

마지막으로 한 번 더 강조하면, Cloudflare 대시보드 화면, Workers 기능 이름, Vite 플러그인 옵션, Wrangler 명령, 요금제별 제공 범위는 시간이 지나며 바뀔 수 있습니다. 실제 작업 전에는 공식 Cloudflare 문서와 현재 프로젝트의 package.json, 설정 파일, 계정 화면을 함께 확인하세요. 이 글은 업무 자동화와 IT 운영 관점의 실무 정리이며, 공개 배포 전 최종 판단은 팀의 운영 기준에 맞춰 진행하는 것이 좋습니다.

FAQ

Q1. Cloudflare Workers Vite 플러그인은 모든 Vite 프로젝트에 바로 넣어도 되나요?

기술적으로는 적용 가능한 경우가 많지만, 기존 프로젝트 구조에 따라 조정이 필요합니다. 먼저 현재 Vite 설정, 라우팅, API 호출, 정적 파일 경로를 확인한 뒤 작은 단위로 변경하는 것이 좋습니다.

Q2. npm run dev만 성공하면 배포 전 확인이 끝난 건가요?

아닙니다. 개발 서버 성공은 첫 단계입니다. build와 preview, 하위 URL 새로고침, 환경 변수, 브라우저 콘솔, 터미널 로그까지 함께 확인해야 합니다.

Q3. 로컬 전용 값은 어디에 적어야 하나요?

프로젝트 규칙에 따라 로컬 전용 파일이나 Cloudflare 설정 위치를 나눠야 합니다. 값 자체를 README에 넣기보다 변수 이름, 발급 위치, 입력 위치만 문서화하는 방식이 안전합니다.

Q4. 공식 문서와 내 화면이 다르면 어떻게 해야 하나요?

Cloudflare, Vite, Wrangler는 계속 바뀔 수 있습니다. 문서 날짜, 도구 버전, 계정 플랜, 프로젝트 종류를 함께 확인하고, 팀 문서에는 확인 날짜와 현재 동작 기준을 남기세요.

Q5. 이 설정은 비개발자 운영 담당자에게도 필요한가요?

직접 코드를 고치지 않더라도 preview 절차와 체크리스트를 이해하면 배포 전 검수, 오류 전달, 문서 관리가 쉬워집니다. 운영 담당자는 명령어 자체보다 확인 항목과 기록 양식을 알아두면 충분합니다.