2강. 배포 전 점검: 빌드, 링크, 모바일 화면, 오류 확인

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

배포 후에야 깨진 링크나 정적 에셋 문제를 발견하면 사용자가 먼저 오류를 보게 됩니다. 로컬에서 배포와 같은 build 결과를 만들고 점검 순서를 고정합니다.

✓2. 학습 목표

✓이 강의를 마치면

• 잠금 파일 기준으로 의존성을 설치하고 프로덕션 빌드를 실행합니다.
• 빌드 결과를 로컬 정적 서버에서 확인합니다.
• 홈·강의·사이드바·모바일·404·콘솔 점검표를 만듭니다.

◇3. 핵심 개념

npm run build는 Docusaurus가 프로덕션 정적 파일을 build에 생성하는 검증 단계입니다. 현재 설정의 onBrokenLinks: throw는 발견한 내부 링크 오류를 빌드 실패로 바꿉니다. npm run serve는 개발 서버가 아니라 만들어진 build 결과를 제공해 배포에 가까운 상태를 확인합니다.

✎4. 단계별 실습

1. PowerShell

실행 위치: 저장소 루트

실행 전 확인: git status가 예상 변경만 포함하는지 확인합니다.

대상: package-lock.json과 전체 Docusaurus 문서

PowerShell

Set-Location C:\dev\dev-foundations
git status --short
npm.cmd ci
npm.cmd run build

예상 결과: 의존성이 lockfile대로 설치되고 build 폴더 생성과 성공 메시지가 표시됩니다.

2. PowerShell

실행 위치: 저장소 루트

실행 전 확인: 포트 3000을 다른 프로그램이 사용하는지 확인합니다.

대상: 생성된 build 정적 결과

PowerShell

npm.cmd run serve

예상 결과: 로컬 정적 서버 주소가 표시됩니다. 새 PowerShell에서 Invoke-WebRequest로 응답을 확인합니다.

3. 브라우저

실행 위치: 로컬 정적 사이트

실행 전 확인: 개발자 도구 Console과 Network를 엽니다.

대상: 홈·강의·사이드바·모바일·없는 경로

브라우저

1. 홈과 대표 강의 열기
2. 사이드바 링크 이동
3. 좁은 모바일 폭에서 메뉴 확인
4. 존재하지 않는 주소에서 404 확인
5. Console 오류와 실패한 정적 요청 확인

예상 결과: 필수 화면과 내비게이션이 보이고 치명적 콘솔·네트워크 오류가 없습니다.

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

같은 lockfile과 프로덕션 빌드 명령을 사용하면 로컬과 CI 차이를 줄입니다. 정적 서버 점검은 개발 전용 동작이 build에 누락되거나 baseUrl에서 깨지는 문제를 배포 전에 발견합니다.

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

!자주 하는 실수

• 실수: npm start만 확인 안전한 해결: 반드시 npm run build와 build 결과 serve를 실행합니다.
• 실수: 빌드 성공이면 모바일도 정상이라고 단정 안전한 해결: 레이아웃·키보드·모바일 메뉴는 브라우저에서 별도 확인합니다.
• 실수: 404를 실패로만 생각 안전한 해결: 잘못된 주소가 사용자에게 이해 가능한 404 화면을 제공하는지 확인합니다.

✎7. 직접 실습

✎직접 실습

1. 깨끗한 설치와 build를 실행합니다.
2. 로컬 build에서 홈·강의·사이드바를 확인합니다.
3. 모바일 폭·404·Console·Network 결과를 체크리스트로 저장합니다.

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

?8. 이해 점검 질문 3개

?이해 점검

1. 개발 서버와 build 결과 정적 서버는 무엇이 다른가요?
2. onBrokenLinks: throw는 어떤 오류를 막나요?
3. 빌드 성공 후에도 브라우저 점검이 필요한 이유는 무엇인가요?

■9. 핵심 요약

■핵심 요약

배포 전 검증은 lockfile 설치, 프로덕션 build, 정적 serve, 사용자 경로 점검 순서입니다. 자동 검사와 화면 검사를 함께 수행해야 배포 실패를 앞당겨 발견할 수 있습니다.