0728 프론트엔드 실무 심화 (10/N): 배포, 환경변수와 운영 모니터링
✅ 1. 프론트엔드 배포란 무엇인가?
- 프론트엔드 배포는 개발한 React/Vite/Next.js 화면을 실제 사용자가 접속할 수 있는 서버 또는 CDN에 올리는 작업입니다.
- 단순히
npm run build 결과물을 업로드하는 것만이 아니라, 환경변수, API 주소, 캐시, CDN, 롤백, 배포 후 확인까지 포함합니다.
- 고객 화면은 상담 신청 전환에 직접 연결되고, 관리자 화면은 운영 업무에 연결되므로 배포 안정성이 매우 중요합니다.
코드 수정
↓
lint/test/build
↓
환경변수 확인
↓
정적 파일 생성
↓
S3/서버/CDN 업로드
↓
캐시 무효화
↓
배포 후 Smoke Test
➕ 1-1. 프론트엔드 배포에서 자주 생기는 문제
로컬에서는 되는데 운영에서 API 호출 실패
환경변수 누락
이전 JS/CSS 캐시가 남아 화면 깨짐
CloudFront 캐시 때문에 새 배포 반영 지연
관리자 화면은 새 버전인데 API 응답 구조가 안 맞음
이미지 경로 깨짐
라우팅 새로고침 시 404 발생
- 프론트엔드는 “빌드 성공”만으로 배포가 끝나지 않습니다.
- 배포 후 실제 운영 URL에서 핵심 흐름을 확인해야 합니다.
✅ 2. 개발 환경과 운영 환경 구분
- 프론트엔드는 환경별로 API 주소, CDN 주소, 로그 설정, 기능 플래그가 달라질 수 있습니다.
| 환경 | 용도 |
|---|
| Local | 개발자 로컬 개발 |
| Development | 내부 개발 서버 |
| Staging | 운영 배포 전 검증 |
| Production | 실제 사용자 운영 환경 |
➕ 2-1. 환경별 예시
Local:
http://localhost:3000 API 사용
Staging:
스테이징 API 사용
테스트 관리자 계정 사용
Production:
운영 API 사용
실제 고객/관리자 사용
➕ 2-2. 환경 구분이 중요한 이유
- 운영 API에 테스트 데이터를 잘못 보내는 일을 막을 수 있습니다.
- 스테이징에서 먼저 QA할 수 있습니다.
- 운영 전용 기능과 테스트 기능을 분리할 수 있습니다.
- 문제 발생 시 환경별로 원인을 좁히기 쉽습니다.
✅ 3. 프론트엔드 환경변수
- 프론트엔드 환경변수는 빌드 시점에 코드에 포함되는 경우가 많습니다.
- 백엔드 환경변수와 다르게, 프론트엔드에 들어간 값은 브라우저에서 볼 수 있다고 생각해야 합니다.
➕ 3-1. Vite 환경변수
Vite:
VITE_ 로 시작하는 환경변수만 클라이언트 코드에서 접근 가능
VITE_API_BASE_URL=https://api.example.com
VITE_PUBLIC_ASSET_URL=https://cdn.example.com
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL;
➕ 3-2. Next.js 환경변수
Next.js:
NEXT_PUBLIC_ 로 시작하는 환경변수는 브라우저에 노출됨
NEXT_PUBLIC_API_BASE_URL=https://api.example.com
➕ 3-3. 주의할 점
프론트엔드 환경변수에 Secret 넣지 않기
API Key, JWT Secret, AWS Secret 넣지 않기
운영 API 주소와 로컬 API 주소 혼동하지 않기
빌드 후 환경변수 변경이 바로 반영되지 않을 수 있음
VITE_, NEXT_PUBLIC_ 값은 사용자 브라우저에서 확인 가능하다고 봐야 합니다.- Secret은 반드시 백엔드에서만 관리해야 합니다.
✅ 4. 프론트엔드에 넣으면 안 되는 값
- 프론트엔드는 사용자 브라우저에서 실행되기 때문에 민감한 값을 넣으면 안 됩니다.
프론트엔드에 넣으면 안 되는 것:
JWT_SECRET
Refresh Token Secret
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
DATABASE_URL
관리자 API Secret
알림톡 API Key
결제 Secret Key
서버 내부 Webhook Secret
➕ 4-1. 넣어도 되는 값
공개 API Base URL
CDN Base URL
서비스 이름
공개용 feature flag
Sentry DSN 같은 공개 클라이언트 키
지도 공개 client key
- 공개 키라도 사용량 제한, 도메인 제한, 권한 제한이 필요할 수 있습니다.
- “프론트에 들어가는 값은 노출된다”를 기본 원칙으로 잡으면 됩니다.
✅ 5. 환경변수 검증
- 운영 배포에서 환경변수가 빠지면 화면이 빈 페이지가 되거나 API 호출이 실패할 수 있습니다.
- 앱 시작 시 필요한 환경변수가 있는지 검증하는 구조가 좋습니다.
➕ 5-1. 간단한 검증 예시
const requiredEnv = {
apiBaseUrl: import.meta.env.VITE_API_BASE_URL,
};
for (const [key, value] of Object.entries(requiredEnv)) {
if (!value) {
throw new Error(`Missing frontend env: ${key}`);
}
}
export const env = requiredEnv;
➕ 5-2. 사용 예시
export const env = {
apiBaseUrl: import.meta.env.VITE_API_BASE_URL,
publicAssetUrl: import.meta.env.VITE_PUBLIC_ASSET_URL,
};
- 환경변수는 여러 파일에서 직접
import.meta.env를 읽기보다 env.ts 한 곳으로 모으는 것이 좋습니다.
- 어떤 환경변수가 필요한지 문서화해야 합니다.
✅ 6. API Base URL 관리
- 프론트엔드에서 가장 중요한 환경변수 중 하나가 API 주소입니다.
- 로컬, 스테이징, 운영 API 주소가 섞이면 치명적인 문제가 생길 수 있습니다.
➕ 6-1. API Client 예시
import { env } from '@/config/env';
export const apiClient = axios.create({
baseURL: env.apiBaseUrl,
withCredentials: true,
});
➕ 6-2. 환경별 예시
# .env.local
VITE_API_BASE_URL=http://localhost:3000
# .env.production
VITE_API_BASE_URL=https://api.togethermall.example.com
➕ 6-3. 주의할 점
운영 빌드에 localhost가 들어가면 안 됨
스테이징 빌드에 운영 API가 들어가면 안 됨
관리자 화면과 고객 화면이 같은 API 기준을 쓰는지 확인
CORS 설정과 함께 확인
- 배포 후 Network 탭에서 실제 호출되는 API 주소를 확인하는 습관이 중요합니다.
✅ 7. 빌드와 정적 파일
- Vite/React 앱은 보통
npm run build를 실행하면 정적 파일이 생성됩니다.
- 이 결과물을 S3, Nginx, CloudFront, Vercel, Netlify 등에 배포할 수 있습니다.
➕ 7-1. Vite 빌드
npm run build
➕ 7-2. 결과물
dist/
index.html
assets/
index-abc123.js
index-def456.css
logo.webp
➕ 7-3. 빌드 전 확인
npm run lint
npm run test:run
npm run build
- 운영 배포 전에는 최소한 build가 성공하는지 확인해야 합니다.
- TypeScript 에러가 있는 상태로 배포하면 운영에서 빈 화면이 될 수 있습니다.
✅ 8. S3 + CloudFront 배포 구조
- 정적 프론트엔드는 AWS S3와 CloudFront로 배포하는 경우가 많습니다.
- S3는 파일 저장소, CloudFront는 CDN 역할을 합니다.
사용자
↓
CloudFront
↓
S3 정적 파일
➕ 8-1. 장점
- 정적 파일 제공 속도가 빠릅니다.
- 서버 부하가 적습니다.
- CloudFront 캐시를 활용할 수 있습니다.
- HTTPS 연결이 쉽습니다.
- 프론트와 백엔드 배포를 분리할 수 있습니다.
➕ 8-2. 주의할 점
SPA 라우팅 새로고침 404 처리
index.html 캐시 짧게
assets 파일은 캐시 길게
배포 후 invalidation 필요
S3 public access 정책 주의
CloudFront OAC/OAI 설정 검토
- SPA는
/admin/consults에서 새로고침하면 S3가 해당 파일을 찾으려다 404를 낼 수 있습니다.
- CloudFront/S3 에러 응답을
index.html로 돌리는 설정이 필요합니다.
✅ 9. SPA 라우팅 404 문제
- React Router 기반 SPA에서는 브라우저 라우팅과 서버 파일 경로가 다릅니다.
/admin/consults는 실제 파일이 아니라 React Router가 처리하는 경로입니다.
➕ 9-1. 문제 흐름
사용자 /admin/consults 직접 접속
↓
CloudFront/S3가 /admin/consults 파일 찾음
↓
파일 없음
↓
404 발생
➕ 9-2. 해결 방향
404 또는 403 에러 응답을 index.html로 반환
React Router가 이후 경로 처리
➕ 9-3. 주의할 점
- 모든 404를 무조건
index.html로 돌리면 실제 없는 이미지/API 경로 문제를 숨길 수 있습니다.
- 정적 프론트엔드 라우팅에만 적절히 적용해야 합니다.
- API는 별도 도메인 또는
/api 경로로 분리하는 것이 좋습니다.
✅ 10. 캐시 전략
- 프론트엔드 배포에서 캐시는 매우 중요합니다.
- 잘못 설정하면 사용자가 이전 JS/CSS를 계속 받아 화면이 깨질 수 있습니다.
➕ 10-1. 캐시 기준
| 파일 | 권장 캐시 |
|---|
index.html | 짧게 또는 no-cache |
| hashed JS/CSS | 길게 |
| 이미지 assets | 길게, 변경 시 파일명 변경 |
| 설정 JSON | 짧게 |
| API 응답 | API 성격에 따라 별도 |
➕ 10-2. 이유
index.html:
최신 JS/CSS 파일명을 참조해야 하므로 오래 캐시하면 위험
hashed assets:
파일명이 바뀌면 새 파일이므로 오래 캐시 가능
➕ 10-3. 문제 예시
index.html은 새 버전
JS 파일은 이전 버전
↓
API 응답 구조와 화면 코드가 안 맞음
↓
운영 화면 오류
index.html 캐시와 assets 캐시를 다르게 설정해야 합니다.- CloudFront invalidation 대상도 이 기준으로 잡는 것이 좋습니다.
✅ 11. CloudFront Invalidation
- CloudFront는 캐시된 파일을 전 세계 엣지에 보관합니다.
- 배포 후 새 파일을 즉시 반영하려면 invalidation이 필요할 수 있습니다.
➕ 11-1. 기본 명령어 예시
aws cloudfront create-invalidation \
--distribution-id DISTRIBUTION_ID \
--paths "/*"
➕ 11-2. 더 나은 기준
index.html:
항상 무효화
assets:
파일명 hash가 바뀌면 굳이 전체 무효화가 필요 없을 수 있음
급한 배포:
전체 invalidation 고려
➕ 11-3. 주의할 점
- 매번
/* 전체 invalidation을 해도 되지만, 규모가 커지면 비용과 효율을 고려해야 합니다.
- 작은 서비스에서는 단순하게 전체 invalidation으로 시작해도 현실적입니다.
✅ 12. 배포 스크립트
- 반복 배포 작업은 스크립트로 묶는 것이 좋습니다.
- 실수를 줄이고 배포 흐름을 표준화할 수 있습니다.
➕ 12-1. 예시 흐름
1. lint
2. test
3. build
4. S3 sync
5. CloudFront invalidation
6. 배포 결과 출력
➕ 12-2. 스크립트 예시
#!/bin/bash
set -e
npm run lint
npm run test:run
npm run build
aws s3 sync dist/ s3://YOUR_BUCKET_NAME --delete
aws cloudfront create-invalidation \
--distribution-id YOUR_DISTRIBUTION_ID \
--paths "/*"
echo "Frontend deploy completed"
➕ 12-3. 주의할 점
운영 버킷명 실수 방지
AWS profile 확인
빌드 환경변수 확인
--delete 사용 시 대상 경로 확인
배포 전 git branch 확인
--delete는 S3에 있는 불필요한 파일을 지워주지만, 버킷을 잘못 지정하면 위험합니다.- 운영 배포 스크립트에는 branch와 env 확인을 넣는 것이 좋습니다.
✅ 13. GitHub Actions 배포
- 배포를 자동화하려면 GitHub Actions를 사용할 수 있습니다.
- 다만 운영 배포는 승인 단계나 branch 기준을 명확히 해야 합니다.
➕ 13-1. 기본 흐름
main branch push
↓
checkout
↓
npm ci
↓
lint/test/build
↓
AWS credentials 설정
↓
S3 sync
↓
CloudFront invalidation
➕ 13-2. 주의할 점
GitHub Secrets에 AWS 키 저장
운영 배포 branch 제한
PR에서는 build/test만 수행
main merge 후 배포
실패 시 배포 중단
- 자동 배포는 편하지만 잘못 설정하면 위험합니다.
- 처음에는 수동 배포 스크립트 → GitHub Actions 순서로 가도 됩니다.
✅ 14. 프론트엔드 롤백
- 배포 후 문제가 생기면 빠르게 이전 버전으로 되돌릴 수 있어야 합니다.
- 프론트엔드는 정적 파일이므로 이전 빌드 산출물을 보관하면 롤백이 쉬워집니다.
➕ 14-1. 롤백 방식
이전 dist 파일 재업로드
이전 S3 prefix로 CloudFront origin 전환
버전별 build artifact 보관
Git tag 기준 재빌드 후 배포
➕ 14-2. 단순 롤백 흐름
문제 발견
↓
이전 안정 커밋 확인
↓
이전 커밋으로 checkout
↓
운영 env로 build
↓
S3 sync
↓
CloudFront invalidation
↓
Smoke Test
➕ 14-3. 주의할 점
백엔드 API 변경과 호환되는지 확인
DB migration이 필요한 배포였는지 확인
프론트만 롤백하면 더 깨질 수 있음
캐시 무효화 필요
- 프론트와 백엔드가 같이 바뀐 배포는 롤백도 같이 고려해야 합니다.
- API 응답 구조 변경이 있으면 하위 호환이 중요합니다.
✅ 15. 배포 전 체크리스트
1. 현재 branch 확인
2. git diff 확인
3. 환경변수 확인
4. npm run lint
5. npm run test:run
6. npm run build
7. API Base URL 확인
8. 라우팅 새로고침 확인
9. 모바일 핵심 화면 확인
10. 배포 후 Smoke Test 항목 준비
➕ 15-1. API 계약 변경 확인
API 응답 필드명이 바뀌었는가?
에러 코드가 바뀌었는가?
권한 정책이 바뀌었는가?
페이지네이션 meta 구조가 바뀌었는가?
프론트와 백엔드 배포 순서가 필요한가?
- 프론트 배포는 백엔드와 따로 보이지만 실제로는 API 계약에 묶여 있습니다.
- API 변경이 있으면 배포 순서를 반드시 확인해야 합니다.
✅ 16. 배포 후 Smoke Test
- 배포 후에는 운영 URL에서 핵심 기능을 빠르게 확인해야 합니다.
➕ 16-1. 고객 화면
메인 페이지 접속
상품 목록 확인
상품 상세 확인
대표 이미지/배너 확인
상담 신청 모달 열기
필수값 검증 확인
모바일 화면 확인
➕ 16-2. 관리자 화면
관리자 로그인
상담 목록 조회
검색/필터 1회 실행
상담 상세 모달 열기
권한별 버튼 확인
엑셀 다운로드 버튼 확인
상태 변경 모달 열기
➕ 16-3. 주의할 점
- 운영에서 실제 상담 신청을 생성할 경우 테스트 데이터 처리 기준이 있어야 합니다.
- 알림톡/SMS가 실제 발송되는지 확인해야 합니다.
- 가능하면 운영에서는 읽기 중심으로 확인하고, 스테이징에서 전체 흐름을 검증하는 것이 좋습니다.
✅ 17. 프론트엔드 에러 모니터링
- 프론트엔드 에러는 서버 로그에 남지 않을 수 있습니다.
- 사용자의 브라우저에서 발생하는 JS 에러, API 에러, 렌더링 오류를 모니터링할 수 있어야 합니다.
➕ 17-1. 잡아야 하는 에러
JavaScript runtime error
React render error
API 500/403/401 에러 증가
Chunk load error
이미지 로드 실패
폼 제출 실패
라우팅 에러
권한 처리 오류
➕ 17-2. 도구 예시
Sentry
LogRocket
Datadog RUM
CloudWatch RUM
Google Analytics 이벤트
직접 만든 ErrorBoundary + API 로그
- 작은 서비스라도 최소한 ErrorBoundary와 핵심 API 실패 로그는 고려할 수 있습니다.
- 사용자 브라우저에서만 생기는 오류는 운영자가 직접 보기 어렵습니다.
✅ 18. ErrorBoundary
- ErrorBoundary는 React 렌더링 중 발생한 에러로 전체 앱이 흰 화면이 되는 것을 막아줍니다.
- 특정 영역에서 문제가 생겼을 때 fallback UI를 보여줄 수 있습니다.
➕ 18-1. 필요한 이유
컴포넌트 렌더링 오류
예상치 못한 null/undefined 접근
특정 페이지 흰 화면 방지
사용자에게 재시도 안내 제공
에러 모니터링 도구로 전송
➕ 18-2. fallback 메시지 예시
화면을 표시하는 중 문제가 발생했습니다.
새로고침 후 다시 시도해 주세요.
➕ 18-3. 적용 위치
앱 전체
라우트 단위
관리자 주요 페이지 단위
위험한 위젯/차트 단위
- 앱 전체 ErrorBoundary 하나만 두는 것보다 주요 영역별로 나누면 더 좋습니다.
- 특정 차트 하나가 깨졌다고 전체 관리자 페이지가 죽으면 안 됩니다.
✅ 19. Chunk Load Error
- 프론트엔드 배포 후 자주 생기는 문제 중 하나가 Chunk Load Error입니다.
- 사용자가 이전
index.html을 캐시한 상태에서 새 배포 후 이전 JS chunk를 요청하면 파일이 없어져 오류가 발생할 수 있습니다.
➕ 19-1. 발생 흐름
사용자가 오래된 화면을 열어둠
↓
새 배포로 assets 파일명 변경
↓
사용자가 페이지 이동
↓
브라우저가 이전 chunk 파일 요청
↓
파일 없음
↓
Chunk Load Error
➕ 19-2. 대응 방향
index.html 캐시 짧게 설정
배포 후 이전 assets를 바로 삭제하지 않기
ChunkLoadError 감지 시 새로고침 안내
배포 중 사용자 영향 고려
➕ 19-3. 주의할 점
- S3 sync
--delete를 쓰면 이전 chunk가 사라질 수 있습니다.
- 작은 서비스에서는 큰 문제가 아닐 수 있지만, 관리자 작업 중 발생하면 불편할 수 있습니다.
- 중요한 관리자 작업 중에는 배포 시간을 조심하는 것이 좋습니다.
✅ 20. 사용자 행동 이벤트 모니터링
- 프론트엔드에서는 단순 에러뿐 아니라 핵심 행동 이벤트를 추적할 수 있습니다.
- 상담 신청 버튼 클릭, 폼 제출 성공/실패, 상품 상세 진입, 엑셀 다운로드 요청 같은 이벤트가 중요합니다.
➕ 20-1. 고객 화면 이벤트
상품 상세 진입
상담 신청 버튼 클릭
상담 신청 모달 열림
상담 신청 성공
상담 신청 실패
FAQ 클릭
혜택 영역 클릭
➕ 20-2. 관리자 화면 이벤트
관리자 로그인
상담 목록 검색
상태 변경 성공/실패
엑셀 다운로드 요청
필터 초기화
알림 재발송 요청
Webhook 재처리 요청
➕ 20-3. 주의할 점
개인정보를 이벤트에 넣지 않기
전화번호/이름/상담 메모 전송 금지
eventName과 익명 ID 중심으로 관리
성공/실패 count 중심으로 보기
- 이벤트는 운영 개선과 전환 분석에 도움이 됩니다.
- 하지만 개인정보를 분석 도구로 보내면 안 됩니다.
✅ 21. 프론트엔드 로그 기준
- 브라우저 콘솔 로그는 개발 중에는 유용하지만 운영에는 위험할 수 있습니다.
- 개인정보, 토큰, API 응답 전체를 콘솔에 남기면 안 됩니다.
➕ 21-1. 운영에서 제거해야 할 로그
console.log(response)
console.log(token)
console.log(user)
console.log(formValues)
console.log(error 전체 객체)
console.log(전화번호/이름/상담 메모)
➕ 21-2. 남겨도 되는 로그
개발 환경에서만 출력되는 디버그 로그
마스킹된 에러 코드
비식별 이벤트명
빌드 버전
➕ 21-3. 환경별 로그 처리
export function debugLog(...args: unknown[]) {
if (import.meta.env.DEV) {
console.log(...args);
}
}
- 운영 콘솔에 민감정보가 남지 않게 해야 합니다.
- 배포 전
console.log 검색은 꼭 하는 것이 좋습니다.
✅ 22. 버전 표시
- 운영 중 문제가 생겼을 때 현재 프론트엔드 버전을 확인할 수 있으면 좋습니다.
- 배포된 commit hash나 build time을 내부적으로 표시하거나 로그에 남길 수 있습니다.
➕ 22-1. 예시 환경변수
VITE_APP_VERSION=2026.07.28-1
VITE_GIT_SHA=abc1234
➕ 22-2. 관리자 화면 표시 예시
관리자 Footer:
Frontend v2026.07.28-1 · abc1234
➕ 22-3. 장점
운영자가 보고 있는 버전 확인 가능
배포 반영 여부 확인 가능
장애 발생 시 특정 배포와 연결 가능
캐시 문제 확인에 도움
- 고객 화면에는 굳이 노출하지 않아도 됩니다.
- 관리자 화면 하단이나 개발자용 정보 패널에 작게 표시하면 좋습니다.
✅ 23. 프론트엔드 배포 문서화
- 배포 절차는 문서로 남겨야 합니다.
- 혼자 개발하더라도 나중에 실수를 줄이고 AI 자동화에 활용할 수 있습니다.
➕ 23-1. 문서에 넣을 것
배포 대상
배포 branch
필요 환경변수
빌드 명령어
배포 명령어
CloudFront invalidation 방식
배포 전 체크리스트
배포 후 Smoke Test
롤백 방법
주의사항
➕ 23-2. 문서 예시
## 프론트엔드 배포 절차
### 대상
- 고객 화면/관리자 화면 정적 빌드
- S3 + CloudFront 배포
### 배포 전
```bash
npm run lint
npm run test:run
npm run build
배포
aws s3 sync dist/ s3://YOUR_BUCKET_NAME --delete
aws cloudfront create-invalidation --distribution-id YOUR_ID --paths "/*"
배포 후 확인
- 메인 페이지 접속
- 상품 상세 접속
- 상담 신청 모달 열기
- 관리자 로그인
- 상담 목록 조회
- 검색/필터 확인
롤백
- 이전 안정 커밋으로 checkout
- 운영 env로 재빌드
- S3 sync
- CloudFront invalidation
* 문서가 있으면 배포가 반복 가능한 작업이 됩니다.
* 나중에 GitHub Actions로 자동화하기도 쉬워집니다.
---
### ✅ 24. AI를 활용한 프론트엔드 배포 점검
* AI는 배포 전 체크리스트와 diff 리뷰에 매우 유용합니다.
* 특히 공통 컴포넌트, API client, 환경변수, 라우팅 변경은 AI에게 검토시키면 좋습니다.
#### ➕ 24-1. 좋은 질문 예시
```txt id="ai-frontend-deploy-review"
아래 git diff를 보고 프론트엔드 배포 전 위험 요소를 점검해줘.
프로젝트 상황:
1. React + Vite 기반 고객/관리자 화면
2. S3 + CloudFront로 정적 배포
3. API 주소는 VITE_API_BASE_URL 환경변수 사용
4. 서버 상태는 TanStack Query로 관리
5. 관리자 화면은 권한 기반 메뉴/버튼 노출이 있음
6. 상담 신청 폼과 관리자 상담 목록이 핵심 기능임
검토 기준:
- 환경변수 추가/변경 여부
- API Base URL 영향
- queryKey/invalidate 변경 위험
- 라우팅 새로고침 404 가능성
- 공통 컴포넌트 변경 영향
- 권한 UI 깨질 가능성
- 모바일 레이아웃 영향
- 배포 후 Smoke Test 항목
답변:
1. 위험도 높은 변경
2. 반드시 확인할 화면
3. 배포 전 명령어
4. 배포 후 Smoke Test
5. 롤백 시 주의사항
➕ 24-2. AI 답변 검증 기준
- 빌드 성공만 확인하라고 하지 않는가?
- 환경변수와 API Base URL을 확인하는가?
- CloudFront 캐시와 SPA 라우팅 문제를 언급하는가?
- 고객 상담 신청과 관리자 핵심 흐름을 Smoke Test에 포함하는가?
- 공통 컴포넌트 변경 영향 범위를 보라고 하는가?
- 프론트만 롤백해도 되는지 API 호환성을 확인하라고 하는가?
- 운영 콘솔 로그와 개인정보 노출을 확인하는가?
- 현재 서비스 규모에 맞는 현실적인 배포 절차를 제안하는가?
✅ 25. 실무 체크리스트
➕ 25-1. 환경변수 체크리스트
- API Base URL이 환경별로 분리되어 있는가?
- 운영 빌드에 localhost가 들어가지 않는가?
- 프론트 환경변수에 Secret이 들어가지 않는가?
env.ts 한 곳에서 환경변수를 관리하는가?- 필수 환경변수 누락 시 빨리 알 수 있는가?
.env.example이 최신인가?- 스테이징/운영 환경변수 차이가 문서화되어 있는가?
- 배포 후 Network 탭에서 실제 API 주소를 확인했는가?
➕ 25-2. 배포 체크리스트
- 배포 branch가 맞는가?
git diff를 확인했는가?npm run lint를 통과했는가?npm run test:run을 통과했는가?npm run build를 통과했는가?- S3 sync 대상 버킷이 맞는가?
- CloudFront invalidation을 실행했는가?
- SPA 라우팅 새로고침이 정상인가?
- 배포 후 Smoke Test를 완료했는가?
- 롤백할 이전 버전 기준이 있는가?
➕ 25-3. 캐시 체크리스트
index.html 캐시가 너무 길지 않은가?- hashed JS/CSS assets는 장기 캐시 가능한가?
- 배포 후 이전 파일 캐시 문제를 고려했는가?
- CloudFront invalidation 경로가 적절한가?
- 이미지 파일명 변경/캐시 정책이 정리되어 있는가?
- Chunk Load Error 대응 기준이 있는가?
- 배포 직후 새로고침으로 최신 버전이 보이는가?
- 관리자 화면 버전 표시가 있는가?
➕ 25-4. 모니터링 체크리스트
- 프론트 JS 에러를 확인할 방법이 있는가?
- ErrorBoundary가 적용되어 있는가?
- API 401/403/500 처리가 구분되어 있는가?
- Chunk Load Error 대응이 있는가?
- 상담 신청 성공/실패 이벤트를 추적할 수 있는가?
- 관리자 주요 액션 실패를 확인할 수 있는가?
- 운영 콘솔에 개인정보 로그가 남지 않는가?
- 배포 버전/commit hash를 확인할 수 있는가?
📌 요약
- 프론트엔드 배포는 빌드 결과물을 올리는 것뿐 아니라 환경변수, API 주소, 캐시, CDN, 롤백, 배포 후 확인까지 포함하는 운영 작업입니다.
- 프론트엔드 환경변수는 브라우저에 노출될 수 있으므로
JWT_SECRET, AWS_SECRET_ACCESS_KEY, DATABASE_URL, 알림톡 API Key 같은 Secret을 절대 넣으면 안 됩니다.
- API Base URL은 로컬/스테이징/운영 환경별로 분리하고, 배포 후 Network 탭에서 실제 호출 주소를 확인해야 합니다.
- S3 + CloudFront 배포에서는 SPA 라우팅 새로고침 404 문제,
index.html 캐시, assets 장기 캐시, CloudFront invalidation을 반드시 고려해야 합니다.
index.html은 최신 JS/CSS 파일명을 참조해야 하므로 오래 캐시하면 위험하고, hash가 붙은 JS/CSS assets는 장기 캐시에 적합합니다.- 배포 전에는
npm run lint, npm run test:run, npm run build를 실행하고, 환경변수/API 계약/공통 컴포넌트 변경 여부를 확인해야 합니다.
- 배포 후에는 고객 상품 상세, 상담 신청 모달, 관리자 로그인, 상담 목록, 검색/필터, 권한 버튼 같은 핵심 흐름을 Smoke Test로 확인해야 합니다.
- 프론트엔드 에러는 서버 로그에 남지 않을 수 있으므로 ErrorBoundary, Sentry류 도구, 핵심 이벤트 모니터링을 고려해야 합니다.
- 운영 콘솔에는 토큰, 사용자 정보, 전화번호, 이름, 상담 메모, API 응답 전체를 남기면 안 됩니다.
- 배포 절차와 롤백 방법은 문서화해두면 실수를 줄이고, 나중에 GitHub Actions나 AI 자동화로 확장하기 쉽습니다.
