Feb 2, 2026

마지막 업데이트 Apr 9, 2026

Vercel 배포 가이드: Astro와 프런트엔드를 놀라움 없이 운영 배포하는 법

많은 프런트엔드 프로젝트는 로컬에서는 이미 끝난 것처럼 느껴지지만, 공개 운영 배포까지 가면 전혀 다른 종류의 문제가 나타납니다.

Vercel이 유용한 이유는 배포 자체를 빠르게 만들어주기 때문입니다. 하지만 초록색 배포 배지가 떴다고 해서 곧바로 운영 준비가 끝난 것은 아닙니다. 이 블로그를 처음 Vercel에 올렸을 때 Preview에서는 멀쩡했는데 Production에서 광고 스크립트가 안 붙었습니다. 원인은 PUBLIC_GOOGLE_ADSENSE_CLIENT 환경 변수가 Preview에만 있고 Production에는 안 넣어둔 것이었습니다. 그 이후로 “Preview 성공 ≠ Production 준비 완료”를 팀 원칙으로 삼게 됐습니다. 실제로는 build 모델, 환경 변수, Preview 동작, custom domain, 배포 후 검증 루틴이 모두 같은 공개 시스템을 설명해야 합니다.

이 글은 블로그, 문서 사이트, 대시보드, Astro 프런트엔드에 맞는 실전 가이드입니다.

정적 Astro가 언제 기본 설정만으로 충분한지
언제 Astro Vercel adapter가 필요한지
Preview와 Production은 무엇이 다른지
왜 환경 변수와 도메인에서 “로컬에선 되는데” 문제가 반복되는지
무엇을 확인해야 배포가 정말 끝난 것인지

짧게 말하면 렌더링 모델을 먼저 정하고, Preview와 Production을 다른 환경으로 다루고, 공개 도메인을 의도적으로 구성하고, green deploy보다 실제 라이브 사이트 검증을 더 믿는 것이 핵심입니다.

Quick answer

Astro나 일반 프런트엔드를 Vercel에 배포할 때 가장 실전적인 순서는 보통 이렇습니다.

프로젝트가 완전 정적인지, 서버 기능이 필요한지 먼저 정한다
build 명령, output, Node 버전을 명시적으로 확인한다
로컬 .env를 믿지 말고 환경 변수를 환경별로 넣는다
Preview deployment를 진짜 검증용으로 쓴다
apex 도메인과 www를 함께 추가하고 공개 호스트를 하나 정한다
배포 후 홈, 핵심 route, 메타데이터, robots.txt, sitemap, domain redirect를 직접 확인한다

여기가 약하면 배포는 “성공”했는데 실제 운영 사이트는 아직 준비되지 않은 경우가 많습니다.

먼저 Astro 배포 모델을 고르기

Vercel의 Astro 문서에서 가장 중요한 포인트 하나는 꽤 분명합니다.

정적으로 렌더되는 Astro 앱은 zero configuration으로 배포할 수 있다
Web Analytics, Image Optimization, 서버 렌더링 같은 Vercel 기능을 쓰려면 Astro의 Vercel adapter가 필요하다

즉 첫 질문은 “어디서 import하지?”가 아니라:

이 사이트는 완전 정적인가
아니면 SSR, ISR, middleware, Vercel runtime 기능이 필요한가

입니다.

일반적인 콘텐츠 블로그라면 정적 배포가 가장 안전한 기본값인 경우가 많습니다.

조금 더 동적인 앱이라면 이 결정을 초기에 해야 합니다. adapter, routing, runtime 가정이 같이 바뀌기 때문입니다.

깔끔한 첫 배포 흐름

대부분의 프로젝트에서 건강한 첫 배포는 이런 순서입니다.

저장소를 Git에 올린다
Vercel로 프로젝트를 import한다
감지된 framework와 build 설정을 확인한다
환경 변수를 올바른 환경에 추가한다
Preview build부터 만든다
Preview에서 실제 동작을 검증한다
그다음에야 Production으로 배포하거나 promote한다

Vercel은 배포 루프를 빠르게 만들어주지만, 검증 루틴이 붙어 있을 때만 그 속도가 진짜 장점이 됩니다.

Preview와 Production은 같은 것이 아니다

Vercel 환경 문서는 기본 환경이 세 가지라고 설명합니다.

Local
Preview
Production

당연해 보이지만, 많은 팀이 여전히 Preview를 Production의 미리보기 정도로만 다룹니다. 실제로는 그렇지 않습니다.

Vercel 문서에 따르면 Preview deployment는 보통 이런 경우 만들어집니다.

production branch가 아닌 브랜치에 push했을 때
pull request를 열었을 때
CLI에서 -prod 없이 배포했을 때

또 Preview URL도 두 종류가 있습니다.

branch-specific URL
commit-specific URL

이 말은 Preview가 단순히 “예쁜 localhost”가 아니라는 뜻입니다. production 트래픽이 보기 전에 실제 배포 결과를 검증하는 공간입니다.

환경 변수는 머릿속이 아니라 환경별로 모델링하기

Vercel 환경 변수 문서는 값이 Development, Preview, Production별로 다르게 들어갈 수 있고, 변경사항은 이전 배포에 소급 적용되지 않고 새 배포부터만 반영된다고 설명합니다.

이 지점에서 실수가 자주 납니다.

1. 로컬 값이 Vercel에도 있을 거라고 생각하는 경우

그렇지 않습니다. 개발 머신에서는 멀쩡한 프로젝트가 Preview나 Production에서 바로 실패하는 가장 흔한 이유입니다.

2. Preview가 Production과 같을 거라고 생각하는 경우

꼭 그렇지 않습니다. Vercel은 Preview와 Production 변수 세트를 분리할 수 있고, branch-specific Preview 변수는 공통 Preview 변수 위에 덮어쓸 수도 있습니다.

즉 Preview가 멀쩡해 보여도, Production 값이 다르면 운영 배포는 여전히 깨질 수 있습니다.

로컬 동기화에 유용한 명령:

vercel link
vercel env pull

이런 흐름을 써야 기억에 의존한 로컬 가정 대신, 실제 Vercel 프로젝트 기준으로 개발할 수 있습니다.

Preview를 믿되, Production은 별도 이벤트로 보기

이 흐름에서 가장 중요한 Vercel 문서 중 하나가 Preview promotion 가이드입니다.

Vercel은 Preview deployment를 Production으로 promote하면, Production 환경 변수로 완전히 다시 build한다고 설명합니다.

이 한 줄이 중요합니다.

즉:

Preview는 아주 좋은 리허설이다
하지만 Production 변수셋이 다르면 여전히 Production에서만 깨질 수 있다

그래서 가장 안전한 사고방식은 이겁니다.

Preview에서 동작을 충분히 검증하고
Production 가정을 한 번 더 확인한 다음
promote를 진짜 운영 배포 이벤트로 다룬다

Vercel은 vercel promote, vercel rollback 흐름도 함께 제공합니다. 잘못 올린 배포를 빨리 되돌리는 운영 선택지가 있다는 점도 중요합니다.

custom domain은 배포의 일부다

Vercel custom domain 문서는 apex 도메인인 example.com을 추가하면 www도 함께 추가하도록 유도한다고 설명합니다.

같은 문서는 일반적인 DNS 구성도 명확히 적고 있습니다.

apex 도메인: A 레코드
www 같은 서브도메인: CNAME

이 구간은 Vercel 안에서는 끝난 것처럼 보이는데, 실제 사용자 입장에서는 아직 망가져 있는 상태가 가장 자주 생기는 부분입니다.

예를 들어 공개 호스트를 정해야 합니다.

https://example.com
또는 https://www.example.com

그다음 다른 호스트는 그쪽으로 깔끔하게 redirect되어야 합니다.

이 선택은 아래와 모두 맞아야 합니다.

브라우저 URL
canonical URL
sitemap URL
robots.txt
ads.txt

호스트 이야기가 갈라져 있으면, 그 배포는 아직 끝난 것이 아닙니다.

배포 직후 바로 확인할 것

이 단계를 가장 많이 생략합니다.

기술 블로그나 콘텐츠 프런트엔드라면 배포 직후 최소한 아래를 확인하는 편이 좋습니다.

production URL이 열린다
대표 글이나 핵심 route가 정상 렌더링된다
custom domain이 HTTPS로 열린다
모바일 레이아웃과 navigation이 정상이다
canonical과 소셜 메타데이터가 맞다
robots.txt와 sitemap-index.xml이 열린다
배포가 정상적으로 완료됐는지 최종 확인한다

간단한 확인 명령:

curl -I https://www.example.com/
curl https://www.example.com/robots.txt
curl https://www.example.com/sitemap-index.xml
curl -I https://www.example.com/ads.txt

Astro 블로그에서는 이 검증 루틴이 “프로젝트가 빌드됐다”와 “사이트가 운영 준비가 됐다”를 갈라주는 핵심입니다.

Astro에서 특히 가치가 큰 점검 포인트

Astro 기반이라면 이 네 가지는 특히 효율이 좋습니다.

1. production `site` 값 확인

site 값이 틀리면 sitemap, canonical, 관련 메타데이터가 한 번에 다른 호스트를 가리킬 수 있습니다.

2. 정말 `@astrojs/vercel`이 필요한지 확인

정적 Astro는 Vercel에서 기본값만으로도 잘 배포됩니다. 서버 기능, Image Optimization 연동, ISR이 필요한지 먼저 의도적으로 결정하는 편이 좋습니다.

3. 이미지 동작 확인

Vercel Astro 문서는 Astro의 Image 컴포넌트를 쓸 때 Image Optimization이 out of the box로 지원된다고 설명합니다. 그래도 실제 배포 후 렌더된 이미지 URL, 크기, 페이지 출력을 직접 확인하는 편이 안전합니다.

4. 컴포넌트 코드보다 최종 HTML 확인

블로그는 메타데이터 문제가 배포 결과에서만 드러나는 경우가 많습니다.

확인할 것:

<link rel="canonical">
hreflang
title과 description
JSON-LD
OG 이미지 URL

흔한 배포 실수

1. 정적 배포와 서버 배포를 같은 문제로 보는 경우

앱이 runtime 기능을 필요로 하는데 순수 정적 사이트처럼 올리면, 그 불일치는 나중에 더 크게 드러납니다.

2. 환경 변수 가정을 머릿속에만 두는 경우

Preview와 Production 변수 모델이 분명하지 않으면, 결국 다른 환경을 보고 디버깅하게 됩니다.

3. Preview를 선택사항처럼 다루는 경우

Preview는 Vercel의 가장 강한 운영 기능 중 하나입니다. 이걸 건너뛰면 layout, metadata, env 실수를 잡을 가장 안전한 지점을 잃습니다.

4. domain 설정을 나중 문제로 미루는 경우

앱 코드는 배포됐어도, 공개 호스트와 HTTPS, redirect가 틀리면 사용자 입장에서는 여전히 깨진 서비스입니다.

5. `Deployment Ready`에서 멈추는 경우

초록색 상태는 Vercel이 무언가를 빌드해서 공개했다는 뜻이지, 사용자가 보기 좋은 운영 사이트가 되었다는 뜻은 아닙니다.

실전 운영 순서

가장 적게 흔들리는 배포 루프는 보통 이런 순서입니다.

렌더링 모델을 정한다
build와 output 설정을 확인한다
환경 변수를 환경별로 구성한다
Preview를 배포한다
Preview에서 실제 route를 검증한다
Production domain과 DNS 구성을 확인한다
Production으로 배포하거나 promote한다
라이브 공개 호스트를 다시 검증한다
문제 시 rollback 경로를 염두에 둔다

이 순서는 “일단 배포하고 보자”보다 느려 보이지만, 깨진 공개 배포를 수습하는 것보다는 훨씬 빠릅니다.

FAQ

Q. 정적 Astro 사이트는 정말 별도 설정 없이 Vercel에 올라가나요?

대개는 그렇습니다. Vercel Astro 문서도 statically rendered Astro apps는 zero configuration으로 배포할 수 있다고 설명합니다. adapter는 서버 기능이나 Vercel 전용 기능을 쓸 때 필요해집니다.

Q. Preview는 멀쩡한데 Production만 깨질 수 있나요?

네. Production 승격 시 Production 환경 변수로 다시 빌드되기 때문입니다.

Q. apex와 `www`를 둘 다 추가해야 하나요?

대부분은 그렇습니다. Vercel도 apex 도메인을 추가할 때 www 추가를 유도합니다. 이후 한쪽을 공개 호스트로 정하고 다른 쪽은 그쪽으로 정리하면 됩니다.

Q. 잘못 배포했을 때 가장 빠른 복구 방법은 뭔가요?

Vercel rollback 흐름으로 서비스를 먼저 복구하고, 깨진 배포는 별도로 분석하는 편이 가장 안전합니다.

Official References

먼저 읽어볼 가이드

검색 유입이 많은 핵심 글부터 이어서 보세요.