Astro public과 dist 폴더는 무엇이 다른가

Astro 프로젝트에서 public과 dist를 열어보면 CNAME, .nojekyll, 이미지 같은 파일이 양쪽에 보여 같은 폴더처럼 느껴질 수 있다.

한 문장부터

public은 빌드에 넣을 정적 원본이고, dist는 소스와 정적 원본을 합쳐 만든 최종 배포 결과다.

src/ + public/
       ↓ astro build
      dist/

따라서 일반적인 Astro 프로젝트에서는 public을 Git에 보관하고 dist는 필요할 때 다시 생성한다.

public은 빌드 전 원본이다

public에는 Astro나 Vite가 변환하지 않고 그대로 제공해야 하는 파일을 둔다.

public/
  CNAME
  .nojekyll
  ads.txt
  favicon.svg
  images/

예를 들어 public/ads.txt는 개발 서버에서 /ads.txt로 접근할 수 있고, 빌드하면 dist/ads.txt로 복사된다.

Astro 공식 설정 문서도 publicDir의 기본값을 ./public로 정의하고, 그 안의 파일은 변환이나 번들링 없이 빌드 디렉터리로 복사한다고 설명한다.

dist는 빌드 후 결과다

dist에는 배포 서버가 실제로 제공할 파일이 모인다.

dist/
  index.html
  posts/
  _astro/
  CNAME
  .nojekyll
  ads.txt

여기에는 public에서 복사된 파일뿐 아니라 다음 결과도 함께 들어간다.

• src/pages에서 생성된 HTML
• 처리된 CSS와 JavaScript
• Astro가 생성한 자산
• RSS, sitemap, 검색 색인처럼 빌드 과정에서 만들어진 파일

Astro의 기본 빌드 출력 위치는 dist이며, outDir 설정으로 다른 위치를 지정할 수 있다.

왜 같은 파일이 양쪽에 있나

같은 CNAME이나 .nojekyll이 보이는 것은 중복 관리가 아니라 복사 전후를 함께 보고 있기 때문이다.

public/CNAME    ← 관리할 원본
dist/CNAME      ← 빌드하면서 복사된 결과

내용을 바꿔야 한다면 dist/CNAME이 아니라 public/CNAME을 수정해야 한다. dist만 고치면 다음 빌드에서 변경 내용이 사라진다.

무엇을 삭제해도 되나

보통 다음 기준으로 판단하면 된다.

.gitignore에 dist/가 있고 배포 과정에서 빌드를 다시 실행한다면 로컬 dist는 삭제해도 된다.

다만 로컬 빌드 결과를 미리 확인하거나, 호스팅 서비스에 dist를 직접 업로드하는 중이라면 작업이 끝날 때까지 유지할 수 있다.

놓치기 쉬운 점

• public에는 비밀 키나 비공개 설정을 두면 안 된다. 빌드 후 그대로 공개될 수 있다.
• dist를 직접 수정하지 않는다. 수정할 원본은 대부분 src 또는 public에 있다.
• 호스팅 설정의 publish directory가 기본값이라면 dist를 가리키는지 확인한다.
• outDir이나 publicDir을 바꾼 프로젝트는 폴더 이름보다 실제 Astro 설정을 기준으로 판단한다.

관련 글

• Astro 이미지 관리, public과 src/assets는 언제 나눠야 할까
• Astro dev에서는 되는데 build 후 깨질 때 보는 순서
• Astro configuration reference: publicDir과 outDir
• Astro 배포 문서

한 줄 요약

public은 Git에 보관할 정적 원본이고 dist는 빌드할 때 다시 만들 수 있는 최종 배포 결과다.