Blog

🚨 도입부

개발자 여러분, 코드를 작성하다가 “ReferenceError: variable is not defined“라는 에러 메시지를 마주쳤을 때의 그 좌절감, 정말 짜증나죠? 이 에러는 JavaScript를 다루다 보면 피할 수 없는 골칫거리 중 하나입니다. 특히 변수의 선언과 초기화가 제대로 이루어지지 않았을 때 주로 발생합니다. 이 글에서는 이 에러가 발생하는 다양한 시나리오를 살펴보고, 이를 해결할 수 있는 방법을 단계별로 소개합니다. 여러분이 이 글을 통해 얻을 수 있는 것은 단순한 에러 해결이 아닌, 같은 에러를 다시는 만나지 않도록 하는 예방책까지 포함됩니다.

예를 들어, 함수 내에서 변수를 사용하려고 하지만 해당 변수가 함수 외부에서 선언되지 않은 경우, 또는 전역 범위에 변수를 선언한 줄 알았는데 사실 그렇지 않았던 경우 등 다양한 상황에서 이 에러가 발생할 수 있습니다. 이 글을 통해 여러분은 각 상황에 맞는 해결책을 찾을 수 있을 것입니다. 예상 해결 시간은 약 10분에서 30분 정도이며, 난이도는 초급에서 중급 수준입니다.

🔍 에러 메시지 상세 분석

에러 메시지 “ReferenceError: variable is not defined“는 JavaScript에서 변수를 참조할 때 해당 변수가 정의되지 않았을 때 발생합니다. 이 에러의 변형으로는 “ReferenceError: foo is not defined“와 같이 특정 변수명이 포함된 형태가 있습니다. 이 에러는 다양한 상황에서 발생할 수 있습니다. 예를 들어, 변수 선언 없이 사용하려 할 때, 변수의 스코프를 잘못 이해했을 때, 혹은 외부 라이브러리를 제대로 로드하지 않았을 때 등입니다.

에러 메시지의 각 부분을 이해하는 것이 중요합니다. “ReferenceError“는 JavaScript에서 참조 오류를 나타내며, 이는 프로그램이 변수나 함수의 참조를 잘못하고 있다는 의미입니다. “is not defined“는 해당 변수가 선언되지 않았거나, 접근 가능한 범위(scope) 내에 존재하지 않음을 의미합니다. 초보자라면 에러 메시지를 읽고, 어느 부분에서 문제인지 파악하는 것이 중요한 첫 단계입니다.

이 에러와 혼동하기 쉬운 비슷한 에러로는 “TypeError“가 있습니다. TypeError는 주로 변수나 함수가 undefined 또는 null일 때 발생합니다. 이러한 에러는 비슷해 보이지만, 문제의 원인과 해결 방법이 다르므로 주의가 필요합니다.

🧐 발생 원인 분석

주요 원인 중 하나는 변수를 선언하지 않고 사용하려고 할 때입니다. 예시로는 다음과 같습니다:

console.log(myVariable); // ReferenceError 발생

이 경우, myVariable이 선언되지 않았기 때문에 ReferenceError가 발생합니다. 두 번째 원인은 변수의 스코프를 잘못 이해했을 때입니다. 예를 들어, 함수 내에서 전역 변수를 참조하려 하는데, 사실 해당 변수가 지역 변수로 선언된 경우입니다.

function testFunction() {
  console.log(localVar); // ReferenceError 발생
}
var localVar = 'Hello';

이 코드에서는 localVar가 함수 호출 시점에 선언되지 않았기 때문에 오류가 발생합니다.

세 번째 원인은 비동기 코드에서 변수를 참조할 때입니다. 예를 들어, 비동기 함수 내에서 외부 변수를 사용할 때, 해당 변수가 비동기 호출 전에 선언되지 않으면 오류가 발생할 수 있습니다.

async function fetchData() {
  console.log(data); // ReferenceError 발생
}
fetchData();
var data = 'Sample Data';

네 번째 원인은 외부 라이브러리가 제대로 로드되지 않았을 때입니다. 예를 들어, jQuery를 사용하려고 하는데, jQuery 라이브러리가 포함되지 않은 경우입니다.

$(document).ready(function() {
  console.log('Document ready!');
});

이 경우, jQuery 라이브러리가 로드되지 않았다면, $가 정의되지 않아 ReferenceError가 발생합니다.

다섯 번째 원인은 조건문 내에서 변수를 초기화할 때입니다. 조건문이 실행되지 않으면 변수도 초기화되지 않으므로, 이후에 변수를 참조하면 ReferenceError가 발생할 수 있습니다.

if (false) {
  var conditionalVar = 'I am defined';
}
console.log(conditionalVar); // undefined

이러한 경우, conditionalVar는 정의되지 않기 때문에 문제가 발생합니다.

✅ 해결 방법

즉시 해결: 1분 내 적용 가능한 빠른 방법

1. 변수가 사용되기 전에 선언하기: 변수 선언이 코드의 시작 부분에 위치하도록 합니다.

var myVariable = 'Hello';
console.log(myVariable); // 'Hello'

2. 함수 내에서 전역 변수를 사용하려면 window 객체를 통해 접근하기.

function testFunction() {
  console.log(window.globalVar);
}
var globalVar = 'I am global';
testFunction(); // 'I am global'

3. 비동기 함수 내에서 변수를 사용하기 전에 초기화하기.

var data = 'Sample Data';
async function fetchData() {
  console.log(data); // 'Sample Data'
}
fetchData();

표준 해결: 일반적이고 안전한 해결법

1. 변수의 스코프를 명확히 하기 위해 let이나 const를 사용하세요.

let message = 'Hello, World!';
function showMessage() {
  console.log(message); // 'Hello, World!'
}
showMessage();

2. 비동기 코드를 사용할 때는 async/await를 제대로 사용하여 비동기 흐름을 관리하세요.

async function fetchData() {
  let data = await fetch('https://api.example.com/data');
  console.log(data);
}
fetchData();

3. 외부 라이브러리 사용 시 CDN을 통해 라이브러리를 로드했는지 확인하세요.

// HTML 파일에 추가

4. 조건문 내에서 변수를 안전하게 선언하려면 let을 사용하세요.

let conditionalVar;
if (true) {
  conditionalVar = 'I am defined';
}
console.log(conditionalVar); // 'I am defined'

5. undefined 변수를 참조하기 전에 typeof를 사용하여 안전성을 확보하세요.

if (typeof someVar !== 'undefined') {
  console.log(someVar);
}

고급 해결: 복잡한 상황을 위한 해결법

1. 모듈 시스템을 사용하여 변수를 안전하게 관리하세요.

// mod.js
export const myVar = 'Hello from module';

// main.js
import { myVar } from './mod.js';
console.log(myVar); // 'Hello from module'

2. 변수의 사용 범위를 ES6의 블록 스코프를 활용하여 명확히 하세요.

{
  let blockVar = 'I am block scoped';
  console.log(blockVar); // 'I am block scoped'
}
// console.log(blockVar); // ReferenceError 발생

3. 대규모 프로젝트에서는 TypeScript를 사용하여 타입과 변수를 엄격하게 관리하세요.

// TypeScript Code
let typedVar: string = 'Typed variable';
console.log(typedVar);

🛡️ 예방법 및 베스트 프랙티스

이 에러를 예방하기 위한 가장 확실한 방법은 변수를 사용하기 전에 항상 선언하는 습관을 들이는 것입니다. 또한, let과 const를 사용하여 변수를 선언하면 스코프 문제를 상당 부분 해결할 수 있습니다. 팀 개발 시에는 변수 선언 규칙을 문서화하고, 코드 리뷰 시 이를 철저히 검토하는 것이 좋습니다.

린터 도구인 ESLint를 사용하여 코드 작성 시 발생할 수 있는 문제를 사전에 파악하고, 자동으로 수정할 수 있도록 설정하세요. 프로젝트 시작 시 eslint 설정 파일을 공유하여 팀원이 동일한 규칙을 따르도록 하는 것도 좋은 방법입니다.

또한, 외부 라이브러리를 사용할 때는 항상 최신 버전을 사용하고, 라이브러리가 제대로 로드되었는지 확인하는 절차를 추가하세요. 이는 특히 CDN을 통해 라이브러리를 로드하는 경우에 중요합니다.

🎯 마무리 및 추가 팁

이 글에서 다룬 것처럼, “ReferenceError: variable is not defined” 에러는 변수 선언의 실수에서 비롯되는 경우가 대부분입니다. 변수 선언, 스코프 이해, 비동기 처리 등 기본적인 사항을 철저히 이해하고 실천한다면 이러한 에러는 쉽게 피할 수 있습니다.

비슷한 에러로는 “TypeError“가 있으며, 이는 undefined나 null 상태에서 메서드를 호출할 때 발생합니다. 이러한 에러에 대한 추가 학습 리소스로는 MDN 웹 문서와 같은 공식 문서를 추천합니다.

여러분의 개발 여정에 이 글이 도움이 되기를 바라며, 항상 코드의 안전성과 효율성을 유지하는 습관을 기르시길 응원합니다!