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

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

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

✓2. 학습 목표

✓이 강의를 마치면

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

◇3. 핵심 개념

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

세 실행 환경의 차이

환경	입력	확인할 수 있는 것	이것만으로 확인할 수 없는 것
개발 서버	소스 파일	빠른 편집과 화면 확인	프로덕션 빌드 성공 여부
프로덕션 build	소스·설정·의존성	SSR/MDX 변환, 링크 검사, 정적 파일 생성	모바일 배치와 실제 클릭 동작 전부
build 정적 serve	생성된 build	배포 산출물의 경로·에셋·클라이언트 실행	실제 호스팅 도메인·CDN 설정

빌드 성공은 중요한 자동 검증이지만 사용자 행동 전체의 성공을 뜻하지 않습니다. 반대로 브라우저 개발 서버가 정상이어도 SSR에서 window를 직접 읽거나 baseUrl이 틀리면 프로덕션 build 또는 정적 배포에서만 실패할 수 있습니다.

실행 전 안전 기준선

명령을 실행하기 전에 다음 값을 기록합니다.

현재 브랜치:
HEAD SHA:
git status의 예상 변경:
Node/npm 버전:
package-lock.json 존재 여부:
사용할 포트:
검증할 대표 URL:

npm ci는 lockfile 기준으로 의존성 디렉터리를 다시 구성합니다. 소스 파일을 지우는 명령은 아니지만 node_modules 안에 수동으로 넣은 파일은 보존 대상으로 생각하면 안 됩니다. 저장해야 할 작업은 반드시 저장소의 정상 경로와 Git 변경으로 관리합니다.

✎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

명령을 한 줄씩 확인하기

1. Set-Location으로 다른 프로젝트를 실수로 빌드하지 않도록 루트를 고정합니다.
2. git status --short에서 자신이 만든 변경과 모르는 변경을 구분합니다. 모르는 변경을 삭제하거나 초기화하지 않습니다.
3. npm.cmd ci가 package-lock.json과 정확히 맞는 의존성을 설치합니다. lockfile이 없거나 package.json과 맞지 않으면 실패하는 것이 정상입니다.
4. npm.cmd run build가 설정과 문서를 읽고 프로덕션 정적 파일을 만듭니다.

정상 결과는 단순히 build 폴더가 있다는 것이 아니라 명령 종료 코드가 0이고 마지막 로그에 성공이 표시되는 상태입니다. 오래된 build 폴더가 남아 있으면 실패했는데도 산출물이 있다고 착각할 수 있으므로 실행 로그와 생성 시각을 함께 봅니다.

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

2. PowerShell

실행 위치: 저장소 루트

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

대상: 생성된 build 정적 결과

PowerShell

npm.cmd run serve

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

새 PowerShell · 읽기 전용 확인

$siteUrl = "http://localhost:3000"
$response = Invoke-WebRequest -Uri $siteUrl
$response.StatusCode
$response.Headers["Content-Type"]

기대값은 상태 200과 HTML Content-Type입니다. 포트가 달라졌다면 serve 로그의 실제 주소를 사용합니다. 없는 경로의 404도 사이트가 멈춘 것이 아니라 예상된 사용자 안내 화면인지 브라우저에서 확인합니다.

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. 직접 실습

✎직접 실습

실습 목표

현재 작업을 손상시키지 않고 프로덕션 build와 정적 결과를 검증해 재사용 가능한 배포 전 기록을 만듭니다.

시작 전 상태

현재 브랜치·SHA·git status·Node/npm 버전을 기록합니다. 모르는 변경이 있으면 정리 명령을 실행하지 말고 소유자에게 확인합니다. 실제 비밀 값은 기록하지 않습니다.

1단계: 따라 하기

lockfile 설치와 build를 실행합니다. 종료 코드, 마지막 성공 메시지, build 생성 시각을 기록하고 첫 오류가 있다면 이후 오류보다 먼저 해결합니다.

2단계: 조건을 바꿔 비교하기

정적 serve를 실행해 홈과 대표 강의의 200을 확인합니다. 없는 URL도 열어 404 안내와 복귀 링크를 확인하고, 개발 서버 결과와 어떤 차이가 있는지 기록합니다.

3단계: 직접 적용

모바일 너비, 키보드 탐색, 다크 모드, 사이드바, 이미지, Console, 실패한 Network 요청을 포함한 프로젝트 전용 체크리스트를 만듭니다. 대표 URL과 예상 결과를 구체적으로 적습니다.

4단계: 스스로 확인

• build 종료 코드와 산출물 존재를 둘 다 확인했나요?
• 현재 변경을 초기화하거나 덮어쓰지 않았나요?
• 화면 점검 결과를 URL·브라우저·SHA와 함께 남겼나요?

막혔을 때

• npm ci가 lockfile 오류로 중지: lockfile을 임의 삭제하지 말고 package.json과 변경 이력을 확인합니다.
• build만 실패하고 개발 서버는 정상: 로그의 첫 SSR/MDX/링크 오류 파일을 확인합니다.
• serve에서 CSS·이미지가 404: url/baseUrl과 생성된 에셋 경로를 확인합니다.
• 포트 사용 중: 기존 프로세스를 식별하거나 serve가 지원하는 다른 포트를 명시하고 기록합니다.

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

?8. 이해 점검 질문 3개

?이해 점검

1. 개발 서버와 build 결과 정적 서버는 무엇이 다른가요?
2. onBrokenLinks: throw는 어떤 오류를 막나요?
3. 빌드가 성공했지만 모바일 메뉴를 키보드로 열 수 없다면 배포 가능으로 판정하면 안 되는 이유는 무엇인가요?

■9. 핵심 요약

■핵심 요약

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

§다음 강의 연결

검증 기준선을 만들었으므로 3강. Git 배포 흐름에서 어떤 커밋과 브랜치가 배포 대상인지 추적합니다.