ReferenceError: variable is not defined 완벽 해결 가이드

도입: ReferenceError는 왜 발생할까?

JavaScript 개발을 하다 보면 ReferenceError: variable is not defined 에러를 자주 마주치게 됩니다. 이 에러는 JavaScript 엔진이 코드를 실행하는 과정에서 선언되지 않은 변수를 참조하려 할 때 발생합니다. 초보 개발자부터 숙련된 개발자까지 누구나 겪을 수 있는 흔한 에러이지만, 정확한 원인을 파악하지 못하면 디버깅에 많은 시간을 소비하게 됩니다. 이 글에서는 ReferenceError: variable is not defined 에러의 모든 것을 상세히 분석하고, 실무에서 바로 적용할 수 있는 해결 방법과 예방 전략을 제시합니다. 코드 예제와 함께 단계별로 설명하므로, 이 글을 읽고 나면 더 이상 이 에러로 고민하지 않게 될 것입니다.

ReferenceError 에러 상세 분석

ReferenceError는 JavaScript의 7가지 기본 에러 타입 중 하나로, 존재하지 않는 변수를 참조할 때 발생합니다. 이 에러는 런타임(runtime) 에러로 분류되며, 코드가 실행되는 시점에 감지됩니다. JavaScript는 변수를 사용하기 전에 반드시 선언해야 하는 언어이며, 선언되지 않은 변수에 접근하려고 하면 엔진이 즉시 ReferenceError를 던집니다.

이 에러 메시지는 “variable is not defined”라는 형태로 나타나며, 여기서 ‘variable’은 실제로 참조하려 했던 변수의 이름으로 대체됩니다. 예를 들어, ‘userName’이라는 변수를 선언하지 않고 사용했다면 “ReferenceError: userName is not defined”라고 표시됩니다. 이 에러는 strict mode(‘use strict’)에서 더욱 엄격하게 적용되며, 암묵적 전역 변수 생성을 방지하여 코드의 안정성을 높여줍니다. 브라우저 콘솔이나 Node.js 환경에서 스택 트레이스(stack trace)와 함께 표시되므로, 에러가 발생한 정확한 위치를 쉽게 파악할 수 있습니다.

ReferenceError 발생 원인 5가지

1. 변수 선언 누락

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

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

// 올바른 예
let myVariable = 'Hello';
console.log(myVariable); // 'Hello'

2. 변수 선언 전 사용 (Temporal Dead Zone)

let과 const로 선언한 변수는 호이스팅되지만, 선언 전에는 접근할 수 없는 Temporal Dead Zone(TDZ)이 존재합니다. 이 구간에서 변수에 접근하면 ReferenceError가 발생합니다.

console.log(userName); // ReferenceError
let userName = 'John';

3. 스코프 문제

변수의 스코프 밖에서 해당 변수에 접근하려 할 때 발생합니다. 블록 스코프, 함수 스코프를 정확히 이해하지 못하면 이런 에러가 자주 발생합니다.

function myFunction() {
  let localVar = 'I am local';
}
myFunction();
console.log(localVar); // ReferenceError: localVar is not defined

4. 오타 및 대소문자 구분 실수

JavaScript는 대소문자를 구분하므로, 변수명의 철자나 대소문자가 다르면 다른 변수로 인식하여 에러가 발생합니다.

let userName = 'Alice';
console.log(username); // ReferenceError: username is not defined
// userName과 username은 다른 변수

5. 외부 스크립트 로딩 순서 문제

여러 JavaScript 파일을 사용할 때, 변수를 정의한 파일이 로드되기 전에 다른 파일에서 해당 변수를 사용하려 하면 에러가 발생합니다.

해결방법 7가지 (코드 포함)

해결법 1: 변수 올바르게 선언하기

변수를 사용하기 전에 반드시 var, let, 또는 const로 선언합니다.

// 문제 코드
function calculateTotal() {
  total = price * quantity; // ReferenceError
  return total;
}

// 해결 코드
function calculateTotal() {
  const price = 100;
  const quantity = 5;
  const total = price * quantity;
  return total;
}

해결법 2: 변수 선언 순서 조정

변수를 사용하기 전에 먼저 선언하도록 코드 순서를 조정합니다.

// 문제 코드
console.log(greeting); // ReferenceError
const greeting = 'Hello World';

// 해결 코드
const greeting = 'Hello World';
console.log(greeting); // 'Hello World'

해결법 3: 스코프 확장 또는 매개변수 활용

필요한 변수를 적절한 스코프에 선언하거나 함수 매개변수로 전달합니다.

// 문제 코드
function outer() {
  let data = 'Important Data';
}
function inner() {
  console.log(data); // ReferenceError
}

// 해결 코드 1: 스코프 확장
let data = 'Important Data';
function outer() {
  console.log(data);
}
function inner() {
  console.log(data); // 정상 작동
}

// 해결 코드 2: 매개변수 활용
function outer() {
  let data = 'Important Data';
  inner(data);
}
function inner(receivedData) {
  console.log(receivedData); // 정상 작동
}

해결법 4: typeof 연산자로 안전하게 확인

변수 존재 여부가 불확실할 때 typeof 연산자를 사용하여 에러를 방지합니다.

// 안전한 변수 확인
if (typeof myVariable !== 'undefined') {
  console.log(myVariable);
} else {
  console.log('Variable is not defined');
}

// 또는 기본값 설정
const value = typeof myVariable !== 'undefined' ? myVariable : 'default value';

해결법 5: try-catch로 에러 처리

ReferenceError를 포착하여 프로그램이 중단되지 않도록 처리합니다.

try {
  console.log(undefinedVariable);
} catch (error) {
  if (error instanceof ReferenceError) {
    console.error('변수가 정의되지 않았습니다:', error.message);
    // 대체 로직 실행
  }
}

해결법 6: 옵셔널 체이닝과 Nullish 병합 연산자

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

// 문제 코드
console.log(user.profile.name); // user가 없으면 ReferenceError

// 해결 코드
const user = {}; // 변수는 선언되어 있어야 함
const name = user?.profile?.name ?? 'Anonymous';
console.log(name); // 'Anonymous'

해결법 7: 엄격 모드 사용

‘use strict’를 사용하여 암묵적 전역 변수 생성을 방지하고 에러를 조기에 발견합니다.

'use strict';

function test() {
  myVar = 10; // ReferenceError: myVar is not defined
  // strict mode 없이는 전역 변수로 생성됨
}

예방법과 베스트 프랙티스

1. 항상 변수 선언하기

모든 변수를 사용하기 전에 const, let, var로 명시적으로 선언합니다. 가능한 const를 우선 사용하고, 재할당이 필요한 경우에만 let을 사용하세요.

2. ESLint 같은 린터 도구 활용

코드 작성 중 실시간으로 선언되지 않은 변수를 감지하여 경고해주는 린터를 사용합니다. ESLint의 ‘no-undef’ 규칙을 활성화하면 효과적입니다.

// .eslintrc.json 설정 예시
{
  "rules": {
    "no-undef": "error"
  }
}

3. TypeScript 도입 고려

TypeScript를 사용하면 컴파일 시점에 변수 관련 에러를 미리 발견할 수 있어 런타임 에러를 크게 줄일 수 있습니다.

4. 모듈 패턴 사용

ES6 모듈(import/export)을 사용하여 스코프를 명확히 관리하고, 전역 네임스페이스 오염을 방지합니다.

5. 코드 리뷰와 테스트

정기적인 코드 리뷰와 단위 테스트를 통해 변수 선언 누락이나 스코프 문제를 사전에 발견합니다.

마무리

ReferenceError: variable is not defined 에러는 JavaScript 개발에서 피할 수 없는 일반적인 문제이지만, 원인을 정확히 이해하고 체계적으로 접근하면 쉽게 해결할 수 있습니다. 이 글에서 소개한 7가지 해결 방법과 베스트 프랙티스를 실무에 적용하면, 디버깅 시간을 대폭 줄이고 더 안정적인 코드를 작성할 수 있습니다. 변수 선언을 습관화하고, 린터와 같은 도구를 활용하며, 엄격 모드를 사용하는 것만으로도 대부분의 ReferenceError를 예방할 수 있습니다. 앞으로는 이 에러 메시지를 마주쳤을 때 당황하지 말고, 이 가이드를 참고하여 빠르게 문제를 해결하시기 바랍니다.