Go 모듈의 go 버전 지시어, 알고 보면 꽤 짜증나는 문제

대체 무슨 일이길래

Go 언어로 프로젝트를 하다 보면 go.mod 파일에 go 1.21 같은 버전이 적혀 있는 걸 보셨을 거예요. 이게 단순히 "이 프로젝트는 Go 1.21로 만들었어요"라는 메모 정도로 생각하기 쉬운데, 사실은 그보다 훨씬 강력한 역할을 하거든요. Go 1.21부터 이 버전 지시어가 실제로 빌드에 사용하는 Go 툴체인 버전을 결정하는 역할을 하게 됐어요. 문제는 이게 개발자의 의도와 다르게 동작하는 경우가 꽤 많다는 점이에요.

go.mod의 go 버전이 하는 진짜 역할

예전에는 go.mod에 적힌 go 버전이 "이 모듈은 최소 이 버전의 Go가 필요해요"라는 의미였어요. 근데 Go 1.21부터 의미가 달라졌는데요, 이제는 이 버전이 "이 버전의 Go 툴체인으로 빌드해라"라는 명령에 가까워졌어요.

이게 뭐냐면, 여러분이 시스템에 Go 1.23을 설치해놨더라도 의존하는 라이브러리의 go.mod에 go 1.24라고 적혀 있으면, Go가 알아서 1.24 툴체인을 다운로드해서 빌드하려고 해요. 마치 Node.js에서 .nvmrc 파일이 자동으로 노드 버전을 바꿔버리는 것과 비슷한데, Go는 이걸 더 강하게 강제하는 거죠.

어떤 상황에서 문제가 되나

실무에서 가장 짜증나는 시나리오를 생각해볼게요. 여러분이 Go 1.23으로 안정적으로 운영 중인 서비스가 있어요. 그런데 어느 날 의존성 중 하나가 go.mod에 go 1.24를 지정해버리면, 여러분의 빌드 파이프라인이 갑자기 Go 1.24를 요구하기 시작해요. 직접 업그레이드를 결정한 게 아닌데 말이에요.

특히 라이브러리 메인테이너 입장에서는 더 골치 아파요. 라이브러리의 go.mod에 최신 버전을 적어두면, 그 라이브러리를 쓰는 모든 프로젝트에 영향이 가거든요. 실제로 Go 1.24가 나왔을 때 많은 라이브러리들이 바로 go 1.24로 올려버렸는데, 이 때문에 아직 1.23에 머물러 있던 프로젝트들이 예상치 못한 빌드 문제를 겪었어요.

toolchain 지시어를 써서 어느 정도 제어할 수 있긴 한데요, 이것도 완벽하지는 않아요. GOTOOLCHAIN=local이라는 환경 변수를 설정하면 "내 로컬에 설치된 Go만 써"라고 강제할 수 있지만, 이걸 팀 전체에 적용하고 CI/CD에도 반영하려면 또 하나의 관리 포인트가 생기는 셈이에요.

다른 언어는 어떻게 하나

Rust의 rust-toolchain.toml도 비슷한 역할을 하는데, Rust는 rustup이라는 도구와 자연스럽게 통합되어 있어서 버전 전환이 훨씬 매끄러워요. 그리고 중요한 차이가 있는데, Rust에서는 의존 라이브러리가 내 프로젝트의 툴체인 버전을 강제하지 않아요. 라이브러리의 MSRV(Minimum Supported Rust Version)는 참고 사항이지 강제 사항이 아니거든요.

Node.js 생태계에서는 engines 필드가 있지만, 기본적으로는 경고만 띄우고 강제하지 않아요. engine-strict 옵션을 켜야 비로소 강제되는데, 이것도 직접적인 의존성에만 적용되지 간접 의존성까지 올라타지는 않죠.

그런 면에서 Go의 접근법은 꽤 공격적이에요. 의존성 하나가 전체 프로젝트의 빌드 툴체인을 바꿔버릴 수 있다는 건, 언어 차원에서 "항상 최신 버전을 써라"라고 압박하는 것과 비슷하거든요.

실무에서 어떻게 대응하면 좋을까

한국에서도 Go로 백엔드 서비스를 운영하는 팀이 많은데요, 특히 쿠버네티스 관련 도구나 마이크로서비스를 Go로 작성하는 경우가 흔하잖아요. 이런 팀에서 알아두면 좋은 팁이 몇 가지 있어요.

첫째, CI/CD 환경에서는 GOTOOLCHAIN=local 환경 변수를 설정해두는 게 안전해요. 빌드 서버에 설치된 Go 버전만 사용하도록 고정하면, 의존성 업데이트 때문에 예상 못한 툴체인 변경이 일어나는 걸 막을 수 있어요.

둘째, 라이브러리를 만들어서 공개하는 분들은 go.mod의 버전을 올릴 때 신중해야 해요. 최신 Go 기능이 꼭 필요한 게 아니라면, 가능한 한 낮은 버전을 유지하는 게 사용자들에게 친절한 거예요.

셋째, go.mod에 toolchain 줄이 자동으로 추가되는 경우가 있는데, 이걸 그냥 두면 팀원 간에 Go 버전이 달라지는 혼란이 생길 수 있으니 팀 내에서 정책을 정해두는 게 좋아요.

정리하자면

Go의 go.mod 버전 지시어는 Go 1.21부터 단순한 메타데이터가 아니라 실제 빌드 동작을 제어하는 강력한 설정이 됐어요. 의존성이 내 프로젝트의 Go 버전까지 좌우할 수 있다는 건 편리함과 통제력 상실 사이의 트레이드오프인데요, 여러분은 프로젝트에서 Go 버전 관리를 어떻게 하고 계신가요? GOTOOLCHAIN=local을 쓰고 계신 분이 있다면 경험을 공유해주세요.