Go 빌드와 실행, 배포 흐름 정리: 로컬부터 운영까지 한 번에 이해하기

go mod까지 정리했다면, 이제 실제로
코드를 어떻게 빌드하고 실행하며, 운영 환경에 배포하는지를 다룰 차례다.

Go는 빌드와 배포 과정이 단순한 편이다.
하지만 단순하다고 해서 아무 생각 없이 쓰다 보면
환경별 차이, 바이너리 관리, 설정 처리에서 다시 헷갈리기 쉽다.

이 글에서는

• Go 빌드와 실행의 기본 흐름
• 환경별 빌드 방식
• 실무에서 자주 사용하는 배포 패턴

을 중심으로 정리한다.

---

go run vs go build, 언제 무엇을 쓰나

go run: 빠른 실행용

go run main.go

• 소스 코드를 즉시 컴파일 후 실행
• 임시 바이너리를 만들어 실행한다
• 실행 파일이 남지 않는다

로컬 개발이나 간단한 테스트에는 충분하지만,
운영 환경에서는 거의 사용하지 않는다.

---

go build: 실행 파일 생성

go build

• 현재 디렉터리 기준으로 바이너리 생성
• 결과물은 실행 파일 하나

./myapp

Go의 가장 큰 장점 중 하나는
빌드 결과물이 단일 바이너리라는 점이다.
별도의 런타임이나 의존 파일이 필요 없다.

---

빌드 결과물 위치와 이름 제어

go build -o app

• -o: 출력 파일 이름 지정

go build ./cmd/server

• 특정 패키지만 빌드
• 여러 entry point가 있는 프로젝트에서 유용

실무에서는 보통
cmd 디렉터리 아래를 기준으로 빌드하는 구조를 많이 쓴다.

---

크로스 컴파일: 다른 OS용 빌드

Go는 크로스 컴파일을 기본 지원한다.

GOOS=linux GOARCH=amd64 go build

• macOS에서 Linux용 바이너리 생성 가능
• Docker 없이도 서버 바이너리 빌드 가능

자주 사용하는 조합은 다음과 같다.

• linux/amd64
• linux/arm64

이 기능 덕분에
CI 환경이나 개인 노트북에서도 배포용 바이너리를 쉽게 만들 수 있다.

---

환경 변수로 설정 관리하기

Go 애플리케이션은 보통
환경 변수 기반 설정을 많이 사용한다.

port := os.Getenv("PORT")

• 코드 변경 없이 설정 변경 가능
• 컨테이너, 클라우드 환경과 궁합이 좋다

⚠️ 주의할 점

• 기본값 처리 필수
• 필수 값 누락 시 빠르게 실패하도록 구성

if port == "" {
    log.Fatal("PORT is required")
}

---

빌드 플래그(ldflags) 활용

빌드 시점에 값을 주입할 수도 있다.

go build -ldflags "-X main.version=1.0.0"

var version string

• 버전 정보
• 커밋 해시
• 빌드 시각

같은 값을 런타임에 주입할 수 있다.
실무에서는 배포 추적용으로 자주 활용된다.

---

Docker 없이도 배포가 쉬운 이유

Go 바이너리는 다음 특징을 가진다.

• 단일 파일
• 의존성 포함
• 실행 권한만 있으면 동작

그래서 전통적인 서버 환경에서는

1. 바이너리 업로드
2. 실행 권한 부여
3. 서비스 등록

정도로 배포가 끝난다.

물론 컨테이너 환경에서도 Go는 잘 어울리지만,
컨테이너가 필수는 아니다라는 점이 다른 언어와의 차이점이다.

---

실무에서 흔한 배포 흐름 예시

1. 로컬 또는 CI에서 빌드
2. Linux 바이너리 생성
3. 서버로 파일 전달 (scp, artifact)
4. 실행 또는 서비스 재시작

이 과정에서 중요한 건

• 빌드 환경과 실행 환경 분리
• 설정은 환경 변수로 처리
• 실행 파일은 불변(immutable)하게 관리

---

빌드 & 배포 시 자주 겪는 문제

• 로컬에서는 되는데 서버에서 안 됨
  → GOOS/GOARCH 확인
• 실행은 되는데 설정이 없음
  → 환경 변수 누락
• 바이너리 크기가 큼
  → 디버그 옵션 확인, 불필요한 의존성 제거

대부분의 문제는
빌드 단계에서 한 번 더 정리하면 해결되는 경우가 많다.

---

정리

Go의 빌드와 배포는
“단일 바이너리 + 환경 변수”라는 단순한 철학 위에 있다.

• go run: 개발용
• go build: 운영용
• 크로스 컴파일 기본 지원
• 배포 흐름이 예측 가능하다

이 흐름을 한 번 익혀두면,
새 프로젝트에서도 거의 같은 방식으로 가져갈 수 있다.

다음 글에서는 배포 이후 단계로
로깅과 설정 관리, 그리고 운영 관점에서의 Go 코드 작성 기준을 다루면 좋다.