zenn/playuniare.sori.studio

Fork 0

Files

zenn 314c98fe66 feat: expand experimental online multiplayer

2026-06-22 10:48:42 +09:00

5.5 KiB

Raw Permalink Blame History

로컬 개발과 테스트 실행 안내

처음 한 번만 준비하기

1. Node.js 확인

터미널에서 실행한다.

node --version
npm --version

두 명령 모두 버전 번호가 출력되어야 한다. 명령을 찾을 수 없다는 메시지가 나오면 Node.js LTS 버전을 먼저 설치한다.

2. 프로젝트 폴더로 이동

cd /Users/bicute/Desktop/dxp6800pro/uniare-simulator

3. 패키지 설치

프로젝트를 처음 받았거나 package.json이 변경되었을 때 실행한다.

npm install

node_modules는 자동 생성되며 Git에 올리지 않는다.

개발 서버 실행

가장 간단한 방법은 프로젝트 폴더에서 다음 명령 하나를 실행하는 것이다.

npm run dev:all

이 명령은 Vue 개발 서버와 Socket.IO 서버를 동시에 실행한다. 화면에 표시되는 Vite의 Local 주소를 브라우저에서 연다.

각 서버 로그를 별도 터미널에서 보고 싶다면 터미널 두 개를 연다.

첫 번째 터미널에서 Socket.IO 서버를 실행한다.

npm run dev:server

두 번째 터미널에서 Vue 개발 서버를 실행한다.

npm run dev

터미널에 다음과 비슷한 주소가 표시된다.

Local: http://localhost:5173/

해당 주소를 브라우저에서 연다. 개발 중 코드를 저장하면 화면이 자동으로 갱신된다.

Vite는 브라우저의 /socket.io 요청을 로컬 31873 포트로 전달한다. 두 개발 서버를 종료하려면 각각의 터미널에서 Control + C를 누른다. npm run dev:all을 사용했다면 해당 터미널에서 Control + C를 한 번 누르면 두 서버가 함께 종료된다.

Vue 파일 변경은 자동으로 화면에 반영된다.
server/ 파일을 변경한 경우에는 Control + C로 종료한 뒤 npm run dev:all을 다시 실행한다.

같은 네트워크의 다른 기기에서 테스트

npm run dev -- --host

터미널의 Network 주소를 같은 공유기에 연결된 휴대전화나 태블릿에서 연다. macOS 방화벽이 연결 허용 여부를 물으면 개발 중에만 허용한다.

배포용 빌드 확인

코드 변경을 완료하기 전에 반드시 실행한다.

npm run build

성공하면 dist/ 폴더가 생성된다. 오류가 발생하면 배포하지 말고 오류를 먼저 수정한다.

빌드 결과를 로컬에서 확인하려면 다음을 실행한다.

npm run preview

개발 서버와 마찬가지로 터미널에 표시된 주소로 접속한다.

환경변수 사용

로컬 전용 값은 프로젝트 루트의 .env.local에 작성한다.

VITE_CARD_ASSET_BASE_URL=http://playuniare.sori.studio/card-assets

VITE_로 시작하는 값은 브라우저에 노출될 수 있다.
비밀번호, 개인키, NAS 관리자 계정은 넣지 않는다.
.env.local은 Git에 커밋하지 않는다.
로컬 개발에서 실제 카드 이미지를 확인하려면 운영 카드 자산 주소를 VITE_CARD_ASSET_BASE_URL에 사용한다.

일반적인 작업 순서

git pull
npm install
npm run dev:all

작업이 끝난 뒤:

npm run test:server
npm run build
git status

npm run test:server는 npm run dev:server가 실행 중일 때 방 생성, 참가, 덱 등록, 양쪽 준비와 게임 시작 이벤트를 검증한다.

변경 문서를 확인한 후 커밋하고 푸시한다.

자주 발생하는 문제

포트가 이미 사용 중이라고 나오는 경우

Vite가 다른 포트를 자동으로 제시할 수 있다. 터미널에 새로 표시된 주소로 접속한다. 반드시 5173 포트를 고정할 필요는 없다.

로컬 Socket.IO 서버는 기본적으로 31873 포트를 사용한다. 이 포트가 이미 사용 중이면 두 터미널에서 같은 환경변수를 사용한다.

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에서는 발생하지 않아야 한다. 기존 터미널을 모두 종료하고 다음 명령을 다시 실행한다.

npm install
npm run dev:all

패키지 오류가 발생하는 경우

먼저 다음을 다시 실행한다.

npm install
npm run build

문제가 지속되면 오류 전문과 Node.js 버전을 기록하고 임의로 대규모 패키지 업데이트를 하지 않는다.

카드 이미지가 보이지 않는 경우

덱의 series 값이 올바른지 확인한다.
이미지 파일명이 실제 파일과 같은지 확인한다.
VITE_CARD_ASSET_BASE_URL 값 끝에 불필요한 경로가 없는지 확인한다.
브라우저 개발자 도구의 Network 탭에서 404 또는 CORS 오류를 확인한다.

5.5 KiB Raw Permalink Blame History