97 lines
3.0 KiB
Markdown
97 lines
3.0 KiB
Markdown
# 프론트엔드 디버깅 환경 구축 및 Windsurf 디버깅 가이드
|
|
|
|
이 문서는 본 프로젝트(Next.js 기반 프론트엔드)에서 Windsurf 및 브라우저/VSCode를 활용해 효율적으로 디버깅하는 방법을 안내합니다.
|
|
|
|
---
|
|
|
|
## 1. 개발 환경 준비
|
|
|
|
### 1) Node.js 및 패키지 설치
|
|
- Node.js 18.x 이상 필요
|
|
- 루트 디렉토리에서:
|
|
```bash
|
|
npm install
|
|
# 또는
|
|
pnpm install
|
|
```
|
|
|
|
### 2) 환경 변수 파일 준비
|
|
- `.env.local` 등 환경 변수 파일을 복사/생성합니다.
|
|
- API 엔드포인트 등 민감 정보는 환경 변수로 관리하세요.
|
|
|
|
### 3) Next.js 개발 서버 실행
|
|
- 아래 명령어로 개발 서버 실행:
|
|
```bash
|
|
npm run dev
|
|
# 또는
|
|
pnpm dev
|
|
```
|
|
- 기본 포트: `3000` (필요시 `.env` 또는 `package.json`에서 변경)
|
|
|
|
---
|
|
|
|
## 2. Windsurf 디버깅 환경 구축
|
|
|
|
### 1) 소스맵 활성화
|
|
- Next.js는 개발 모드에서 자동으로 소스맵을 제공합니다.
|
|
- 별도 설정 없이 브라우저에서 TypeScript/JSX 소스 디버깅 가능.
|
|
|
|
### 2) 브라우저 디버깅
|
|
- Chrome/Edge 등에서 F12 → `Sources` 탭에서 실제 소스 파일에 브레이크포인트 설정.
|
|
- step-by-step 실행, 변수 값 확인, 콜스택 추적 가능.
|
|
|
|
### 3) VSCode 디버깅 (선택)
|
|
- `.vscode/launch.json` 파일 생성:
|
|
```json
|
|
{
|
|
"version": "0.2.0",
|
|
"configurations": [
|
|
{
|
|
"type": "chrome",
|
|
"request": "launch",
|
|
"name": "Next.js: Chrome 브라우저에서 디버깅",
|
|
"url": "http://localhost:3000",
|
|
"webRoot": "${workspaceFolder}"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
- VSCode에서 디버깅 세션 시작 → 브레이크포인트, 변수 추적 가능.
|
|
|
|
### 4) Windsurf 연동
|
|
- Windsurf에서 “로컬 서버 연결” 기능으로 `http://localhost:3000` 접속.
|
|
- 브라우저 프리뷰, 콘솔 로그, 네트워크 요청, 소스맵 기반 디버깅 가능.
|
|
- "디버깅 세션 시작" 버튼 클릭 시 브라우저 개발자 도구와 동일하게 동작.
|
|
|
|
---
|
|
|
|
## 3. 디버깅 팁
|
|
|
|
- **핫 리로드**: 코드 수정 시 자동 반영.
|
|
- **React DevTools**: 컴포넌트 상태, props, hooks 실시간 확인.
|
|
- **네트워크 탭**: API 요청/응답 실시간 확인.
|
|
- **에러 오버레이**: Next.js가 런타임/빌드 에러를 화면에 표시.
|
|
|
|
---
|
|
|
|
## 4. 문제 해결 체크리스트
|
|
|
|
- **빌드/런타임 에러**: 터미널과 브라우저 메시지 확인.
|
|
- **API 통신 문제**: 네트워크 탭에서 요청/응답 확인, 환경 변수 및 서버 상태 점검.
|
|
- **소스맵 미작동**: `next.config.js` 등에서 소스맵 관련 옵션 확인.
|
|
|
|
---
|
|
|
|
## 5. Windsurf 디버깅 절차 요약
|
|
|
|
1. 의존성 설치 및 개발 서버 실행 (`npm run dev`)
|
|
2. Windsurf에서 “로컬 서버 연결”로 `http://localhost:3000` 접속
|
|
3. 브라우저 프리뷰에서 UI/네트워크/콘솔/소스 디버깅
|
|
4. 필요시 VSCode에서 브레이크포인트 디버깅 병행
|
|
|
|
---
|
|
|
|
## 참고
|
|
- Next.js 공식문서: https://nextjs.org/docs
|
|
- Windsurf 공식문서 및 지원 채널 참고
|