﻿---
title: "사용 가이드 8: 내 도메인에 블로그 배포하기"
description: "Anglefeint 정적 배포, 도메인과 환경 덮어쓰기, 빌드·이미지 파일, 검색과 공개 내보내기, 선택적인 GA4 연결을 설명합니다."
url: "https://demo.anglefeint.com/ko/blog/starter-guide-deployment/"
language: "ko"
author: "Anglefeint"
published: "2026-11-13T00:00:00.000Z"
updated: "2026-11-14T00:00:00.000Z"
---

# 사용 가이드 8: 내 도메인에 블로그 배포하기

**버전 안내:** build와 CI doctor의 자동 이미지 준비는 0.36.2부터 지원합니다. 0.36.1에서는 dev 또는 `prepare-covers`로 먼저 준비하세요.

이 글은 입문 가이드의 8 / 8편입니다. [전체 가이드 순서](https://demo.anglefeint.com/ko/blog/starter-guide-1-configure-your-site/#tutorial-order) · [필드별 설정 사전](https://demo.anglefeint.com/ko/blog/config-reference/).

로컬에서 블로그를 열 수 있다면 게시에는 세 가지가 필요합니다. 최종 도메인 확인, 완전한 정적 파일 생성, 호스팅 서비스가 그 도메인에서 파일을 제공하도록 설정하는 일입니다. 테마가 도메인을 구매하거나 DNS를 수정하거나 호스팅에 자동 로그인하지는 않습니다.

현재 starter는 기본적으로 정적 사이트를 빌드합니다. 운영 환경에서 Node.js를 계속 실행하거나 정적 배포를 위해 SSR adapter를 추가할 필요는 없습니다. 아래는 npm 프로젝트와 기본 출력 디렉터리 `dist/`를 기준으로 합니다.

## 1\. 정식 사이트 주소 정하기

`https://blog.example.com`처럼 직접 관리하는 도메인을 준비하고 `src/site.config.ts`의 기존 최상위 `site`에 합치세요.

```ts
site: {
  url: 'https://blog.example.com',
},
```

외부에서 최종 접근할 주소를 입력하세요. localhost, 특정 글 주소, 호스팅 콘솔 주소는 안 됩니다. 나머지 사이트 정보는 유지하세요.

이 값은 canonical, RSS, sitemap, 공유 이미지, 공개 콘텐츠 링크에 사용합니다. 로컬 개발 서버 주소는 바꾸지 않으며 아직 연결하지 않은 도메인을 사이트로 자동 연결하지 않습니다.

### 이전 환경 덮어쓰기 확인하기

프로젝트 `.env`, 적용되는 `.env.*`, 호스팅 빌드 환경의 `PUBLIC_SITE_URL`은 설정 파일보다 우선합니다. site.url만 바꿨는데 예전 도메인이 나온다면 이 위치들을 함께 확인하세요. 일반 dev는 development, 일반 build는 production 모드입니다. 사용자 `--mode`는 해당 모드 설정도 읽으므로 `.env`만 확인하면 안 됩니다.

덮어쓰기가 필요 없다면 변수를 제거하고 site.url로 통일하세요. 환경 구분이 필요하다면 각 빌드 환경에 올바른 값을 설정하세요. 수정 뒤 다시 빌드해야 하며 이전 산출물의 링크 하나만 직접 바꾸면 안 됩니다.

### 도메인 루트 사용하기

현재 테마는 `https://blog.example.com/` 같은 도메인 루트 배포를 기준으로 합니다. `https://example.com/my-blog/` 같은 하위 경로는 추가 조정이 필요합니다. Astro base만 설정했다고 모든 페이지와 자원이 호환되는 것은 아닙니다.

호스팅이 루트 사이트, 정적 디렉터리의 index.html, 정상적인 하위 페이지 경로를 제공하는지 확인하세요. GitHub Pages는 사이트 도메인·사용자 도메인 흐름을 우선 사용하세요. 프로젝트 하위 경로 튜토리얼을 그대로 테마 지원 설정으로 간주하지 마세요. 플랫폼 설정은 [Astro 배포 문서](https://docs.astro.build/en/guides/deploy/)의 해당 호스팅 안내를 참고하세요.

## 2\. 필요한 소스 파일 모두 준비하기

배포에는 내 블로그 프로젝트와 실제 콘텐츠 브랜치를 사용하세요. 테마 유지보수 저장소의 데모를 그대로 개인 블로그로 취급하지 마세요. 소스에는 최소한 프로젝트 설정, 콘텐츠, 의존성 명세, 필요한 자원이 있어야 합니다.

로컬 표지나 Fragment 이미지를 추가·교체했다면 먼저 로컬 dev나 doctor로 반응형 파일을 준비하고 다음을 커밋하세요.

*   글, Fragments, 사용자 페이지, `src/site.config.ts`.
*   글이 참조하는 원본, public 이미지, 아이콘, 실제 필요한 음악 자원.
*   manifest.json, generated/, 사용 중인 originals/를 포함한 `src/assets/blog/covers/` 전체.
*   `package.json`, `package-lock.json`, 기존 Astro 설정과 호스팅 설정.

원본이 항상 originals에 있는 것은 아닙니다. 글 옆이나 public의 원본도 커밋하세요. 자세한 내용은 [글과 Fragments에 이미지 넣기](https://demo.anglefeint.com/ko/blog/starter-guide-images/)를 참고하세요.

일반 dev·build·doctor는 CI에서도 누락되거나 오래되거나 손상된 파생 이미지를 필요에 따라 생성하며 올바른 기존 파일은 재사용합니다. 원본 누락, 잘못된 이미지와 안전하지 않은 경로는 오류입니다. 명시적 `prepare-covers --check`와 설정 동기화는 읽기 전용 검사입니다. 원본과 `src/assets/blog/covers/` 전체를 Git에 저장하면 재사용할 수 있어 배포 플랫폼의 이미지 캐시에 의존하지 않습니다.

Git 기반 배포에는 node\_modules, `.astro`, dist를 커밋할 필요가 없습니다. 플랫폼이 의존성을 설치하고 산출물을 만듭니다. 로컬 의존성 디렉터리를 정적 사이트로 올리지 마세요. 환경 파일이 저장소에 없다면 플랫폼에 필요한 환경변수를 설정하세요. PUBLIC\_ 변수는 공개 사이트 정보용이며 비밀 자격 증명에 적합하지 않습니다.

## 3\. 로컬 검사와 실제 빌드 결과 미리보기

Ctrl+C로 dev를 멈추고 터미널이 프로젝트 루트에 있는지 확인한 뒤 실행하세요.

```bash
npm run doctor
npm run preview
```

preview 주소를 열어 홈, 글, 이미지, 언어 메뉴, 글 검색을 확인하세요. 언어를 추가하거나 선택 페이지를 켰다면 그 입구도 확인합니다. 댓글 등 외부 서비스는 브라우저에서 실제 연결해야 확인할 수 있습니다. 로컬 빌드 통과가 원격 권한의 정확함을 증명하지는 않습니다.

명령별 역할은 다릅니다.

| 명령 | 역할 |
| --- | --- |
| `npm run dev` | 로컬 개발이며 관련 이미지는 자동 준비할 수 있습니다. 빌드 뒤 전문 검색 인덱스는 없습니다. |
| `npm run doctor` | CI를 포함한 이미지 준비, Astro 검사, 빌드입니다. About이 켜져 있으면 런타임 설정도 확인합니다. |
| `npm run check` | 현재 starter에서는 doctor를 호출하므로 둘을 연속 실행할 필요는 없습니다. |
| `npm run build` | 필요한 파생 이미지를 준비한 뒤 사이트를 빌드합니다. |
| `npm run preview` | 이미 빌드한 dist를 제공하며 재빌드하거나 게시하지 않습니다. |

검사나 빌드가 실패하면 오류를 고치고 남은 dist를 배포하지 마세요. doctor 성공 후에는 빌드 결과가 있으므로 check·build를 바로 반복할 필요는 없습니다. Ctrl+C로 preview를 멈춥니다.

## 4\. 완전한 정적 산출물 배포하기

Git 저장소를 연결해 플랫폼에서 빌드하거나 로컬 빌드 뒤 직접 업로드할 수 있습니다. 최종적으로 같은 정적 출력을 제공합니다.

### 방법 1: 호스팅 플랫폼에서 Git 빌드

플랫폼에 내 저장소를 연결하고 설정하세요.

| 항목 | 현재 starter 설정 |
| --- | --- |
| 빌드 브랜치 | 실제 블로그 콘텐츠를 관리하는 브랜치 |
| 프로젝트 루트 | 이 블로그 package.json이 있는 디렉터리이며 저장소 최상위가 아닐 수 있습니다. |
| Node.js | 프로젝트·의존성 요구 사항을 충족해야 하며 현재 starter는 22.12.0 이상을 선언합니다. |
| 설치 | npm 프로젝트는 `npm ci`를 쓸 수 있으며 커밋한 package-lock.json이 package.json과 일치해야 합니다. |
| 빌드 명령 | `npm run build` |
| 출력 디렉터리 | 프로젝트 루트 기준 `dist` |

플랫폼이 의존성을 자동 설치한다면 설치 명령을 중복 추가하지 마세요. 전체 빌드 스크립트를 직접 써야 한다면 설치 후 build를 수행하세요. doctor, check, build를 중복 실행할 필요는 없습니다.

프레임워크 프리셋, 브랜치, 설치 절차는 실제 플랫폼 설정을 따릅니다. 정적 출력을 선택하고 npm run dev나 npm run preview를 운영 시작 명령으로 쓰지 마세요.

### 방법 2: 로컬 빌드 결과 업로드

로컬 doctor 성공 뒤 `dist/` 전체 내용을 호스팅 웹 루트에 올리세요. 출력 폴더를 선택한다면 dist, 사이트 파일을 올린다면 dist 안의 내용을 선택하세요. 불필요한 dist 경로를 한 겹 더 씌우지 마세요.

HTML뿐 아니라 `_astro/`, `_blog-covers/`, `_social/`, 검색 인덱스, 실제 생성된 다른 파일을 모두 포함해야 합니다. 밑줄 디렉터리는 무시할 임시 파일이 아닙니다. HTML만 올리면 스타일, 스크립트, 이미지, 검색이 빠집니다.

재배포는 플랫폼의 전체 배포·교체를 사용하세요. 새 파일만 덮어써서 삭제한 글, 이전 페이지, 이전 언어 파일이 남지 않게 하세요. 로컬 Markdown을 삭제해도 직접 업로드한 서버의 이전 HTML은 자동 삭제되지 않습니다.

## 5\. 플랫폼에 도메인을 연결하고 DNS 설정하기

플랫폼에 사용자 도메인을 추가하고 제공한 레코드 값에 따라 도메인 DNS 관리에서 추가·수정하세요. 루트와 하위 도메인의 레코드 타입과 대상은 다를 수 있습니다. 실제 플랫폼 값을 사용하고 예시 IP를 복사하지 마세요.

플랫폼이 도메인과 HTTPS 인증서 준비를 확인하면 정식 주소로 여세요. 루트 도메인과 www 등 여러 주소를 쓴다면 주 주소 하나를 고르고 호스팅에서 나머지를 그 주소로 리다이렉트하세요. site.url에도 주 주소를 씁니다.

canonical은 메타 정보이지 방문 리다이렉트가 아닙니다. site.url은 DNS, 인증서, 여러 도메인 이동을 수행하지 않으며 도메인·호스팅 설정이 담당합니다. 주 도메인을 바꾸면 다시 빌드·배포하고 이전 도메인의 환경 덮어쓰기도 갱신하세요.

## 6\. 게시 후 페이지와 공개 출력 확인하기

정식 도메인으로 글의 직접 링크를 열고 새로고침해도 열리는지 확인하세요. 홈에서 클릭 성공만으로 모든 경로가 올바르다고 판단하지 마세요. 이미지, 코드 스타일, 언어 전환, 검색도 확인합니다. dev에서만 테스트한 기능은 빌드한 사이트에서 다시 확인해야 합니다.

다음 정적 출력은 테마가 기본 제공하므로 같은 통합을 또 설치할 필요는 없습니다.

| 주소 예시 | 용도 |
| --- | --- |
| `/robots.txt` | 수집 규칙과 sitemap 주소이며 접근 권한 제어는 아닙니다. |
| `/sitemap-index.xml` | 사이트맵 입구입니다. 링크는 정식 도메인을 사용해야 합니다. |
| `/zh/rss.xml` | 중국어 간체 글 구독입니다. 다른 활성 언어는 zh를 바꿉니다. |
| `/llms.txt` | AI 읽기용 콘텐츠 전체 인덱스 |
| `/zh/llms.txt`, `/zh/llms-full.txt` | 해당 언어의 내보낼 콘텐츠가 있을 때 인덱스와 전문 모음 |
| `/zh/blog/my-first-post/index.md` | 공개 글의 Markdown입니다. 예시 slug를 실제 글로 바꾸세요. |
| `/zh/fragments/index.md`, `/zh/about/index.md` | 페이지 활성화와 내보내기 조건을 충족할 때의 공개 콘텐츠 |

글 sitemap 수정일은 updatedDate, 없으면 pubDate를 사용하며 빌드마다 새 날짜를 꾸미지 않습니다. 꺼진 언어·페이지의 공개 출력을 기대하면 안 됩니다. 검색의 search: false는 비공개가 아니며 다른 공개 출력을 자동 금지하지도 않습니다.

AI 내보내기는 공개 글, 켜진 Fragments, About을 포함합니다. 댓글과 장식 도구 UI는 본문에 포함하지 않습니다. 실제 noindex 페이지나 외부 canonical 페이지는 제외합니다. 사용자 파일이 생성 경로와 충돌하면 직접 덮어쓰지 않고 빌드를 멈춥니다. 내보내기 파일과 발견 링크는 재빌드 시 갱신하므로 함께 배포해야 합니다.

이 메타 정보와 텍스트는 발견·읽기를 돕지만 검색 엔진 수록, AI 인용, 방문자 증가를 보장하지 않습니다.

### 호스팅 응답 헤더의 차이

빌드 시 dist/\_headers에 `/:locale/terminal/*`의 `X-Robots-Tag: noindex`를 보완하고 기존 규칙을 유지하며 소스 public/\_headers는 바꾸지 않습니다. 이 파일 형식을 지원하는 호스팅은 적용하고 다른 서비스는 동등한 헤더 설정이 필요합니다.

Astro preview는 호스팅의 \_headers 규칙을 흉내 내지 않습니다. 실제 적용 판단에는 정식 서비스 응답을 확인해야 하며 로컬 파일 존재만으로 판단하지 마세요. 이 규칙을 위해 Node 서버를 추가할 필요는 없습니다.

도메인·환경변수 우선순위는 [사이트 사전](https://demo.anglefeint.com/ko/blog/config-site-chrome/#environment), 공개 설명의 필드 정의는 [GA4와 AI 읽기 보충 사전](https://demo.anglefeint.com/ko/blog/config-analytics-ai/#supplement)을 참고하세요.

## 7\. 필요할 때 AI 읽기 설명 추가하기

일반 배포에는 필요 없습니다. 사이트 배경이나 추가 자료를 설명하려면 최상위에 합치세요.

```ts
aiReadableContent: {
  notes: '이 사이트는 개인 학습 과정을 기록하며 내용은 계속 수정될 수 있습니다.',
  links: [{ label: '프로젝트 홈페이지', href: 'https://example.com/project' }],
},
```

notes는 Markdown을 지원하며 links 항목은 label과 href를 씁니다. 공개 접근 가능한 HTTP(S) 주소를 사용하세요. 루트 등 상대 주소는 사이트 주소 기준으로 해석합니다. 공개 사이트 보충 설명이며 글 본문을 대체하거나 글에 비공개 제한을 추가하지 않습니다.

언어별 덮어쓰기는 `i18n.locales.<locale>.aiReadableContent`를 씁니다. 예를 들어 중국어 간체 전용 설명과 추가 링크 없음은 다음과 같습니다.

```ts
i18n: {
  locales: {
    zh: {
      aiReadableContent: {
        notes: '中文内容是作者自己的学习笔记。',
        links: [],
      },
    },
  },
},
```

필드를 생략하면 전역값을 상속하며 notes: ‘’ 또는 links: \[\]는 해당 부분을 명시적으로 숨깁니다. 설명은 관련 인덱스, 전문 모음, 개별 Markdown에 들어가므로 공개 의사를 확인하고 수정 뒤 다시 빌드하세요.

## 8\. 필요할 때 GA4 방문 통계 켜기

기본적으로 Google 통계 스크립트를 로드하지 않습니다. 필요하면 Google Analytics 웹 데이터 스트림에서 G-로 시작하는 Measurement ID를 얻으세요. 위치는 [Google 공식 안내](https://support.google.com/analytics/answer/9539598)를 참고하세요. 테마는 G- ID만 받으며 숫자 속성 ID, GTM 컨테이너 ID, 다른 식별자로 대체하지 마세요.

site와 같은 최상위에 합치세요.

```ts
analytics: {
  googleAnalyticsId: 'G-XXXXXXXXXX',
},
```

실제 ID로 바꾸세요. 빈 문자열은 끄며 형식 오류는 설정 오류입니다. 하나의 ID로 모든 언어 페이지를 집계하고 경로로 구분할 수 있으므로 분위기·언어마다 스크립트를 넣을 필요는 없습니다.

테마는 운영 빌드에서 ID가 있을 때만 로더를 출력하며 dev는 보내지 않습니다. 브라우저 주소가 localhost, 그 하위 도메인, 루프백 등 로컬이면 전송을 건너뜁니다. 운영 빌드를 LAN IP나 원격 미리보기 도메인으로 열면 집계될 수 있으므로 모든 preview가 제외된다고 생각하지 마세요.

재배포 후 정식 주소로 방문해 GA4 실시간 보고서를 확인하세요. 스크립트 차단, 네트워크, 통계 측 설정이 영향을 줄 수 있습니다. 수동 코드, GTM, 다른 주입 도구로 같은 통계를 중복 설치하지 마세요. 동의 관리 UI는 포함하지 않으므로 필요하면 직접 연결하세요.

## 9\. 배포 실패와 온라인 문제 해결

| 현상 | 우선 확인 |
| --- | --- |
| npm ci 실패 | Node·의존성 요구와 package-lock 커밋 및 package.json 일치 여부 |
| 이미지 missing／stale／modified | 일반 build는 해당 파생 파일을 자동 복구합니다. 계속 실패하면 원본과 경로를 확인하세요. 읽기 전용 –check를 실행했다면 먼저 준비 명령을 실행하세요. |
| 빌드 성공이나 페이지 404 | 출력 디렉터리, 배포 브랜치, 웹 루트, 디렉터리 index 지원, 미지원 하위 경로 사용 여부 |
| 홈은 열리지만 글 새로고침 404 | 실제 정적 하위 경로 지원, 홈만 배포했는지, 잘못된 SPA 대체 설정인지 확인하세요. |
| 스타일·이미지·검색 없음 | 전체 dist 배포 여부, 자원 디렉터리 누락, 경로 재작성을 확인하세요. |
| canonical／RSS가 예시 도메인 | site.url, PUBLIC\_SITE\_URL, 빌드 모드 환경값과 재빌드·재배포를 확인하세요. |
| 설정 변경이 온라인에 없음 | 로컬만 바꾼 것이 아니라 올바른 프로젝트·브랜치·최신 커밋을 배포했는지 확인하세요. |
| 삭제한 글의 링크가 계속 열림 | 이전 배포 파일·캐시가 남았는지, 전체 교체와 호스팅 캐시를 확인하세요. |
| GA4 데이터 없음 | 실제 G- ID, 운영 빌드, 비로컬 주소, 스크립트 차단을 확인하세요. |

일상 업데이트도 “로컬 편집·준비 → 검사·미리보기 → 소스 커밋 → 빌드·배포”를 따릅니다. 업그레이드는 [설치 가이드](https://demo.anglefeint.com/ko/blog/starter-guide-1-configure-your-site/), 언어 경로는 [더 많은 언어의 독자 맞이하기](https://demo.anglefeint.com/ko/blog/starter-guide-languages/)를 참고하세요.

## 가이드 탐색과 설정 조회

첫 배포 과정은 여기까지입니다. 이후에는 바꿀 내용에 맞는 가이드를 다시 보거나 설정 사전을 조회하세요.

[이전 글: 더 많은 언어의 독자 맞이하기](https://demo.anglefeint.com/ko/blog/starter-guide-languages/) · [여덟 편의 가이드 시작 페이지](https://demo.anglefeint.com/ko/blog/starter-guide-1-configure-your-site/#tutorial-order).

관련 필드: [도메인과 환경 덮어쓰기](https://demo.anglefeint.com/ko/blog/config-site-chrome/), [GA4와 AI 읽기 보충](https://demo.anglefeint.com/ko/blog/config-analytics-ai/), [검색 자원](https://demo.anglefeint.com/ko/blog/config-search/). 전체 경로, 기본값, 제한은 [설정 사전 시작 페이지](https://demo.anglefeint.com/ko/blog/config-reference/)를 참고하세요.
