8강. 사이트 주소·baseUrl·도메인 설정의 원리

?1. 이번 강의에서 해결할 문제

호스트 주소와 프로젝트 경로를 뒤섞으면 모든 내부 링크와 자산 경로가 틀어집니다. 커스텀 도메인은 DNS 비용과 보안 책임도 추가합니다.

✓2. 학습 목표

✓이 강의를 마치면

• url과 baseUrl의 역할을 구분합니다.
• 프로젝트 Pages와 사용자 Pages 주소를 계산합니다.
• 커스텀 도메인을 선택 사항으로 평가하고 DNS 변경 전 복구 계획을 세웁니다.

◇3. 핵심 개념

url은 프로토콜과 호스트, baseUrl은 사이트가 제공되는 경로 접두사입니다. https://example-learner.github.io/dev-foundations/라면 url은 호스트까지, baseUrl은 /dev-foundations/입니다. 커스텀 도메인은 구매 비용과 DNS·HTTPS 관리가 생길 수 있어 필수가 아니며 GitHub 기본 주소로 월 비용 0원 구조를 유지할 수 있습니다.

커스텀 도메인은 GitHub Pages 공식 도메인 문서의 현재 DNS·HTTPS 절차를 확인합니다.

✎4. 단계별 실습

1. 파일 검토

실행 위치: 저장소 루트

실행 전 확인: 현재 정상 값을 직접 바꾸지 말고 별도 노트에서 계산합니다.

대상: docusaurus.config.js 가상 프로젝트 설정

파일 검토

url: 'https://example-learner.github.io',
baseUrl: '/dev-foundations/',
organizationName: 'example-learner',
projectName: 'dev-foundations',
trailingSlash: false,

예상 결과: 네 값을 결합한 주소가 https://example-learner.github.io/dev-foundations/가 됩니다.

2. PowerShell

실행 위치: 로컬 터미널

실행 전 확인: DNS 레코드를 변경하지 않고 읽기 전용 조회만 합니다.

대상: 선택적 가상 도메인의 DNS 조회

PowerShell

Resolve-DnsName docs.example.test -ErrorAction SilentlyContinue

예상 결과: 예약된 예시 도메인은 결과가 없을 수 있으며 실제 사용 시 변경 전후 레코드를 기록합니다.

→5. 배포·운영 흐름이 동작하는 이유

Docusaurus는 build 시 baseUrl을 링크와 정적 자산 경로에 반영합니다. DNS는 도메인을 호스팅 주소로 연결하지만 사이트 경로 구성과 별도 계층이므로 둘을 함께 맞춰야 합니다.

!6. 자주 하는 실수와 안전한 해결법

!자주 하는 실수

• 실수: url에 저장소 경로까지 포함 안전한 해결: 호스트는 url, 경로 접두사는 baseUrl에 둡니다.
• 실수: DNS부터 바꾸고 GitHub 설정을 나중에 함 안전한 해결: 공식 문서 순서와 기존 레코드 백업을 따릅니다.
• 실수: 와일드카드 DNS 사용 안전한 해결: 도메인 탈취 위험이 있으므로 필요한 정확한 호스트만 설정합니다.

✎7. 직접 실습

✎직접 실습

1. 가상 사용자명과 저장소명으로 최종 URL을 계산합니다.
2. 현재 config에서 url과 baseUrl을 읽습니다.
3. 커스텀 도메인을 쓰지 않을 때 절약되는 비용·운영 항목을 적습니다.

실습 기록에는 변경 SHA, 실행 위치, 확인 대상, 예상 결과와 실제 결과를 남기고 실제 토큰·비밀번호·SSH 개인 키·.env 내용은 포함하지 않습니다.

?8. 이해 점검 질문 3개

?이해 점검

1. url과 baseUrl은 주소의 어느 부분을 담당하나요?
2. 프로젝트 Pages가 /가 아닌 저장소 경로를 쓰는 이유는 무엇인가요?
3. 커스텀 도메인이 선택 사항이어야 하는 이유는 무엇인가요?

■9. 핵심 요약

■핵심 요약

url은 호스트, baseUrl은 배포 경로입니다. 기본 GitHub 주소는 추가 도메인 비용 없이 운영할 수 있고 커스텀 도메인은 DNS·HTTPS·보안 책임을 감수할 때만 선택합니다.