SyntaxError: Unexpected token 완벽 해결 가이드

도입

JavaScript 개발 중 가장 흔하게 마주치는 에러 중 하나가 바로 SyntaxError: Unexpected token입니다. 이 에러는 JavaScript 엔진이 코드를 파싱하는 과정에서 예상하지 못한 문자나 기호를 만났을 때 발생합니다. 초보 개발자부터 숙련된 프로그래머까지 누구나 경험하는 이 에러는 문법적 오류로 인해 코드 실행 자체가 불가능해지는 치명적인 문제입니다. 하지만 걱정하지 마세요. 이 가이드를 통해 SyntaxError: Unexpected token 에러의 모든 것을 이해하고 빠르게 해결할 수 있습니다. 에러 메시지를 정확히 분석하고 근본 원인을 파악한다면, 앞으로는 동일한 실수를 반복하지 않을 수 있습니다.

에러 상세 분석

SyntaxError: Unexpected token은 JavaScript의 구문 분석기(Parser)가 코드를 읽는 도중 문법 규칙에 맞지 않는 토큰을 발견했을 때 발생합니다. 여기서 ‘토큰(token)’이란 코드를 구성하는 최소 단위로, 키워드, 변수명, 연산자, 괄호 등을 의미합니다. 이 에러는 실행 시점이 아닌 파싱 단계에서 발생하므로, 코드가 한 줄도 실행되지 않고 즉시 중단됩니다.

에러 메시지는 일반적으로 다음과 같은 형태로 나타납니다:

SyntaxError: Unexpected token '{'.
SyntaxError: Unexpected token '}'
SyntaxError: Unexpected token 'else'
SyntaxError: Unexpected identifier

에러 메시지 뒤에 표시되는 문자가 바로 파서가 예상하지 못한 토큰입니다. 하지만 주의할 점은 에러가 표시된 위치가 실제 문제의 위치와 다를 수 있다는 것입니다. 종종 이전 줄에서 발생한 문법 오류가 다음 줄에서 감지되는 경우가 많습니다. 따라서 에러가 발생한 줄뿐만 아니라 그 이전 코드도 함께 검토해야 합니다.

발생 원인 5가지

1. 괄호 불일치

가장 흔한 원인은 중괄호 {}, 대괄호 [], 소괄호 ()의 짝이 맞지 않는 경우입니다. 함수나 객체, 배열을 작성할 때 여는 괄호와 닫는 괄호의 개수가 일치하지 않으면 파서가 코드 구조를 제대로 이해하지 못합니다. 특히 중첩된 구조에서 괄호 하나를 빼먹거나 추가하는 실수가 자주 발생합니다.

2. 세미콜론 누락 또는 잘못된 위치

JavaScript는 자동 세미콜론 삽입(ASI) 기능이 있지만, 모든 상황에서 완벽하게 작동하지는 않습니다. 특히 return 문 다음 줄에 값을 작성하거나, 배열/객체 리터럴을 여러 줄로 작성할 때 예상치 못한 동작이 발생할 수 있습니다. 또한 for 루프의 세미콜론 위치가 잘못된 경우에도 이 에러가 발생합니다.

3. 잘못된 JSON 형식

JSON 데이터를 다룰 때 JavaScript 객체 리터럴 문법과 혼동하여 에러가 발생하는 경우가 많습니다. JSON은 키를 반드시 쌍따옴표로 감싸야 하며, 후행 쉼표(trailing comma)를 허용하지 않습니다. 또한 undefined, 함수, 심볼 등의 값을 포함할 수 없습니다.

4. 예약어 오용

JavaScript의 예약어(if, else, return, function 등)를 변수명이나 속성명으로 잘못 사용하거나, 예약어를 잘못된 위치에 배치하면 구문 오류가 발생합니다. 특히 strict mode에서는 더 많은 단어가 예약어로 지정되어 있어 주의가 필요합니다.

5. 문자열 처리 오류

문자열을 감싸는 따옴표가 일치하지 않거나, 여러 줄 문자열을 백틱(`) 대신 일반 따옴표로 작성하거나, 문자열 내부의 특수 문자를 이스케이프하지 않은 경우 에러가 발생합니다. 또한 템플릿 리터럴의 ${} 문법을 잘못 사용하는 경우도 해당됩니다.

해결방법 7가지

1. 괄호 매칭 확인

모든 여는 괄호에 대응하는 닫는 괄호가 있는지 확인합니다. 대부분의 코드 에디터는 괄호 매칭 기능을 제공하므로 이를 활용하세요.

// 잘못된 코드
function getData() {
  const data = {
    name: 'John',
    age: 30
  // 닫는 중괄호 누락
  return data;
}

// 올바른 코드
function getData() {
  const data = {
    name: 'John',
    age: 30
  };
  return data;
}

2. JSON 형식 검증

JSON 데이터는 엄격한 형식을 따라야 합니다. 키는 쌍따옴표로 감싸고, 후행 쉼표를 제거하세요.

// 잘못된 JSON
const config = {
  name: 'MyApp',
  version: 1.0,
  enabled: true,
};

// 올바른 JSON
const config = {
  "name": "MyApp",
  "version": 1.0,
  "enabled": true
};

3. 문자열 따옴표 일치 확인

문자열을 시작한 따옴표와 같은 종류의 따옴표로 끝내야 합니다.

// 잘못된 코드
const message = "Hello World';
const text = 'It's a beautiful day";

// 올바른 코드
const message = "Hello World";
const text = 'It\'s a beautiful day';
const multiline = `This is
a multiline string`;

4. 조건문과 반복문 구조 확인

if-else, for, while 등의 제어문은 올바른 구조를 가져야 합니다.

// 잘못된 코드
if (condition)
  console.log('true')
else  // 앞에 세미콜론이 자동 삽입되어 에러 발생
  console.log('false');

// 올바른 코드
if (condition) {
  console.log('true');
} else {
  console.log('false');
}

5. 화살표 함수 문법 확인

화살표 함수의 매개변수와 본문을 올바르게 작성해야 합니다.

// 잘못된 코드
const add = (a, b) => return a + b;
const multiply = a, b => a * b;

// 올바른 코드
const add = (a, b) => a + b;
const multiply = (a, b) => a * b;
const complex = (x) => {
  const result = x * 2;
  return result;
};

6. 객체 리터럴과 구조분해 확인

객체 리터럴과 구조분해 할당 문법을 정확히 사용하세요.

// 잘못된 코드
const user = { name: 'Alice' age: 25 }; // 쉼표 누락
const { name age } = user; // 쉼표 누락

// 올바른 코드
const user = { name: 'Alice', age: 25 };
const { name, age } = user;

7. async/await 키워드 위치 확인

async와 await 키워드는 올바른 위치에 사용해야 합니다.

// 잘못된 코드
function getData() {
  const result = await fetch('/api/data'); // async 누락
}

// 올바른 코드
async function getData() {
  const result = await fetch('/api/data');
  return result.json();
}

예방법과 베스트 프랙티스

1. 린터(Linter) 사용

ESLint 같은 린터를 프로젝트에 도입하면 코드를 작성하는 즉시 문법 오류를 감지할 수 있습니다. 린터는 잠재적인 에러를 미리 경고하고 코드 스타일을 일관되게 유지하는 데 도움을 줍니다.

2. 코드 포매터 활용

Prettier 같은 자동 포매터를 사용하면 괄호, 세미콜론, 들여쓰기 등을 자동으로 정리해줍니다. 이를 통해 인간의 실수로 인한 구문 오류를 크게 줄일 수 있습니다.

3. 코드 에디터 기능 활용

VS Code, WebStorm 등 현대적인 IDE는 괄호 자동 완성, 구문 강조, 에러 표시 등의 기능을 제공합니다. 이러한 기능을 적극 활용하여 코드 작성 중 실시간으로 문제를 파악하세요.

4. 점진적 코드 작성 및 테스트

많은 양의 코드를 한 번에 작성하지 말고, 작은 단위로 나누어 작성하고 즉시 테스트하세요. 이렇게 하면 에러가 발생했을 때 문제의 범위를 좁혀 빠르게 해결할 수 있습니다.

5. 코드 리뷰 문화

동료 개발자와 코드 리뷰를 진행하면 자신이 놓친 오류를 발견할 수 있습니다. 여러 사람의 눈으로 코드를 검토하면 품질이 향상되고 에러를 사전에 방지할 수 있습니다.

마무리

SyntaxError: Unexpected token 에러는 JavaScript 개발에서 피할 수 없는 동반자입니다. 하지만 이 에러의 원인을 정확히 이해하고, 체계적인 디버깅 방법을 익히며, 예방 도구를 활용한다면 더 이상 두려워할 필요가 없습니다. 이 가이드에서 소개한 해결 방법과 베스트 프랙티스를 실천하면 코드 품질이 향상되고 개발 생산성도 크게 높아질 것입니다. 에러는 배움의 기회입니다. 각 에러를 통해 JavaScript 문법을 더욱 깊이 이해하고, 더 나은 개발자로 성장하시기 바랍니다. 지금 바로 여러분의 코드에 린터를 설치하고, 체계적인 디버깅 습관을 들여보세요!