196 lines
5.5 KiB
Markdown
196 lines
5.5 KiB
Markdown
# 로컬 개발과 테스트 실행 안내
|
|
|
|
## 처음 한 번만 준비하기
|
|
|
|
### 1. Node.js 확인
|
|
|
|
터미널에서 실행한다.
|
|
|
|
```bash
|
|
node --version
|
|
npm --version
|
|
```
|
|
|
|
두 명령 모두 버전 번호가 출력되어야 한다. 명령을 찾을 수 없다는 메시지가
|
|
나오면 Node.js LTS 버전을 먼저 설치한다.
|
|
|
|
### 2. 프로젝트 폴더로 이동
|
|
|
|
```bash
|
|
cd /Users/bicute/Desktop/dxp6800pro/uniare-simulator
|
|
```
|
|
|
|
### 3. 패키지 설치
|
|
|
|
프로젝트를 처음 받았거나 `package.json`이 변경되었을 때 실행한다.
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
`node_modules`는 자동 생성되며 Git에 올리지 않는다.
|
|
|
|
## 개발 서버 실행
|
|
|
|
가장 간단한 방법은 프로젝트 폴더에서 다음 명령 하나를 실행하는 것이다.
|
|
|
|
```bash
|
|
npm run dev:all
|
|
```
|
|
|
|
이 명령은 Vue 개발 서버와 Socket.IO 서버를 동시에 실행한다. 화면에 표시되는
|
|
Vite의 `Local` 주소를 브라우저에서 연다.
|
|
|
|
각 서버 로그를 별도 터미널에서 보고 싶다면 터미널 두 개를 연다.
|
|
|
|
첫 번째 터미널에서 Socket.IO 서버를 실행한다.
|
|
|
|
```bash
|
|
npm run dev:server
|
|
```
|
|
|
|
두 번째 터미널에서 Vue 개발 서버를 실행한다.
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
터미널에 다음과 비슷한 주소가 표시된다.
|
|
|
|
```text
|
|
Local: http://localhost:5173/
|
|
```
|
|
|
|
해당 주소를 브라우저에서 연다. 개발 중 코드를 저장하면 화면이 자동으로
|
|
갱신된다.
|
|
|
|
Vite는 브라우저의 `/socket.io` 요청을 로컬 `31873` 포트로 전달한다. 두
|
|
개발 서버를 종료하려면 각각의 터미널에서 `Control + C`를 누른다.
|
|
`npm run dev:all`을 사용했다면 해당 터미널에서 `Control + C`를 한 번 누르면
|
|
두 서버가 함께 종료된다.
|
|
|
|
- Vue 파일 변경은 자동으로 화면에 반영된다.
|
|
- `server/` 파일을 변경한 경우에는 `Control + C`로 종료한 뒤
|
|
`npm run dev:all`을 다시 실행한다.
|
|
|
|
## 같은 네트워크의 다른 기기에서 테스트
|
|
|
|
```bash
|
|
npm run dev -- --host
|
|
```
|
|
|
|
터미널의 `Network` 주소를 같은 공유기에 연결된 휴대전화나 태블릿에서 연다.
|
|
macOS 방화벽이 연결 허용 여부를 물으면 개발 중에만 허용한다.
|
|
|
|
## 배포용 빌드 확인
|
|
|
|
코드 변경을 완료하기 전에 반드시 실행한다.
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
성공하면 `dist/` 폴더가 생성된다. 오류가 발생하면 배포하지 말고 오류를 먼저
|
|
수정한다.
|
|
|
|
빌드 결과를 로컬에서 확인하려면 다음을 실행한다.
|
|
|
|
```bash
|
|
npm run preview
|
|
```
|
|
|
|
개발 서버와 마찬가지로 터미널에 표시된 주소로 접속한다.
|
|
|
|
## 환경변수 사용
|
|
|
|
로컬 전용 값은 프로젝트 루트의 `.env.local`에 작성한다.
|
|
|
|
```text
|
|
VITE_CARD_ASSET_BASE_URL=http://playuniare.sori.studio/card-assets
|
|
```
|
|
|
|
- `VITE_`로 시작하는 값은 브라우저에 노출될 수 있다.
|
|
- 비밀번호, 개인키, NAS 관리자 계정은 넣지 않는다.
|
|
- `.env.local`은 Git에 커밋하지 않는다.
|
|
- 로컬 개발에서 실제 카드 이미지를 확인하려면 운영 카드 자산 주소를
|
|
`VITE_CARD_ASSET_BASE_URL`에 사용한다.
|
|
|
|
## 일반적인 작업 순서
|
|
|
|
```bash
|
|
git pull
|
|
npm install
|
|
npm run dev:all
|
|
```
|
|
|
|
작업이 끝난 뒤:
|
|
|
|
```bash
|
|
npm run test:server
|
|
npm run build
|
|
git status
|
|
```
|
|
|
|
`npm run test:server`는 `npm run dev:server`가 실행 중일 때 방 생성, 참가,
|
|
덱 등록, 양쪽 준비와 게임 시작 이벤트를 검증한다.
|
|
|
|
변경 문서를 확인한 후 커밋하고 푸시한다.
|
|
|
|
## 자주 발생하는 문제
|
|
|
|
### 포트가 이미 사용 중이라고 나오는 경우
|
|
|
|
Vite가 다른 포트를 자동으로 제시할 수 있다. 터미널에 새로 표시된 주소로
|
|
접속한다. 반드시 5173 포트를 고정할 필요는 없다.
|
|
|
|
로컬 Socket.IO 서버는 기본적으로 `31873` 포트를 사용한다. 이 포트가 이미
|
|
사용 중이면 두 터미널에서 같은 환경변수를 사용한다.
|
|
|
|
```bash
|
|
SOCKET_SERVER_PORT=31874 npm run dev:server
|
|
SOCKET_SERVER_PORT=31874 npm run dev
|
|
```
|
|
|
|
운영에서는 `31873`을 Docker 내부에서만 사용하므로 NAS의 다른 컨테이너가
|
|
내부에서 같은 번호를 사용해도 충돌하지 않는다.
|
|
|
|
### 실시간 서버에 연결되지 않는 경우
|
|
|
|
- `npm run dev:server` 터미널이 실행 중인지 확인한다.
|
|
- 명령 하나로 실행하려면 기존 개발 서버를 모두 종료한 뒤
|
|
`npm run dev:all`을 사용한다.
|
|
- 서버 터미널에 `listening on port 31873` 메시지가 있는지 확인한다.
|
|
- 포트를 바꿨다면 Vue와 Socket.IO 서버를 같은 `SOCKET_SERVER_PORT`로
|
|
실행했는지 확인한다.
|
|
- 브라우저 개발자 도구 Network 탭에서 `/socket.io` 요청을 확인한다.
|
|
|
|
### `EMFILE: too many open files`가 나오는 경우
|
|
|
|
이 프로젝트의 기본 `dev:server`는 파일 감시를 사용하지 않으므로 최신
|
|
`package.json`에서는 발생하지 않아야 한다. 기존 터미널을 모두 종료하고
|
|
다음 명령을 다시 실행한다.
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev:all
|
|
```
|
|
|
|
### 패키지 오류가 발생하는 경우
|
|
|
|
먼저 다음을 다시 실행한다.
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
문제가 지속되면 오류 전문과 Node.js 버전을 기록하고 임의로 대규모 패키지
|
|
업데이트를 하지 않는다.
|
|
|
|
### 카드 이미지가 보이지 않는 경우
|
|
|
|
- 덱의 `series` 값이 올바른지 확인한다.
|
|
- 이미지 파일명이 실제 파일과 같은지 확인한다.
|
|
- `VITE_CARD_ASSET_BASE_URL` 값 끝에 불필요한 경로가 없는지 확인한다.
|
|
- 브라우저 개발자 도구의 Network 탭에서 404 또는 CORS 오류를 확인한다.
|