Claude Code로 Vercel과 Cloudflare에 앱 배포하기 (2026)

Claude Code로 배포한다는 게 무슨 뜻일까요? 혼자서 배포할 수 있나요?

방금 Claude Code로 Next.js 앱이나 정적 사이트를 만들었고 이제 웹에 올리고 싶다면 좋은 소식이 있어요. 터미널을 벗어날 필요가 전혀 없어요. Claude Code로 배포한다는 건 셸 명령어를 대신 실행하게 한다는 뜻이에요. 플랫폼 CLI를 설치하고, 로그인하고, 빌드를 실행하고, 코드를 푸시한 다음, 로그를 읽어 오류를 반복적으로 잡아 고치는 거죠.

핵심은 이거예요. Claude Code는 진짜 터미널 명령어를 실행해요. 흉내만 내는 게 아니에요. "이 프로젝트를 Vercel에 배포해"라고 하면 실제로 vercel --prod를 호출하고, 결과를 기다리고, 빌드가 실패하면 오류 메시지를 읽어 수정안을 제안해요. 바로 이 점이 블로그 글에서 명령어를 복사해 붙여넣는 것과 다른 부분이에요. 이 도구가 처음이라면 먼저 Claude Code가 무엇인지 훑어보면서 샌드박스에서 명령어를 어떻게 실행하는지 이해해 보세요.

하지만 "마법처럼 배포"하는 건 아니에요. 사람이 여전히 해야 할 세 가지가 있어요.

• Vercel이나 Cloudflare 계정이 필요해요(처음엔 무료 플랜으로 충분해요).
• 처음에는 로그인 단계에서 보통 브라우저가 열려 직접 확인해요. Claude Code가 여러분 계정에 대신 로그인해 주지는 않아요.
• 플랫폼, 도메인, 환경 변수는 직접 정해요. AI가 제안은 할 수 있지만 결정은 여러분이 해요.

정리하면, AI는 반복되는 명령어 작업과 성가신 로그 읽기를 맡고, 여러분은 결정과 계정을 맡아요. 이 역할 분담을 제대로 이해하면 기대치가 현실적으로 유지돼요.

손으로 배포하는 대신 이렇게 할 가치가 있는 이유가 뭘까요? 실용적인 이유가 세 가지예요. 첫째, 각 플랫폼의 명령어를 외울 필요가 없어요. vercel과 wrangler는 문법이 다르고 둘 다 꽤 빠르게 바뀌어요. 둘째, 수정 루프가 짧아져요. 빌드가 실패하면 여러분이 오류를 복사해 웹에서 검색하는 대신 AI가 바로 그 자리에서 로그를 읽어요. 셋째, 맥락이 그대로 유지돼요. Claude Code는 방금 앱을 빌드한 바로 그 폴더에 있어서 프로젝트 구조, 사용한 프레임워크, 출력물이 어디 있는지 알아요. 여러분 코드를 전혀 모르는 가이드에서 명령어를 붙여넣는 것과는 큰 차이죠.

배포 전에(체크리스트)

배포가 매끄럽게 진행되는지는 대부분 준비 단계에서 결정돼요. Claude Code에게 앱을 프로덕션으로 푸시하라고 지시하기 전에 다음을 모두 확인하세요.

• ✓ 깨끗한 git 저장소: 모두 커밋되어 있고 남은 변경이 없어야 해요. 이 부분이 처음이라면 Claude Code와 함께하는 git 워크플로를 참고하세요.
• ✓ 여러분 컴퓨터에서 npm run build가 성공해야 해요. 이게 첫 번째 조건이에요. 로컬에서 빌드가 실패하면 서버에서는 반드시 실패해요. "그냥 어떻게 되나 보려고" 배포하지 마세요.
• ✓ 프레임워크를 파악하기: Next.js, Vite/React, 또는 정적 HTML. 종류에 따라 플랫폼과 배포 명령어가 달라요.
• ✓ Vercel이나 Cloudflare에 계정을 가지고 있기.
• ✓ .gitignore가 이미 .env와 잠금 파일을 막고 있기. 이 줄을 다시 한번 확인하세요.

보안 경고: Claude Code가 .env나 API 키를 git에 커밋하게 두지 마세요. git add -A를 실행하게 하기 전에 .gitignore에 .env와 .env.local이 들어 있는지 확인하세요. 비밀 값은 코드가 아니라 플랫폼 대시보드나 wrangler secret에 있어야 해요.

앱에 서버 사이드(API 라우트, 데이터베이스)가 있다면 Claude Code로 백엔드와 API 만들기도 읽어 두면 좋아요. 프로덕션에 올리기 전에 앱이 어떤 환경 변수를 필요로 하는지 알 수 있거든요. 이 목록을 제대로 갖추면 아래 배포 단계는 보통 몇 분이면 끝나요.

방법 1 - Claude Code로 Vercel에 배포하기

Vercel은 Next.js와 SSR 앱에 가장 매끄러운 선택이에요. 많은 부분이 거의 "클릭하면 끝"이죠. Claude Code에게 한 단계씩 실행시킬 수 있는 CLI 흐름은 이래요.

1. Vercel CLI 설치: npm i -g vercel
2. 로그인: vercel login - 브라우저가 열려 인증해요(직접 하는 단계예요).
3. 프로젝트 연결: vercel link - 현재 폴더를 Vercel의 프로젝트에 연결해요.
4. 프리뷰 만들기: vercel(플래그 없이)을 실행해 프리뷰 URL을 빌드하고 먼저 확인해요.
5. 환경 변수 설정: Vercel 대시보드나 vercel env add VAR_NAME으로 설정해요.
6. 프로덕션에 배포: vercel --prod.

Claude Code에서는 위 명령어를 하나하나 입력할 필요가 없어요. 이런 프롬프트면 충분해요.

Deploy this project to Vercel. Run vercel link first,
create a preview for me to check, then ask me before
running vercel --prod. If the build fails, read the
log and suggest a fix.

Claude Code는 명령어 체인을 실행하고, 여러분이 볼 수 있도록 프리뷰에서 멈추고, 여러분이 승인해야만 프로덕션에 배포해요. 빌드가 실패하면 오류 출력을 읽어 고쳐요. 바로 여기서 "AI가 로그를 읽는" 것이 눈에 띄게 시간을 아껴줘요.

2026년 새 소식: Vercel에는 공식 Claude Code 플러그인과 Vercel MCP 커넥터가 있어서 Claude Code가 Vercel과 더 깔끔하게 연동돼요(프로젝트 관리, 배포 읽기). Vercel에 자주 배포한다면 둘 다 써 볼 만해요.

Next.js/SSR에서는 Vercel의 큰 장점이 런타임을 거의 설정하지 않아도 된다는 거예요. 프레임워크가 자동으로 감지되고 "그냥 배포"하면 돼요. Server Components, API 라우트, 미들웨어가 모두 어댑터 없이 동작해요. 트레이드오프는 트래픽이 많으면 비용이 금방 올라갈 수 있다는 점이에요(아래 비교 표 참고).

프리뷰를 제대로 쓰기: --prod 전에 항상 vercel(프리뷰)을 실행하세요. 프리뷰는 전용 URL을 갖고, 곧 배포할 바로 그 코드를 쓰지만 실제 사용자에게는 영향을 주지 않아요. 그 URL을 열어 핵심 흐름 몇 가지를 클릭해 보고, 그다음에야 Claude Code가 프로덕션에 푸시하게 하세요. 망가진 빌드를 메인 도메인에 올리는 걸 막아주는, 비용이 낮은 습관이에요.

방법 2 - Claude Code로 Cloudflare에 배포하기(Pages와 Workers)

Cloudflare는 저렴하게, 엣지에서 돌리거나, Workers로 풀스택(KV, D1, R2)으로 만들고 싶을 때 맞아요. 주요 도구는 wrangler예요. 단계는 이래요.

1. Wrangler 설치: npm i -g wrangler(한 번만 쓸 거면 npx wrangler도 좋아요).
2. 로그인: wrangler login - 브라우저가 열려 인증해요.
3. 앱 빌드: npm run build로 출력 폴더를 만들어요.
4. Pages 배포: wrangler pages deploy <build-folder>(예: Vite면 dist, 또는 사용하는 프레임워크의 빌드 폴더).
5. 비밀 값 설정: wrangler secret put SECRET_NAME이나 대시보드로 설정해요. 절대 코드에 하드코딩하지 마세요.
6. 도메인 + SSL 연결: 대시보드에서 커스텀 도메인을 추가하면 Cloudflare가 SSL을 자동으로 발급해요.

Claude Code용 샘플 프롬프트예요.

Build this app and deploy it to Cloudflare Pages with wrangler.
After it deploys, show me the .pages.dev URL so I can check it.
Remind me which secrets I need to set with wrangler secret put.

Cloudflare에서 Next.js를 쓸 때의 함정(꼭 읽으세요): Next.js는 Vercel에서처럼 Cloudflare Pages/Workers에서 바로 돌지 않아요. 어댑터 계층이 필요해요.

• @cloudflare/next-on-pages - Next.js를 Cloudflare Pages용으로 빌드해 엣지 런타임에서 돌리는 어댑터예요.
• OpenNext(@opennextjs/cloudflare) - 더 새로운 방향으로, 복잡한 Next.js 앱을 위해 Workers의 Node 런타임을 더 잘 지원해요. Cloudflare용 OpenNext 문서를 참고하세요.

둘 다 보통 설정에서 Node 호환 플래그(nodejs_compat)를 켜야 해요. 그 단계를 건너뛰면 알아보기 힘든 런타임 오류를 만나요. 바로 이 부분을 Vercel만 다루는 가이드가 빼먹죠. Claude Code에게 이렇게 말할 수 있어요. "이 앱은 Next.js야. OpenNext로 Cloudflare에 배포하고 nodejs_compat를 켜 줘."

Cloudflare에는 AI 에이전트를 Cloudflare 인프라에 연결하는 방법을 설명하는 Claude Code용 agent-setup 문서도 있어요. 동적 로직(데이터베이스, 캐시, 파일 저장)에는 모든 걸 정적 Pages에 욱여넣는 대신 Workers를 KV/D1/R2와 함께 쓰세요. KV는 빠른 키-값, D1은 SQL 데이터베이스, R2는 이그레스 비용이 없는 S3 방식의 오브젝트 스토리지예요. Claude Code에게 wrangler.toml에서 이 서비스들에 대한 바인딩을 만들게 하고 그에 맞는 읽기/쓰기 코드를 작성하게 할 수 있어요.

Vercel과 비교하면 Cloudflare의 트레이드오프는 설정이 조금 더 필요한 대신 더 큰 유연성과 규모가 커질 때의 더 낮은 비용이에요. 앱이 그냥 정적/SPA라면 트레이드오프가 거의 없어요. Pages가 빌드 폴더를 받아 곧바로 엣지에서 제공하거든요. 어댑터의 복잡함이 정말 드러나는 건 Next.js SSR에 이르렀을 때뿐이에요.

Vercel일까요, Cloudflare일까요? 플랫폼 고르기 표

"최고의 플랫폼"이란 없어요. 여러분 앱의 종류에 맞는 것만 있을 뿐이죠. 아래 표는 Claude Code가 만든 프로젝트 종류에 따라 빠르게 고르도록 도와줘요.

빠른 결론: Vercel은 가장 적게 고민하면서 가장 매끄러운 Next.js 경험을 주고, Cloudflare는 낮은 비용, 엣지, Workers로 풀스택을 줘요. 둘 다 개인 앱이나 사이드 프로젝트에는 충분한 무료 플랜이 있어요. 잘 모르겠으면 두 무료 플랜에서 시작해 Claude Code가 각각에 배포하게 한 뒤 비교해 보세요.

흔한 배포 오류 다루기

배포가 첫 시도에 깔끔하게 통과하는 일은 드물어요. 여기서 Claude Code의 강점은 배포 로그를 읽고 반복해서 고치는 거예요. 오류를 붙여넣거나 그냥 "그 출력을 읽고 고쳐"라고 하면 돼요. 가장 자주 만나는 오류와 대처법은 이래요.

• 첫 빌드가 실패해요. 보통 빠진 의존성이나 잘못된 빌드 스크립트 때문이에요. Claude Code에게 이렇게 말하세요. "방금 실패한 빌드 로그를 읽고, 빠진 의존성이나 package.json의 잘못된 스크립트를 찾아 고쳐." 이건 가장 흔한 오류이면서 고치기도 가장 쉬워요.
• 환경 변수 누락 → 앱은 배포되지만 빈 페이지나 500이 떠요. 대시보드에 변수가 설정되어 있는지 확인하세요. .env의 로컬 변수는 저절로 서버로 넘어가지 않는다는 걸 기억하세요.
• Cloudflare에서의 Next.js 엣지 런타임 오류. 신호: "module not found"나 존재하지 않는 Node API. 해결: @cloudflare/next-on-pages나 OpenNext를 쓰고 nodejs_compat를 켜세요(위 Cloudflare 섹션 참고).
• Node 버전 불일치. 로컬은 Node 20을 쓰는데 서버 기본값은 다른 것 → 빌드 결과가 달라져요. 프로젝트 설정이나 package.json(engines)에 버전을 명시하세요.
• 실수로 비밀 값을 커밋했어요. API 키가 git에 들어갔다면 즉시 키를 회전(폐기 후 재발급)하세요. 커밋을 지우는 것만으론 부족해요. 키가 이미 히스토리에 노출됐거든요. 그런 다음 비밀 값을 원래 있어야 할 대시보드/wrangler secret로 옮기세요.

(플랫폼 쪽이 아니라) Claude Code 세션 안에서 오류를 만났다면 흔한 Claude Code 오류를 참고하세요. 일반적인 팁: 무턱대고 다시 배포하지 마세요. 뭔가 고치기 전에 항상 AI가 해당 로그를 읽게 하세요.

자동화하기: git push → 라이브(CI/CD와 프리뷰)

수동 CLI 배포는 처음엔 훌륭하지만, 길게 보면 모든 git push가 자동으로 라이브가 되길 원하게 돼요. Vercel과 Cloudflare Pages 둘 다 GitHub 저장소에 직접 연결하는 걸 지원해요.

• 저장소 연결: 플랫폼 대시보드에서 연결하면 → main 브랜치로의 모든 푸시가 프로덕션에 자동 배포돼요.
• 프리뷰 배포 = 진짜 QA. 모든 풀 리퀘스트가 전용 프리뷰 URL을 받아서 머지 전에 여러분(또는 리뷰어)이 확인할 수 있어요. 거의 공짜 QA니까 건너뛰지 마세요.
• 한 번의 명령으로 롤백. 새 빌드가 망가지면 대시보드에서 거의 즉시 이전 것으로 롤백해요. 당황할 필요 없어요.

설정 파일도 Claude Code에게 쓰게 할 수 있어요. Vercel은 vercel.json, Cloudflare는 wrangler.toml, 파이프라인을 세밀하게 제어하고 싶으면 GitHub Actions 워크플로예요. Claude Code와 함께하는 git 워크플로와 결합하면 코드 → 푸시 → 프리뷰 → 머지 → 라이브라는 촘촘한 개발 루프가 생겨요.

미리 만들어진 스킬로 더 빠르게 배포하기(ak-deploy)

각 vercel/wrangler 명령어를 외워서 입력하는 대신, 미리 만들어진 배포 스킬을 쓸 수 있어요. ak-deploy는 프로젝트 설정이나 docs/deployment.md 파일에서 배포 대상을 자동으로 감지해요. Vercel, Cloudflare, Netlify, Railway, Fly.io 등 많은 걸 지원하니 보통 "이 앱을 배포해" 한 문장이면 알맞은 흐름을 골라줘요. 더 무거운 인프라(Cloudflare Workers/R2/D1, Docker, Kubernetes)는 ak-devops가 그쪽을 맡아요.

이 스킬들은 Engineer Kit(ak-deploy 스킬 포함)에 들어 있어요. 이건 Claude Code용 AgentKit 번들 — 현재 $149($198에서)의 일부예요(agentkit.best, ak CLI 사용). 혼동을 피하려고 분명히 해 두면, 이건 AgentKit, 즉 Claude Code용 스킬/에이전트 팩이고 OpenAI의 AgentKit과는 완전히 달라요. Engineer Kit은 $99(페이지에 반복 결제 안내는 없어요)이고, 평생 업데이트와 환불 보장이 있어요. Claude Code에서 스킬이 어떻게 동작하는지 먼저 이해하고 싶다면 Claude Code의 스킬이란 무엇인지를 참고하세요.

자주 묻는 질문(FAQ)

Claude Code는 혼자서 배포할 수 있나요?

네 - Claude Code는 진짜 터미널 명령어를 실행하니까 vercel/wrangler를 대신 실행해요. CLI 설치, 빌드, 배포, 그리고 로그를 읽어 오류를 고치는 것까지요. 다만 Vercel/Cloudflare 계정은 여전히 필요하고 처음 로그인은 직접 해야 해요.

Vercel과 Cloudflare 중 뭐가 더 싸고, 무료로 쓸 수 있나요?

둘 다 개인 앱이나 사이드 프로젝트에는 충분한 무료 플랜이 있어요. Cloudflare는 트래픽이 많을 때와 정적/엣지 앱에서 더 저렴한 편이고, Vercel은 Next.js/SSR에서 더 매끄러워요. 규모를 키우기 전에 정확한 한도는 가격 페이지에서 확인하세요.

Next.js를 Cloudflare에 배포하려면 뭐가 필요한가요?

Next.js는 Cloudflare에서 바로 돌지 않아요. @cloudflare/next-on-pages 어댑터나 OpenNext(@opennextjs/cloudflare)가 필요하고, 보통 Node 호환 플래그(nodejs_compat)를 켜야 해요. Vercel에서는 이 단계가 필요 없어요.

Claude Code가 제 비밀 값을 유출할 수 있나요?

여러분이 .env/API 키를 git에 커밋하게 두는 경우에만요. 막으려면 .env를 .gitignore에 추가하고 비밀 값은 대시보드나 wrangler secret put으로 불러오세요. 키가 유출되면 이미 git 히스토리에 있으니 곧바로 회전(재발급)하세요.

정적 HTML을 가장 빠르게 배포하는 방법은?

정적 사이트라면 가장 빠른 길은 wrangler pages deploy <folder>로 Cloudflare Pages에 배포하거나, 프로젝트 폴더에서 vercel을 실행하는 거예요. Claude Code에게 명령어를 실행하게 하고 확인용 라이브 URL을 건네받으세요.

새 빌드가 망가지면 어떻게 롤백하나요?

Vercel과 Cloudflare Pages 둘 다 대시보드에서 거의 즉시 이전 배포로 롤백할 수 있어요. 각 배포가 그 자체로 불변 빌드라서 롤백이 아주 안전하고, 다시 빌드할 필요가 없어요.

결론과 다음 단계

Claude Code로 배포하는 건 한 가지 원칙으로 요약돼요. AI가 명령어를 실행하고 로그를 읽게 하고, 여러분은 플랫폼과 계정을 정하는 거예요. Next.js와 매끄러운 DX에는 Vercel을, 저렴함·엣지·Workers 풀스택에는 Cloudflare를 고르세요. 깨끗한 저장소, 로컬에서 돌아가는 빌드, git 밖에 둔 비밀 값을 갖추면 이미 문제의 80%는 피한 거예요.

다음 단계: 앱에 서버 사이드가 있다면 Claude Code로 백엔드와 API 만들기를, 푸시-투-라이브를 자동화하려면 Claude Code와 함께하는 git 워크플로를 참고하세요.