Blog

도입: ReferenceError: variable is not defined란?

ReferenceError: variable is not defined는 JavaScript 개발 과정에서 가장 흔하게 마주치는 에러 중 하나입니다. 이 에러는 코드에서 선언되지 않은 변수를 참조하려고 할 때 발생하며, 초보 개발자부터 숙련된 프로그래머까지 모두가 경험하는 문제입니다. 특히 대규모 프로젝트나 여러 파일로 구성된 애플리케이션에서는 변수의 스코프와 선언 위치를 파악하기 어려워 더욱 빈번하게 발생합니다. 이 에러 메시지를 처음 접하면 당황스러울 수 있지만, 원인을 정확히 이해하고 적절한 해결 방법을 알고 있다면 빠르게 문제를 해결할 수 있습니다. 본 가이드에서는 ReferenceError: variable is not defined 에러의 발생 원인을 심층 분석하고, 실제 코드 예제와 함께 7가지 해결 방법을 제시합니다. 또한 이러한 에러를 미리 예방할 수 있는 베스트 프랙티스까지 다루어 여러분의 개발 생산성을 높이는 데 도움을 드리겠습니다.

에러 상세 분석

ReferenceError는 JavaScript의 내장 에러 타입 중 하나로, 존재하지 않는 변수를 참조할 때 JavaScript 엔진이 발생시키는 런타임 에러입니다. 이 에러는 코드가 실행되는 시점에 발생하므로, 문법적으로는 올바르지만 실행 컨텍스트에서 해당 변수를 찾을 수 없을 때 나타납니다.

에러 메시지의 구조를 살펴보면, “ReferenceError: [변수명] is not defined” 형태로 출력됩니다. 여기서 [변수명] 부분에는 실제로 찾을 수 없는 변수의 이름이 표시되어, 어떤 변수가 문제인지 즉시 파악할 수 있습니다. 예를 들어 “ReferenceError: userName is not defined”라는 메시지가 나타났다면, userName이라는 변수가 현재 스코프에서 정의되지 않았음을 의미합니다.

이 에러는 TypeError나 SyntaxError와는 다릅니다. TypeError는 변수는 존재하지만 해당 타입에서 지원하지 않는 연산을 수행할 때 발생하고, SyntaxError는 코드 자체가 문법적으로 잘못되었을 때 발생합니다. 반면 ReferenceError는 변수 자체가 존재하지 않을 때 발생하는 것이 핵심 차이점입니다.

발생 원인 5가지

1. 변수 선언 누락

가장 기본적인 원인으로, 변수를 사용하기 전에 var, let, const 키워드로 선언하지 않은 경우입니다.

// 에러 발생
console.log(message); // ReferenceError: message is not defined

// 올바른 방법
let message = "Hello";
console.log(message);

2. 오타 및 대소문자 실수

JavaScript는 대소문자를 구분하므로, 변수명의 철자가 조금이라도 다르면 다른 변수로 인식합니다.

let userName = "John";
console.log(username); // ReferenceError: username is not defined
// userName과 username은 다른 변수입니다.

3. 스코프 문제

변수가 선언된 스코프 밖에서 접근하려고 할 때 발생합니다. 블록 스코프(let, const)나 함수 스코프(var)를 이해하지 못하면 자주 겪는 문제입니다.

function greet() {
  let greeting = "Hello";
}
greet();
console.log(greeting); // ReferenceError: greeting is not defined

4. 호이스팅 미이해

let과 const로 선언된 변수는 호이스팅되지만 TDZ(Temporal Dead Zone)에 의해 선언 전에는 접근할 수 없습니다.

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

5. 모듈/파일 간 import 누락

다른 파일에서 정의된 변수나 함수를 import하지 않고 사용하는 경우입니다.

// utils.js에 정의된 함수를 import 없이 사용
formatDate(new Date()); // ReferenceError: formatDate is not defined

해결방법 7가지

1. 변수 선언 확인 및 추가

사용하려는 변수가 올바르게 선언되었는지 확인하고, 누락된 경우 선언을 추가합니다.

// 해결: 변수 선언 추가
let result;
result = calculateSum(10, 20);
console.log(result);

2. 변수명 철자 및 대소문자 확인

IDE의 자동완성 기능을 활용하여 정확한 변수명을 사용합니다.

let totalAmount = 1000;
// console.log(totalamount); // 에러
console.log(totalAmount); // 정상 작동

3. 스코프 범위 조정

변수의 스코프를 적절히 조정하거나, 필요한 스코프에서 변수를 선언합니다.

let greeting; // 외부 스코프에 선언
function greet() {
  greeting = "Hello";
}
greet();
console.log(greeting); // "Hello"

4. 선언 순서 조정

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

// 올바른 순서
const config = { debug: true };
if (config.debug) {
  console.log("Debug mode enabled");
}

5. typeof 연산자로 안전하게 확인

변수의 존재 여부를 안전하게 확인할 때 typeof를 사용합니다.

if (typeof optionalVar !== 'undefined') {
  console.log(optionalVar);
} else {
  console.log("변수가 정의되지 않았습니다.");
}

6. 전역 객체 확인 (브라우저/Node.js)

전역 변수를 확인할 때 window(브라우저) 또는 global(Node.js) 객체를 활용합니다.

// 브라우저 환경
if (window.jQuery) {
  // jQuery 사용 가능
}

// Node.js 환경
if (typeof global.myModule !== 'undefined') {
  // myModule 사용 가능
}

7. 모듈 import 추가

필요한 모듈이나 함수를 올바르게 import합니다.

// ES6 모듈
import { formatDate } from './utils.js';
formatDate(new Date()); // 정상 작동

// CommonJS
const { formatDate } = require('./utils');
formatDate(new Date()); // 정상 작동

예방법과 베스트 프랙티스

ESLint 활용

ESLint와 같은 린터를 사용하면 ReferenceError: variable is not defined 에러를 코드 작성 단계에서 미리 감지할 수 있습니다. no-undef 규칙을 활성화하면 정의되지 않은 변수 사용을 즉시 경고합니다.

strict 모드 사용

‘use strict’를 파일 상단에 추가하면 선언되지 않은 변수에 값을 할당하는 것을 방지합니다.

'use strict';
myVar = 10; // ReferenceError 발생

TypeScript 도입

TypeScript를 사용하면 컴파일 타임에 변수 참조 오류를 감지할 수 있어, 런타임 에러를 크게 줄일 수 있습니다.

일관된 네이밍 컨벤션

camelCase나 snake_case 등 일관된 네이밍 규칙을 팀 전체에서 사용하면 오타로 인한 에러를 줄일 수 있습니다.

IDE 자동완성 활용

VS Code 등 현대적인 IDE의 자동완성 기능을 적극 활용하여 변수명 오타를 방지합니다.

마무리

ReferenceError: variable is not defined 에러는 JavaScript 개발에서 피할 수 없는 부분이지만, 원인을 정확히 이해하고 적절한 도구와 방법을 활용하면 효과적으로 해결하고 예방할 수 있습니다. 본 가이드에서 다룬 5가지 원인과 7가지 해결 방법을 숙지하고, ESLint나 TypeScript 같은 도구를 활용하여 더욱 안정적인 코드를 작성하시기 바랍니다. 에러를 두려워하지 마시고, 각 에러를 학습의 기회로 삼아 더 나은 개발자로 성장하세요. 이 가이드가 여러분의 디버깅 시간을 줄이고 개발 생산성을 높이는 데 도움이 되었기를 바랍니다.