ReferenceError: variable is not defined 완벽 해결법 – 원인부터 예방까지

도입 – JavaScript 개발자라면 반드시 알아야 할 에러

JavaScript 개발 중 “ReferenceError: variable is not defined” 에러를 마주친 적이 있나요? 이 에러는 JavaScript 개발자들이 가장 자주 접하는 에러 중 하나로, 코드 실행 중 정의되지 않은 변수를 참조하려 할 때 발생합니다. 초보 개발자부터 경험 많은 개발자까지 누구나 한 번쯤 경험하는 이 에러는 단순해 보이지만, 그 원인은 매우 다양합니다. 변수 선언을 빼먹었거나, 스코프 문제, 타이핑 실수, 비동기 처리 문제 등 여러 상황에서 발생할 수 있습니다. 이 글에서는 ReferenceError의 모든 것을 다루며, 빠르고 정확하게 해결하는 방법을 제시합니다. 실무에서 바로 적용 가능한 해결책과 예방법까지 상세히 알아보겠습니다.

에러 상세 분석 – ReferenceError의 정체

ReferenceError는 JavaScript 엔진이 현재 스코프 체인에서 변수를 찾을 수 없을 때 발생하는 런타임 에러입니다. 브라우저 콘솔이나 Node.js 환경에서 “Uncaught ReferenceError: variable is not defined”라는 메시지로 표시됩니다. 이 에러는 코드 실행을 즉시 중단시키므로 신속한 해결이 필요합니다.

JavaScript는 변수를 참조할 때 현재 스코프에서 시작해 전역 스코프까지 변수를 검색합니다. 이 과정을 스코프 체인 탐색이라고 하며, 모든 스코프에서 변수를 찾지 못하면 ReferenceError가 발생합니다. 이는 컴파일 타임이 아닌 런타임에 발생하므로, 코드를 실행하기 전까지는 발견하기 어렵습니다.

특히 “variable is not defined”와 “variable is undefined”는 다릅니다. 전자는 변수 자체가 선언되지 않았음을 의미하고, 후자는 변수는 선언되었지만 값이 할당되지 않은 상태를 뜻합니다. 이 차이를 이해하는 것이 디버깅의 첫 걸음입니다.

발생 원인 5가지 – 왜 이 에러가 나타나는가

1. 변수 선언 누락

가장 흔한 원인은 변수를 선언하지 않고 사용하는 경우입니다. JavaScript에서는 var, let, const 키워드로 변수를 선언해야 하는데, 이를 빼먹으면 에러가 발생합니다.

// 잘못된 예
console.log(userName); // ReferenceError: userName is not defined

// 올바른 예
let userName = "홍길동";
console.log(userName); // "홍길동"

2. 스코프 문제

변수가 선언된 스코프 밖에서 접근하려 할 때 발생합니다. 블록 스코프를 가진 let과 const는 선언된 블록 내에서만 접근 가능합니다.

// 잘못된 예
if (true) {
  let message = "안녕하세요";
}
console.log(message); // ReferenceError: message is not defined

// 올바른 예
let message;
if (true) {
  message = "안녕하세요";
}
console.log(message); // "안녕하세요"

3. 변수명 오타

변수명을 잘못 입력한 경우 JavaScript는 새로운 변수로 인식하여 에러를 발생시킵니다. 대소문자도 구분하므로 주의해야 합니다.

let userEmail = "[email protected]";
console.log(useremail); // ReferenceError: useremail is not defined

4. 호이스팅 이해 부족

let과 const는 호이스팅되지만 TDZ(Temporal Dead Zone)에 머물러 선언 전에 접근하면 에러가 발생합니다.

console.log(count); // ReferenceError: Cannot access 'count' before initialization
let count = 10;

5. 비동기 실행 순서 문제

비동기 함수에서 변수가 초기화되기 전에 접근하려 할 때 발생합니다.

let data;
setTimeout(() => {
  data = "로드 완료";
}, 100);
console.log(data); // undefined (에러는 아니지만 예상과 다름)

해결방법 7가지 – 실전 코드로 배우기

1. 변수 선언 확인 및 추가

변수를 사용하기 전에 반드시 선언했는지 확인합니다.

// 해결 전
function calculateTotal() {
  result = price * quantity; // ReferenceError
  return result;
}

// 해결 후
function calculateTotal() {
  let price = 1000;
  let quantity = 5;
  let result = price * quantity;
  return result;
}

2. 스코프 범위 조정

변수를 접근 가능한 스코프에 선언합니다.

// 해결 전
function processData() {
  if (true) {
    const tempData = "임시 데이터";
  }
  return tempData; // ReferenceError
}

// 해결 후
function processData() {
  let tempData;
  if (true) {
    tempData = "임시 데이터";
  }
  return tempData;
}

3. typeof를 이용한 안전한 체크

변수 존재 여부를 에러 없이 확인할 수 있습니다.

// 안전한 체크 방법
if (typeof unknownVariable !== 'undefined') {
  console.log(unknownVariable);
} else {
  console.log("변수가 정의되지 않았습니다.");
}

4. try-catch로 에러 핸들링

에러가 발생할 가능성이 있는 코드를 감싸 안전하게 처리합니다.

try {
  console.log(possiblyUndefinedVar);
} catch (error) {
  if (error instanceof ReferenceError) {
    console.error("변수가 정의되지 않았습니다:", error.message);
  }
}

5. 옵셔널 체이닝 활용

객체 속성 접근 시 안전하게 체크합니다.

// 해결 전
const user = {};
console.log(user.profile.name); // TypeError

// 해결 후
const user = {};
console.log(user?.profile?.name); // undefined (에러 없음)

6. 기본값 설정

변수 선언 시 기본값을 할당하여 안전성을 높입니다.

let config = window.appConfig || {};
let apiUrl = config.apiUrl || 'https://api.default.com';

7. ESLint 사용

정적 분석 도구를 사용해 미리 에러를 방지합니다.

// .eslintrc.json 설정
{
  "rules": {
    "no-undef": "error",
    "no-use-before-define": "error"
  }
}

예방법과 베스트 프랙티스

strict mode 사용: ‘use strict’를 파일 상단에 추가하면 선언되지 않은 변수 사용을 방지할 수 있습니다. 이는 실수로 전역 변수를 생성하는 것을 막아줍니다.

const 우선 사용: 재할당이 필요 없는 변수는 const로 선언하여 의도치 않은 변경을 방지합니다. 재할당이 필요한 경우만 let을 사용하고, var는 피하는 것이 좋습니다.

명명 규칙 준수: 일관된 변수명 규칙(camelCase, PascalCase 등)을 사용하여 오타를 줄입니다. TypeScript 사용도 고려해볼 만합니다.

코드 리뷰와 테스트: 동료 개발자의 코드 리뷰와 단위 테스트를 통해 미리 에러를 발견할 수 있습니다. Jest나 Mocha 같은 테스트 프레임워크를 활용하세요.

마무리

“ReferenceError: variable is not defined” 에러는 JavaScript 개발에서 피할 수 없는 문제지만, 원인을 정확히 이해하고 체계적으로 접근하면 쉽게 해결할 수 있습니다. 변수 선언 확인, 스코프 이해, 타입 체크, 그리고 ESLint 같은 도구 활용이 핵심입니다. 이 글에서 소개한 7가지 해결 방법과 예방법을 실무에 적용한다면, 더 안정적이고 견고한 JavaScript 코드를 작성할 수 있을 것입니다. 에러를 두려워하지 말고, 이를 통해 더 나은 개발자로 성장하는 기회로 삼으시길 바랍니다.