개발 환경 세팅은 입문자가 가장 먼저 겪는 현실적인 장벽입니다. 저도 처음에는 VS Code나 Node.js, Git만 설치하면 바로 공부를 시작할 수 있을 줄 알았습니다. 하지만 강의와 같은 코드를 입력해도 실행되지 않았고, 알고 보니 원인은 코드가 아니라 버전 차이와 PATH 설정 문제였습니다. 특히 최신 버전이 무조건 좋은 줄 알고 설치했다가 강의 환경과 맞지 않아 오류를 겪었고, Git을 나중으로 미뤘다가 코드 변경 이력을 남기지 못한 경험도 있었습니다. 저는 그때 개발 환경 세팅이 단순한 준비 작업이 아니라 문제 해결 능력을 기르는 첫 단계라고 느꼈습니다. 이 글에서는 개발 입문자가 처음 환경을 세팅할 때 자주 하는 실수와 해결 방향을 제 경험을 바탕으로 정리해 보겠습니다.
개발 환경 세팅, 버전 하나 차이가 전부를 바꾼다
제가 직접 겪어봤는데, 버전 문제는 정말 예상 밖이었습니다. 강의에서는 멀쩡히 돌아가는 코드가 제 컴퓨터에서는 빨간 오류로 가득 찼고, 원인을 찾는 데만 반나절이 걸렸습니다. 나중에 확인해 보니 Node.js 버전이 강의는 18이었고 저는 최신 버전인 22를 설치해 두었던 겁니다. 입문자는 최신 버전이 무조건 좋다고 생각하는 경향이 있는데, 개발 공부에서는 꼭 그렇지 않습니다. Node.js의 경우 LTS(Long Term Support) 버전을 기준으로 강의나 프로젝트가 만들어지는 경우가 많습니다. 여기서 LTS란 장기 안정 지원 버전을 의미합니다. 쉽게 말해 기업이나 교육 현장에서 가장 널리 쓰이는 안정화된 버전입니다. Python도 마찬가지입니다. 3.8과 3.12는 같은 Python이지만 일부 라이브러리의 호환성이 달라질 수 있습니다(출처: Python 공식 문서). Java 역시 JDK 8, 11, 17, 21처럼 LTS 버전마다 문법과 프로젝트 설정 방식이 다릅니다.
세팅 전에 반드시 확인해야 할 목록은 다음과 같습니다.
- 강의 또는 프로젝트에서 명시한 언어 버전
- 사용하는 패키지 관리자(npm, pip, Maven 등)의 권장 버전
- 프레임워크 공식 문서의 환경 요구 사항
- 운영체제별 설치 방식 차이
설치 후에는 터미널에서 node -v, python --version, java -version 명령어로 반드시 버전을 확인하는 습관이 필요합니다. 이 한 줄 확인이 나중에 몇 시간의 디버깅을 줄여줍니다.
PATH를 모르면 설치가 의미 없다
터미널에 명령어를 입력했을 때 “command not found”가 뜨는 상황, 저도 처음에 정말 당황했습니다. 분명히 프로그램을 설치했는데 컴퓨터가 모른다고 하니까요. 이게 바로 PATH 문제입니다. PATH(환경 변수)란 운영체제가 실행 파일을 탐색하는 경로 목록입니다. 쉽게 말해 터미널에서 git이나 python을 입력했을 때, 컴퓨터가 그 프로그램이 어디 있는지 찾아보는 주소록입니다. 아무리 프로그램을 설치해도 이 주소록에 등록되지 않으면 터미널은 해당 명령어를 실행하지 못합니다. 일반적으로 설치 프로그램이 자동으로 PATH를 등록해 준다고 알려져 있지만, 제 경험상 윈도에서는 수동으로 확인하거나 직접 설정해야 하는 경우가 꽤 있었습니다. 특히 Python을 Anaconda와 기본 인스톨러 두 가지 방식으로 설치하면 환경 변수가 충돌해 터미널에서 인식되는 버전과 VS Code에서 인식하는 버전이 달라지는 상황이 생깁니다.
오류가 났을 때 메시지를 읽지 않고 바로 검색하는 분들도 있는데, 저는 오류 메시지를 먼저 읽는 것이 훨씬 빠른 해결책이라고 생각합니다. 자주 등장하는 오류 키워드만 알아도 방향이 잡힙니다. permission denied는 권한 문제, module not found는 패키지 미설치, version mismatch는 버전 불일치를 의미합니다. 메시지 안에 단서가 이미 있습니다(출처: MDN Web Docs - 개발 환경 설정).
개발 환경 세팅과 Git, 처음부터 같이 잡아야 하는 이유
Git을 나중에 써도 된다고 생각하는 분들도 있는데, 저는 처음부터 함께 세팅하는 것이 정답이라고 생각합니다. 직접 경험해 봤는데, Git 없이 며칠 동안 코드를 수정하다가 이전 상태로 돌아가야 하는 상황이 생겼을 때 방법이 없었습니다. 그냥 처음부터 다시 작성해야 했습니다. Git이란 버전 관리 시스템(VCS, Version Control System)입니다. 쉽게 말해 코드 변경 이력을 날짜별로 기록해 두는 타임머신 같은 도구입니다. 완성된 코드를 올리는 것이 아니라, 작업 중간중간 의미 있는 단위로 저장하는 것이 핵심입니다.
처음 세팅할 때 Git 기본 설정을 함께 잡아두는 것이 좋습니다. git --version으로 설치 확인, 사용자 이름과 이메일 등록, GitHub 계정 연동까지 한 번에 처리해 두면 나중에 따로 시간을 쓰지 않아도 됩니다. 프로젝트 폴더 위치도 이때 함께 정리하는 것이 좋습니다. 바탕화면이나 다운로드 폴더에 프로젝트를 만들면 한글 경로, 공백, 깊은 디렉터리 문제가 생길 수 있습니다. C:\dev 또는 /Users/name/dev처럼 짧고 영문으로 된 전용 폴더 하나를 만들어 두면 터미널 이동도 편하고 패키지 설치 오류도 줄어듭니다. 세팅 과정은 메모장이나 README에 기록해 두면, 컴퓨터를 바꾸거나 팀원이 동일한 환경을 구성할 때 큰 도움이 됩니다(출처: GitHub Docs - Git 시작하기).
처음 개발 환경 세팅에서 겪는 시행착오는 단순한 실수가 아닙니다. 버전을 확인하고, PATH가 왜 필요한지 이해하고, Git을 처음부터 쓰는 습관이 쌓이면 나중에 훨씬 복잡한 환경 문제도 스스로 풀 수 있게 됩니다. 지금 당장 완벽한 환경을 만들 필요는 없습니다. 필요한 도구만 설치하고, 버전을 확인하고, 오류 해결 과정을 한 줄이라도 기록하는 것부터 시작하면 충분합니다.