Appendix C. 실습 환경 트러블슈팅 5대 FAQ

"개발자가 가장 지치고 포기하고 싶을 때는 코드가 어려울 때가 아니라, 환경 설정과 사소한 에러 때문에 화면이 안 뜰 때이다. 사내 실습 시 99% 확률로 마주치는 5대 이슈의 해결책을 사전에 제공한다."

FAQ 1. `npm run dev` 실행 시 3000번 포트가 충돌하여 3001번으로 떠요

[증상]

터미널에 Port 3000 is in use, trying another one... 이라는 메시지가 뜨면서 브라우저 주소가 http://localhost:3001로 열립니다.

[원인 및 영향]

이전에 실행했던 Vite 프로세스가 백그라운드에 남아있거나, 사내 다른 개발 서버가 3000번 포트를 점유하고 있는 경우입니다.
포트가 3001로 바뀌더라도 Vite의 리버스 프록시(/api → 8080)는 정상 작동하지만, 교재 가이드와 포트 번호가 달라 헷갈릴 수 있습니다.

[해결 방법]

점유 중인 3000번 포트 강제 종료 (Windows PowerShell 기준):

powershell

   Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process -Force

포트를 3000번으로 엄격히 고정하려면 (vite.config.ts):

typescript

   export default defineConfig({
     server: {
       port: 3000,
       strictPort: true // 3000번이 점유 중이면 3001로 넘어가지 않고 에러를 내어 알려줌
     }
   });

FAQ 2. VS Code에서 `.vue` 파일에 온통 빨간 줄이 뜨고 타입 완성이 안 돼요

[증상]

코드는 브라우저에서 잘 돌아가는데, VS Code 에디터 안에서 <script setup>이나 import 구문에 빨간 줄(에러)이 그어집니다.

[원인]

VS Code의 기본 내장 TypeScript 언어 서버가 .vue 단일 파일 컴포넌트(SFC)를 자바스크립트로 해석하지 못해 발생하는 현상입니다.

[해결 방법]

VS Code 마켓플레이스에서 Vue - Official (구 Volar) 확장 프로그램을 반드시 설치합니다. (과거의 Vetur 익스텐션은 완전히 삭제하거나 비활성화해야 충돌이 나지 않습니다.)
Ctrl + Shift + P → TypeScript: Select TypeScript Version 입력 → **Use Workspace Version (프로젝트 로컬 TS)**을 선택합니다.

FAQ 3. Spring Boot 실행 시 `class file has wrong version ...` 에러가 나요

[증상]

backend/ 폴더에서 ./mvnw spring-boot:run (또는 .\mvnw.cmd spring-boot:run)을 쳤을 때 빌드가 멈추며 자바 버전 관련 컴파일 에러가 발생합니다.

[원인]

본 프로젝트는 Java 21 (LTS, 클래스 버전 65.0) 기준으로 설정되어 있습니다. PC의 터미널 기본 JAVA_HOME이 이전 버전(Java 17, 11, 8 등)으로 잡혀있는 경우입니다.

[해결 방법]

터미널에서 자바 버전 확인:

bash

   java -version

Java 21이 아니라면, JDK 21(Eclipse Temurin 21, Microsoft OpenJDK 21 등)을 설치한 후 터미널 세션의 JAVA_HOME을 지정합니다:

powershell

# [Windows PowerShell] 본인의 JDK 21 설치 경로 지정 예시
$env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-21.0.x-hotspot"
$env:Path = "$env:JAVA_HOME\bin;" + $env:Path
.\mvnw.cmd spring-boot:run

bash

# [macOS / Linux] 터미널 지정 예시
export JAVA_HOME=$(/usr/libexec/java_home -v 21 2>/dev/null || echo "/usr/lib/jvm/temurin-21-jdk-amd64")
export PATH="$JAVA_HOME/bin:$PATH"
./mvnw spring-boot:run

FAQ 4. `http://localhost:8080/h2-console` 접속 시 `Database ... not found` 에러가 나요

[증상]

브라우저로 H2 콘솔에 접속해 [Connect] 버튼을 눌렀는데, Database "mem:test" not found 또는 테이블이 하나도 안 보이는 빈 화면이 뜹니다.

[원인]

H2 콘솔 로그인 화면의 JDBC URL 기본값이 jdbc:h2:~/test 같은 로컬 파일 경로로 잘못 입력되어 있기 때문입니다.

[해결 방법]

H2 웹 콘솔 로그인 화면에서 JDBC URL 입력칸을 우리 프로젝트의 application.yml 설정과 정확히 동일하게 수정하고 연결하십시오:
- JDBC URL: jdbc:h2:mem:boarddb (반드시 mem:boarddb로 입력!)
- User Name: sa
- Password: (빈칸 유지)

FAQ 5. Windows PowerShell에서 `./mvnw` 실행 시 "스크립트를 실행할 수 없습니다" 에러가 떠요

[증상]

PowerShell에서 ./mvnw spring-boot:run을 입력하면 빨간색 글씨로 ...이 시스템에서 스크립트를 실행할 수 없으므로... Execution_Policies 에러가 발생합니다.

[원인]

Windows의 기본 보안 정책이 로컬 파워쉘 스크립트 실행을 제한(Restricted)하고 있기 때문입니다.

[해결 방법]

Windows CMD/PowerShell에서는 .ps1이 아닌 배치 파일인 .\mvnw.cmd spring-boot:run을 실행하면 별도의 정책 변경 없이 즉시 실행됩니다.
혹은 PowerShell을 관리자 권한으로 실행하여 스크립트 실행 권한을 부여합니다:

powershell

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

[Y] 예를 입력하고 터미널을 다시 켜면 ./mvnw도 정상 실행됩니다.

Appendix C. 실습 환경 트러블슈팅 5대 FAQ ​

FAQ 1. npm run dev 실행 시 3000번 포트가 충돌하여 3001번으로 떠요 ​

[증상] ​

[원인 및 영향] ​

[해결 방법] ​

FAQ 2. VS Code에서 .vue 파일에 온통 빨간 줄이 뜨고 타입 완성이 안 돼요 ​

[증상] ​

[원인] ​

[해결 방법] ​

FAQ 3. Spring Boot 실행 시 class file has wrong version ... 에러가 나요 ​

[증상] ​

[원인] ​

[해결 방법] ​

FAQ 4. http://localhost:8080/h2-console 접속 시 Database ... not found 에러가 나요 ​

[증상] ​

[원인] ​

[해결 방법] ​

FAQ 5. Windows PowerShell에서 ./mvnw 실행 시 "스크립트를 실행할 수 없습니다" 에러가 떠요 ​

[증상] ​

[원인] ​

[해결 방법] ​

Appendix C. 실습 환경 트러블슈팅 5대 FAQ

FAQ 1. `npm run dev` 실행 시 3000번 포트가 충돌하여 3001번으로 떠요

[증상]

[원인 및 영향]

[해결 방법]

FAQ 2. VS Code에서 `.vue` 파일에 온통 빨간 줄이 뜨고 타입 완성이 안 돼요

[증상]

[원인]

[해결 방법]

FAQ 3. Spring Boot 실행 시 `class file has wrong version ...` 에러가 나요

[증상]

[원인]

[해결 방법]

FAQ 4. `http://localhost:8080/h2-console` 접속 시 `Database ... not found` 에러가 나요

[증상]

[원인]

[해결 방법]

FAQ 5. Windows PowerShell에서 `./mvnw` 실행 시 "스크립트를 실행할 수 없습니다" 에러가 떠요

[증상]

[원인]

[해결 방법]