ONAANDALL/frontend

Fork 0

Files

T

changwng 177f4653c8 [as fr]pm2 통합방법

2026-10-20 16:29:33 +09:00

5.7 KiB

Raw Blame History

개발(Dev) 및 운영(Production) 실행 가이드 & 환경변수 관리

본 문서는 apps/as 애플리케이션의 개발(Dev) 모드 및 운영(Production) 모드 실행 방법과 환경변수(.env) 변경 시의 재빌드 규칙을 상세히 정리한 가이드입니다.

1. Dev 모드 vs Production 모드 비교

구분	개발 모드 (Dev)	운영 모드 (Production)
실행 목적	로컬 개발, 디버깅, 실시간 코드 수정	실서버 운영, 성능 최적화, 안정성 보장
사전 빌드 필요 여부	불필요 (즉시 실행)	필수 (`.next` 번들 생성 선행)
코드 반영 방식	핫 리로딩(HMR, 저장 즉시 반영)	빌드 시점의 번들링 코드 고정 서빙
참조 환경변수	`.env.local` > `.env.development`	`.env.local` > `.env.production`
프로세스 관리	Node 단일 프로세스 (터미널)	PM2 Cluster 모드 (2개 인스턴스 무중단)
서비스 포트	기본 `3004` 포트	기본 `3004` 포트

2. 환경변수(.env) 변경 시 재빌드 필수 여부

2.1 결론: `.env.production` 변경 시 반드시 재빌드 필요

Next.js 환경에서는 .env.production을 수정했을 때 단순히 PM2 재시작(pm2 reload / pm2 restart)만으로는 변경 사항이 브라우저에 반영되지 않으며, 반드시 빌드(next build)를 다시 수행해야 합니다.

2.2 이유: Next.js의 환경변수 인라이닝(Inlining) 원리

NEXT_PUBLIC_* 변수의 빌드타임 주입:
- NEXT_PUBLIC_SERVER_API_URL, NEXT_PUBLIC_PROXY_HOST, NEXT_PUBLIC_WEBHYP_CTRL_URL 등 브라우저에서 참조하는 변수들은 next build 시점에 생성되는 클라이언트 JavaScript 파일(.next/static/...) 안에 **문자열 값으로 직접 하드코딩(Inlining)**됩니다.
- 따라서 코드를 다시 빌드하지 않으면 예전 주소나 설정값이 그대로 유지됩니다.
정적 페이지(SSG) 생성 시점의 값 고정:
- 빌드 시 정적 생성된 페이지(Generating static pages (22/22))는 빌드 당시 읽어들인 환경변수 값을 기준으로 생성되므로, 런타임에 환경변수를 바꿔도 페이지가 갱신되지 않습니다.

2.3 환경변수 우선순위 주의사항

Next.js의 환경변수 로딩 우선순위는 다음과 같습니다:

[운영 환경: NODE_ENV=production]
1순위: .env.production.local
2순위: .env.local (NODE_ENV=test 제외 항상 최우선)
3순위: .env.production
4순위: .env

Warning

실서버 환경에 .env.local 파일이 존재할 경우 .env.production보다 우선 적용됩니다. .env.production을 수정했는데도 반영되지 않는다면 같은 경로에 .env.local이 존재하는지 확인하십시오.

3. Dev (개발 모드) 실행 방법

사전 빌드 과정 없이 소스 코드를 실시간으로 수정하며 개발할 때 사용합니다.

3.1 프로젝트 루트 디렉터리에서 실행

# 루트 디렉터리: ~/frontend_as
pnpm dev:as

# 또는 pnpm filter 플래그 사용
pnpm --filter as dev

3.2 `apps/as` 디렉터리 내부에서 실행

cd ~/frontend_as/apps/as
pnpm dev

접속 주소: http://localhost:3004
종료: 터미널에서 Ctrl + C

4. Production (운영 모드) 실행 방법

반드시 빌드 산출물(.next)이 최신 상태로 생성되어 있어야 정상 실행됩니다.

4.1 1단계: 프로덕션 빌드 (필수)

모노레포 전체를 빌드할 필요 없이 as 앱만 단독으로 빌드할 수 있습니다:

# 프로젝트 루트 디렉터리에서 실행 (약 20~30초 소요)
pnpm build:as

# 또는
pnpm --filter as build

4.2 2단계: 서버 프로세스 실행

방법 A: 터미널에서 직접 실행 (로컬 프로덕션 점검용)

포그라운드 터미널에서 프로덕션 번들의 빌드 결과와 동작을 직접 테스트할 때 사용합니다:

# 루트 디렉터리에서 실행
pnpm --filter as start

# 또는 apps/as 디렉터리에서 실행
cd apps/as
pnpm start

방법 B: PM2 프로세스 매니저로 실행 (실서버 운영 표준)

실제 운영 서버에서는 ecosystem.config.js 설정을 통해 무중단 클러스터(2개 인스턴스)로 실행합니다.

# 1. 프로세스가 아직 등록되지 않은 경우 (최초 기동)
pm2 start ecosystem.config.js --only as2-app

# 2. 이미 실행 중인 경우 (무중단 롤링 리로드 - 권장)
# 순차적으로 인스턴스를 재시작하므로 사용자 요청 끊김이 없습니다.
pm2 reload as2-app

# 3. 프로세스 완전 재시작이 필요한 경우
pm2 restart as2-app

5. PM2 운영 및 모니터링 치트시트

# 1. 전체 프로세스 상태 확인 (상태, 메모리, CPU 점유율 등)
pm2 status
# 또는
pm2 list

# 2. as2-app 실시간 로그 모니터링
pm2 logs as2-app

# 3. 최근 로그 100줄 출력
pm2 logs as2-app --lines 100

# 4. 프로세스 일시 중지 및 삭제
pm2 stop as2-app     # 프로세스 일시 중지
pm2 delete as2-app   # PM2 목록에서 제거

# 5. 서버 재부팅 시 자동 실행 등록
pm2 save             # 현재 실행 중인 프로세스 목록 저장
pm2 startup          # OS 부팅 스크립트 생성

6. 실무 배포 요약 워크플로우

.env.production 수정 또는 프론트엔드 코드 수정 후 배포 시 아래 3단계를 수행합니다:

# Step 1. 최신 코드 반영 (필요시)
git pull origin deploy

# Step 2. as 앱 단독 프로덕션 재빌드
pnpm build:as

# Step 3. PM2 무중단 롤링 리로드
pm2 reload as2-app

5.7 KiB Raw Blame History