161 lines
5.7 KiB
Markdown
161 lines
5.7 KiB
Markdown
# 개발(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) 원리
|
|
1. **`NEXT_PUBLIC_*` 변수의 빌드타임 주입**:
|
|
- `NEXT_PUBLIC_SERVER_API_URL`, `NEXT_PUBLIC_PROXY_HOST`, `NEXT_PUBLIC_WEBHYP_CTRL_URL` 등 브라우저에서 참조하는 변수들은 `next build` 시점에 생성되는 클라이언트 JavaScript 파일(`.next/static/...`) 안에 **문자열 값으로 직접 하드코딩(Inlining)**됩니다.
|
|
- 따라서 코드를 다시 빌드하지 않으면 예전 주소나 설정값이 그대로 유지됩니다.
|
|
2. **정적 페이지(SSG) 생성 시점의 값 고정**:
|
|
- 빌드 시 정적 생성된 페이지(`Generating static pages (22/22)`)는 빌드 당시 읽어들인 환경변수 값을 기준으로 생성되므로, 런타임에 환경변수를 바꿔도 페이지가 갱신되지 않습니다.
|
|
|
|
### 2.3 환경변수 우선순위 주의사항
|
|
Next.js의 환경변수 로딩 우선순위는 다음과 같습니다:
|
|
|
|
```text
|
|
[운영 환경: 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 프로젝트 루트 디렉터리에서 실행
|
|
```bash
|
|
# 루트 디렉터리: ~/frontend_as
|
|
pnpm dev:as
|
|
|
|
# 또는 pnpm filter 플래그 사용
|
|
pnpm --filter as dev
|
|
```
|
|
|
|
### 3.2 `apps/as` 디렉터리 내부에서 실행
|
|
```bash
|
|
cd ~/frontend_as/apps/as
|
|
pnpm dev
|
|
```
|
|
|
|
- **접속 주소**: [http://localhost:3004](http://localhost:3004)
|
|
- **종료**: 터미널에서 `Ctrl + C`
|
|
|
|
---
|
|
|
|
## 4. Production (운영 모드) 실행 방법
|
|
|
|
반드시 **빌드 산출물(`.next`)이 최신 상태로 생성되어 있어야 정상 실행**됩니다.
|
|
|
|
### 4.1 1단계: 프로덕션 빌드 (필수)
|
|
모노레포 전체를 빌드할 필요 없이 `as` 앱만 단독으로 빌드할 수 있습니다:
|
|
|
|
```bash
|
|
# 프로젝트 루트 디렉터리에서 실행 (약 20~30초 소요)
|
|
pnpm build:as
|
|
|
|
# 또는
|
|
pnpm --filter as build
|
|
```
|
|
|
|
---
|
|
|
|
### 4.2 2단계: 서버 프로세스 실행
|
|
|
|
#### 방법 A: 터미널에서 직접 실행 (로컬 프로덕션 점검용)
|
|
포그라운드 터미널에서 프로덕션 번들의 빌드 결과와 동작을 직접 테스트할 때 사용합니다:
|
|
|
|
```bash
|
|
# 루트 디렉터리에서 실행
|
|
pnpm --filter as start
|
|
|
|
# 또는 apps/as 디렉터리에서 실행
|
|
cd apps/as
|
|
pnpm start
|
|
```
|
|
|
|
---
|
|
|
|
#### 방법 B: PM2 프로세스 매니저로 실행 (실서버 운영 표준)
|
|
실제 운영 서버에서는 `ecosystem.config.js` 설정을 통해 무중단 클러스터(2개 인스턴스)로 실행합니다.
|
|
|
|
```bash
|
|
# 1. 프로세스가 아직 등록되지 않은 경우 (최초 기동)
|
|
pm2 start ecosystem.config.js --only as2-app
|
|
|
|
# 2. 이미 실행 중인 경우 (무중단 롤링 리로드 - 권장)
|
|
# 순차적으로 인스턴스를 재시작하므로 사용자 요청 끊김이 없습니다.
|
|
pm2 reload as2-app
|
|
|
|
# 3. 프로세스 완전 재시작이 필요한 경우
|
|
pm2 restart as2-app
|
|
```
|
|
|
|
---
|
|
|
|
## 5. PM2 운영 및 모니터링 치트시트
|
|
|
|
```bash
|
|
# 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단계를 수행합니다:
|
|
|
|
```bash
|
|
# Step 1. 최신 코드 반영 (필요시)
|
|
git pull origin deploy
|
|
|
|
# Step 2. as 앱 단독 프로덕션 재빌드
|
|
pnpm build:as
|
|
|
|
# Step 3. PM2 무중단 롤링 리로드
|
|
pm2 reload as2-app
|
|
```
|