FirstBoot Guides

개발 환경 에러 해결 가이드 50선

초기 세팅 시 발생하는 각종 에러들의 원인과 해결 방법을 빠르게 찾아보세요.

환경 변수 & 경로

  • 'command' is not recognized...: 시스템 PATH 설정 확인
  • JAVA_HOME is not set: JDK 설치 경로 변수 등록
  • Permission denied: sudo 사용 또는 파일 권한 변경
  • Command not found: 쉘 프로필(.zshrc, .bashrc) 소스 확인
  • 경로 내 공백/한글 문제: 영문 위주 경로 권장

네트워크 & 프록시

  • Connection refused: 포트 충돌 또는 서비스 미실행
  • SSL Certificate Error: 사내 SSL Inspection 때문일 수 있음 (npm config set strict-ssl false)
  • Git Self signed certificate: SSL 검증 해제 git config --global http.sslVerify false
  • npm/pip Proxy Error: 사내망 프록시 설정 (예: npm config set proxy ...)
  • Docker Timeout: WSL2 가상 네트워크 충돌 또는 Proxy 설정 누락

Git & 권한

  • Permission denied (publickey): SSH 키 등록 여부 및 ssh-agent 확인
  • Git credential manager: 패스워드 변경 후 인증 실패 시 자격 증명 관리자 초기화
  • Git Submodule 누락: git submodule update --init --recursive
  • Windows 한글 경로 이슈: 프로젝트 폴더는 가급적 C:\dev 등 영문 짧은 경로 추천
  • WSL2 Docker 네트워크 충돌: wsl --shutdown 후 재시작

패키지 매니저 (npm, yarn, pip)

  • node-gyp 에러: Python/C++ 빌드 도구 누락
  • peerDependencies 충돌: --force 또는 버전 조정
  • Requirement already satisfied: 가상환경(venv) 활성 확인
  • npm EACCES: 전역 설치 시 권한 이슈 (nvm 권장)
  • Lock file 충돌: 캐시 삭제 및 재설치

인코딩 & 폰트

  • 한글 깨짐 (UTF-8): IDE/터미널 인코딩 설정 일치
  • 터미널 아이콘 깨짐: Nerd Font 설치 및 적용
  • Line Ending (LF/CRLF): Git autocrlf 설정
  • MySQL 한글 입력 불가: utf8mb4 설정 확인

* 현재 50가지 사례를 업데이트 중입니다. 추가 요청은 GitHub 이슈를 이용해주세요.