내 로컬에서는 작동합니다: 정의, 발생 원인 및 예방 방법

“내 로컬에서는 작동합니다”란 무섻인가

“내 로컬에서는 작동합니다” — 동료 또는 테스터가 버그를 제보했을 때 개발자가 하는 말이지만, 개발자의 머신에서는 재현되지 않는다. 외부적으로는 문제 부인과 같지만, 기술적으로는 실제 상황이다: 코드가 한 환경에서는 잘 작동하다가 다른 환경에서는 실패할 수 있다. 구성의 하나의 비트가 달라지면 애플리케이션의 동작이 근본적으로 변한다.

이 말은 IT 커뮤니티에서 밀이 되었다. 그 이유는 것이 동시에 참이면서도 숌덨레스 없기 때문이다. 개발자의 관점에서는 코드가 실제로 그의 머신에서 작동한다. 팀의 관점에서는 문제가 존재하며 해결해야 하지, 정당화해서는 안된다. 상황의 유머는 개발자가 진실을 말하지만, 그 진실이 버그 수정에 도움이 된다는 점이다. 이 밀은 매우 인기가 있어서 Reddit, XKCD 그리고 DevOps 컨퍼런스에서 수젌의 게시물이 이 주제에 할당되어 있다.

프로세스 관점에서, “내 로컬에서는 작동합니다”라는 말은 환경 재현성 문제의 지표이다. 두 개발자가 같은 코드에서 같은 결과를 받지 못한다면 환경 설정 과정이 표준화되지 않았다는 것이다. DevOps 실무는 환경이 수동 작업 없이 리포지토리에서 한 명령으로 재현될 수 있어야 한다고 말한다.

로컬 환경이 프로덕션과 다른 이유

개발자의 로컬 환경은 거의 항상 프로덕션과 다르다. 개발자는 macOS 또는 Windows를 사용하는 반면, 서버는 Linux에서 실행된다. 다른 운영체제는 다른 파일 시스템, 인코딩, 스레드 타이밍 및 시스템 콜을 가진다. 두 환경다 Linux라도 커널, glibc, OpenSSL 버전이 다른 수 있다.

둘째 이유는 설치된 소프트웨어 집합이다. 개발자의 머신에는 Node.js 20의 전역 버전이 설치되어 있지만, CI/CD 구성에서는 버전 18이 명시되어 있을 수 있다. 또는 개발자가 로컬에서 PostgreSQL 16을 사용하는 반면, 프로덕션에서는 PostgreSQL 14를 사용할 수 있다. 마이너 버전의 차이는 보통 느껴지지 않지만, 메이저 업데이트는 SQL 쿼리의 동작을 변경할 수 있다. npm Inc.에 따르면, 의존성 관련 버그의 67%가 패치 버전 차이에서 발생한다.

센째 이유는 네트워크 조건이다. 로컬 머신에는 지연, 대역폭 제한 또는 DNS 문제가 없다. 프로덕션에서는 외부 API에 대한 요청이 5ms 대신 500ms 걸릴 수 있다. 타임아웃, 재시도 로직, 경쟁 상태 — 이러한 문제는 실제 부하와 실제 네트워크 조건에서만 나타난다. Toxiproxy 같은 도구를 통한 네트워크 에미렐이션은 배포 전에 이러한 문제를 식별하는 데 도움이 된다.

로컬에서 버그가 재현되지 않는 일반적인 원인

처음 원인은 데이터 부족이다. 개발자는 테스트 픽스처로 작업하지만, 프로덕션에는 예비치 않은 값을 가진 수백만 개의 레코드가 있다. 개발자가 필수라고 생각했던 필드의 NULL, 이름의 Unicode 문자, 너무 긴 문자열 — 이러한 것들이 합성 데이터를 가진 로컬 DB에서 재현할 수 없는 버그를 유발할 수 있다.

둘째 원인은 컴파일 및 빌드 플래그 차이이다. 리리스 빌드(Release/Distribution)는 디버그 빌드(Debug)와 다른 수 있다. 컴파일러 최적화, 디버그 로그 제거, 함수 인라인 — 이러한 것들이 버그를 숨기거나 반대로 나타낼 수 있다. 일반적인 예: 디버그 빌드에서 assert가 작동하지만 리리스에서는 변수 초기화 순서가 달라서 실패한다.

셋째 원인은 로컬 캐시 및 임시 파일이다. 브라우저에 구 스크립트가 캐시되어 있거나, Redis에 구 데이터가 저장되어 있거나, 파일 시스템에 이전 실행의 임시 파일이 남아 있어서 개발자가 버그를 모른 수 있다. 깎꺿한 실행(시크릿 모드, 캐시 지우기, fresh install)은 “자동으로” 나타나지 않았던 버그를 재현하는 경우가 많다.

넣째 원인은 전역 및 로컬 의존성 간의 충돌이다. Ruby gems, Python pip, Node.js npm 같은 도구는 전역으로 설치된 패키지를 가짨서 코드가 로컬에서 작동하도록 도와주지만 프로덕션에서는 없을 수 있다. 가상 환경(virtualenv, venv, nvm)을 사용하면 프로젝트를 전역 설치로부터 분리하여 환경을 재현 가능하게 만든다.

팀 워크와 신뢰에 미치는 영향

“내 로컬에서는 작동합니다”라는 말은 팀 내의 신뢰를 무너뜨린다. 개발자가 정기적으로 버그를 재현할 수 없으면, 동료들은 그의 능력이나 테스트 검증에 의문을 품기 시작한다. 시간이 지나면 이것이 마이크로 매니지먼트로 이어진다: 모든 변경 사항에 두 번째 개발자의 확인이 필요하여 개발이 느려진다. Google Project Aristotle에 따르면, 팀의 심리적 안전감은 생산성에 직접 영향을 미치며, 환경에 대한 지속적인 논쟁은 그것을 감소시키는 요소 중 하나이다.

둘째 문제는 code review 지연이다. 개발자가 로컬에서 버그를 재현할 수 없으면, 동료의 pull request를 “나에게는 작동합니다 — 그러니 귀하의 문제입니다”라고 거부할 수 있다. 이것은 갑8등을 부추기고 기능 많을 지연시킨다. 환경 표준화는 이러한 갑8등을 해소한다: 두 개발자가 동일한 Docker 컨테이너에서 작업하면, “누게 문제가 있는가”라는 질문은 의미가 없어진다.

셋째 문제는 트래커에서 버그 분실이다. “개발자에게 재현되지 않는” 버그는 종족 “Cannot Reproduce” 로 닫히고 말다. 한 달 후 버그가 프로덕션에서 발생하고, 그 수정에 10배의 비용이 든다. 규칙: 버그가 적어도 한 명에게 재현된다면 그것은 존재하며, 개발자에게 작동하는지와 무관하다.

개발자 환경을 표준화하는 방법

처음이면서 가장 효과적인 방법은 Docker이다. 전체 프로젝트가 추가 작업 없이 docker-compose up으로 실행되어야 한다. 데이터베이스, 캐시, 메시지 큐, 웹 서버 — 모든 것이 컨테이너에서 실행된다. 개발자는 Docker와 Git만 설치한다. 나머지는 컨테이너 안에 있다. 이를 통해 OS에 관계없이 모든 팀 구원이 동일한 환경을 가지게 된다.

둘째 방법은 버전 관리자이다. Docker가 불가능한 경우(라이선스 제한, 레거시 인프라) nvm(Node.js), rbenv(Ruby), pyenv(Python), sdkman(Java)를 사용하십시오. 버전 관리자는 프로젝트 내에서 언어와 도구의 버전을 전환할 수 있게 해줍니다. .nvmrc, .ruby-version, .python-version 파일은 리포지토리에 있어야 하고 CI/CD가 확인해야 합니다.

셋째 방법은 가상 머신을 위한 Vagrant입니다. Vagrant는 VirtualBox 또는 VMware 상에서 지정된 OS와 구성으로 가상 머신을 실행합니다. VM 내부에서는 provisioning 스크립트(shell, Ansible, Puppet)를 통해 모든 의존성이 설치됩니다. Vagrant는 Docker보다 무거우지만, OS 레벨의 완전한 격리를 제공합니다 — 특정 Linux 커널 버전에 의존하는 프로젝트에 유용합니다.

넣째는 makefile과 bootstrap 스크립트입니다. install, test, build, clean 목적을 가진 간단한 Makefile도 루틴 작업을 표준화할 수 있습니다. make install 명령은 모든 의존성을 설치하고, DB를 구성하고, 테스트 데이터를 만들어야 합니다. 모든 개발자를 위한 단일 입구 점은 환경 설정에서 수동 실수를 제거합니다.

환경 간격을 방지하는 도구

주요 도구는 의존성의 lock 파일입니다. package-lock.json (npm), yarn.lock (Yarn), Podfile.lock (CocoaPods), pubspec.lock (Flutter)는 각 패키지의 정확한 버전을 고정합니다. lock 파일이 없으면, 다른 시간에 의존성을 설치한 두 개발자가 다른 마이너 버전을 받을 수 있습니다. Lock 파일은 리포지토리에 있어야 하고 수동으로 편집하면 안됩니다.

둘째 도구는 리포지토리의 .env.example입니다. 주석이 있는 환경 변수의 템플릿 파일입니다. 개발자는 이것을 .env에 복사하여 값을 입력합니다. CI/CD 파이프라인은 모든 필수 변수가 설정되어 있는지 확인합니다. GitLab 2023에 따르면, .env.example을 사용하는 팀은 환경 변수 관련 사고를 40% 감소시킵니다.

셋째 도구는 pre-commit 후크입니다. 각 커및 전에 실행되는 자동 확인: 린터, 포맷터, 타입 확인, 테스트. 모든 개발자가 동일하게 후크를 구성한 경우, “로컬 머신에서는 통과된” 포맷 또는 타입 오류가 프로덕션까지 도달하지 않습니다. JavaScript용 Husky와 Python용 pre-commit이 인기있는 해결책입니다.

넣째는 CI/CD 파이프라인으로 깎꺿한 환경에서 테스트를 실행합니다. 테스트가 CI에서는 통과하지만 로컬에서는 실패하면 문제는 로컬 환경 설정에 있습니다. 테스트가 CI에서 실패하면 pull request가 머지되지 않습니다. 이 엄격한 규칙은 “로컬에서 작동하는” 버그가 메인 브랜치에 들어가는 것을 막습니다.