Go 개발을 시작하기도 전에 좌절하는 이유
터미널에 go version을 입력했을 때 ‘command not found’라는 붉은 글씨가 뜨면 당혹스러울 수밖에 없어요. 분명히 공식 홈페이지에서 설치 파일을 내려받았는데 왜 컴퓨터는 Go가 무엇인지조차 모르는 걸까요? 이런 상황은 Go를 처음 접하는 입문 개발자라면 누구나 한 번쯤 겪게 되는 아주 흔한 통과의례예요.
설치 자체는 간단해 보이지만, 실제로 코드를 작성하고 실행하기까지의 과정에는 생각보다 많은 복잡한 설정이 숨어 있어요. 환경 변수라는 보이지 않는 지도가 잘못 그려져 있거나, 새로운 모듈 시스템인 Go Modules의 작동 방식을 오해하면 프로젝트 하나를 띄우는 데만 몇 시간을 허비하기도 해요. 잘못된 설정 하나가 개발의 흐름을 완전히 끊어버리는 셈이죠.
Go는 매우 강력하고 효율적인 언어지만, 그 효율성을 온전히 누리려면 먼저 탄탄한 개발 환경을 구축해야 해요. 엔진이 아무리 좋아도 연료가 들어가는 통로가 막혀 있으면 자동차는 달릴 수 없는 것과 마찬가지예요. 지금 겪고 계신 문제는 여러분의 실력이 부족해서가 아니라, 단지 환경 설정의 미묘한 차이 때문이에요.
이 글에서는 입문자들이 가장 많이 실수하는 지점들을 콕 집어 정리해 드릴게요. 문제를 해결하고 나면 여러분은 막힘없이 첫 번째 Go 프로그램을 실행할 수 있을 거예요.
- 가장 흔한 환경 변수(PATH) 설정 오류와 해결법
- Go Modules를 사용할 때 반드시 알아야 할 규칙
- IDE와 Go 언어 서버(gopls)의 연동 문제 해결
- 프로젝트 구조 설계 시 놓치기 쉬운 기본 원칙
환경 설정 전 반드시 확인해야 할 체크리스트
무작정 설치 파일을 실행하기 전에, 현재 자신의 컴퓨터 환경을 먼저 파악하는 것이 중요해요. 어떤 OS를 쓰는지, 어떤 터미널 환경에서 작업할 것인지에 따라 해결해야 할 문제의 종류가 완전히 달라지기 때문이에요.
첫 번째로 준비할 것은 운영체제에 맞는 적절한 설치 파일이에요. Windows 사용자라면 .msi 파일을, macOS 사용자라면 .pkg 파일을 사용하는 것이 가장 안전해요. Linux 사용자는 소스 코드를 직접 빌드하거나 패키지 관리자를 사용하는 방식 중 하나를 선택해야 하죠. 이때 주의할 점은 자신의 CPU 아키텍처(Intel/AMD 또는 Apple Silicon)를 정확히 확인해야 한다는 거예요.
Go를 설치하면 기본적으로 GOROOT와 GOPATH라는 두 가지 중요한 경로가 생겨요. GOROOT는 Go 언어 자체가 설치된 위치를 말하고, GOPATH는 여러분이 작업할 프로젝트나 다운로드한 라이브러리가 담기는 공간을 의미해요.
최근에는 Go Modules 덕분에 GOPATH의 제약이 많이 사라졌지만, 여전히 두 개념의 차이를 이해하지 못하면 경로 관련 오류에서 헤맬 수 있어요. 아래 표를 통해 자신의 개발 환경을 어떤 방향으로 설정할지 판단해 보세요.
| 구분 항목 | Go Modules 방식 (권장) | 기존 GOPATH 방식 (비권장) |
|---|---|---|
| 프로젝트 위치 | 어디든 자유롭게 생성 가능 | 반드시 $GOPATH/src 내부에 위치 |
| 의존성 관리 | go.mod 파일을 통한 정밀 관리 | GOPATH/pkg/mod에 자동 저장 |
| 학습 난이도 | 초기 개념 이해 필요 | 경로 규칙 숙지가 어려움 |
| 추천 대상 | 현대적인 모든 개발자 | 오래된 레거시 코드 유지보수자 |
대부분의 입문자라면 Go Modules 방식을 선택하는 것이 정답이에요. 프로젝트를 만들 때마다 `go mod init` 명령어를 사용하는 습관을 들이는 것이 나중에 발생할 경로 문제를 예방하는 가장 좋은 방법입니다. 이제 준비가 되었다면 본격적으로 설치와 설정을 진행해 볼게요.
완벽한 Go 개발 환경 구축을 위한 5단계 실행 가이드
단순히 설치를 마치는 것이 목표가 아니에요. 코드를 작성했을 때 자동 완성이 잘 되고, 라이브러리를 불러올 때 에러가 나지 않는 환경을 만드는 것이 핵심이죠. 다음 단계를 차근차근 따라와 주세요.
STEP 1. 운영체제별 최적화된 설치 프로세스
가장 먼저 해야 할 일은 공식 웹사이트에서 제공하는 바이너리를 사용하는 거예요. 운영체제마다 주의할 점이 조금씩 달라요.
- Windows: .msi 설치 파일을 실행하면 환경 변수(PATH)를 자동으로 등록하려고 시도해요. 하지만 설치가 끝난 후 반드시 새 터미널 창을 열어야 변경 사항이 적용된다는 점을 잊지 마세요.
- macOS: Homebrew를 사용한다면 `brew install go` 명령 한 줄로 끝낼 수 있어 매우 편리해요. 다만, Intel 칩과 Apple Silicon(M1/M2/M3) 칩의 아키텍처가 다르므로 본인의 Mac 종류를 반드시 확인하고 설치해야 성능 손실이 없어요.
- Linux: tar.gz 압축 파일을 내려받아 `/usr/local` 디렉토리에 직접 푸는 방식이 일반적이에요. 이 경우 권한 문제로 인해 설치가 막힐 수 있으니 `sudo` 명령어를 적절히 활용해야 해요.
이미 이전 버전의 Go가 설치되어 있다면, 반드시 기존 버전을 완전히 삭제하고 새 버전을 설치하세요. 여러 버전이 섞여 있으면 PATH 우선순위 때문에 엉뚱한 버전의 명령어가 실행될 수 있어요.
STEP 2. 환경 변수(PATH)의 정밀 점검
설치를 마쳤는데도 `go` 명령어가 먹히지 않는다면 99%는 PATH 문제입니다. 컴퓨터에게
자주 하는 실수와 해결법
설정 과정에서 마주치는 문제들은 대부분 정해진 패턴이 있어요. 당황하지 말고 아래 리스트를 보고 하나씩 체크해 보세요.
- ❌ ‘go: command not found’ 오류 발생
왜 발생하는가: Go 설치 경로가 시스템의 PATH 환경 변수에 등록되지 않았기 때문이에요.
✅ 해결법: 운영체제 설정에서 Go의 bin 폴더 경로를 PATH에 추가하고, 반드시 터미널을 재시작하세요. - ❌ ‘go.mod file not found’ 에러
왜 발생하는가: Go Modules 환경에서 프로젝트를 생성할 때 초기화 과정을 생략했기 때문이에요.
✅ 해결법: 프로젝트 루트 폴더에서go mod init <모듈이름>명령어를 실행하세요. - ❌ 외부 패키지를 가져올 때 ‘cannot find module’ 발생
왜 발생하는가: 패키지 경로가 잘못되었거나, 다운로드 후 의존성 정리가 안 된 상태예요.
✅ 해결법:go get <패키지경로>를 실행한 후,go mod tidy명령어로 사용하지 않는 패키지를 정리하고 누락된 것을 채워 넣으세요. - ❌ 파일 수정 후에도 IDE에서 에러 표시가 사라지지 않음
왜 발생하는가: 언어 서버(gopls)가 코드 변경 사항을 즉시 반영하지 못했거나 멈춘 상태예요.
✅ 해결법: VS Code에서Go: Restart Language Server명령을 실행하거나 IDE를 재시작하세요. - ❌ 패키지 다운로드 시 ‘connection timeout’ 발생
왜 발생하는가: 네트워크 환경이나 프록시 설정 문제로 Go 서버에 접속할 수 없는 상태예요.
✅ 해결법:go env -w GOPROXY=https://proxy.golang.org,direct명령어를 통해 공식 프록시를 설정하세요.
자주 묻는 질문
Q. Go와 Golang은 다른 언어인가요?
아니요, 같은 언어예요. Go는 언어의 공식 이름이고, Golang은 Go 언어가 처음 등장했을 때 Google의 프로젝트라는 의미를 담아 도메인 이름 등으로 사용되던 별칭 같은 것이에요. 편하게 섞어 쓰셔도 무방해요.
Q. Windows에서 개발하는 것이 Mac보다 불리한가요?
아니요, 전혀 그렇지 않아요. 최근에는 Windows의 WSL2(Windows Subsystem for Linux)를 사용하면 리눅스와 거의 동일한 환경에서 Go를 개발할 수 있어 매우 강력한 개발 환경을 구축할 수 있어요.
Q. VS Code 대신 GoLand를 쓰는 게 더 좋은가요?
GoLand는 유료이지만 훨씬 더 많은 기능을 자동으로 제공하는 강력한 IDE예요. 하지만 입문자라면 가볍고 무료인 VS Code로 시작해서 언어의 기본을 익히는 것을 더 추천해요.
Q. 프로젝트 폴더를 어디에 만들어야 하나요?
이제는 위치가 중요하지 않아요! 바탕화면이든 문서 폴더든 상관없어요. 다만, 각 폴더마다 반드시 go mod init을 통해 모듈을 초기화해야 한다는 점만 기억하세요.
Q. ‘go get’ 명령어가 예전과 달라진 것 같아요.
맞아요. Go 1.16 버전 이후부터는 패키지를 설치할 때 go get보다는 go mod tidy를 사용하여 의존성을 관리하는 방식이 권장되고 있어요. 최신 문법을 따르는 것이 좋습니다.
성공적인 Go 개발을 위한 마지막 점검
환경 설정이라는 큰 산을 넘으신 것을 축하드려요! 처음에는 복잡해 보였지만, 한 번 제대로 구축해 두면 Go의 간결하고 빠른 성능을 마음껏 누릴 수 있을 거예요. 마지막으로 오늘 배운 내용을 잊지 않도록 요약해 드릴게요.
- 설치 후에는 반드시 터미널을 재시작하여 PATH를 적용하세요.
- 모든 프로젝트는
go mod init으로 시작해야 합니다. - 의존성 관리는
go mod tidy를 습관화하세요. - IDE에서
gopls가 정상 작동하는지 꼭 확인하세요. - 문제 발생 시
go env로 현재 설정값을 먼저 확인하세요.
이제 다음 단계로 나아갈 차례예요. 환경 설정이 끝났다면 바로 코드를 작성해 보세요. 이론만 공부하는 것보다 직접 에러를 마주하고 해결하는 과정에서 실력이 가장 빠르게 늘거든요.
🚀 이번 주에 도전할 일:
- 작은 CLI 도구(예: 간단한 계산기나 할 일 목록 관리 프로그램) 만들기
- Go의 표준 라이브러리 중
fmt와net/http사용법 익히기 - GitHub에 자신의 첫 번째 Go 프로젝트 저장소 만들기
지금 바로 준비된 예제 코드를 클론하여 여러분의 컴퓨터에서 직접 실행해 보세요. 직접 눈으로 확인하는 것만큼 확실한 학습은 없답니다.
함께 읽으면 좋은 글: Go 설치 및 개발환경 구축 완벽 가이드
