SyntaxError: Unexpected token 완벽 해결 가이드

도입

JavaScript 개발 중 SyntaxError: Unexpected token 에러를 만나셨나요? 이 에러는 JavaScript 개발자라면 누구나 한 번쯤 마주치는 대표적인 문법 오류입니다. 코드를 실행하려는 순간 갑자기 나타나는 이 에러는 JavaScript 엔진이 코드를 파싱하는 과정에서 예상하지 못한 문자나 토큰을 발견했을 때 발생합니다. 초보 개발자는 물론 숙련된 개발자도 실수로 괄호를 빠뜨리거나 쉼표를 잘못 입력하면 이 에러와 마주하게 됩니다. 이 가이드에서는 SyntaxError: Unexpected token의 모든 것을 다루며, 원인 분석부터 실전 해결법, 그리고 예방 전략까지 완벽하게 설명드리겠습니다.

에러 상세 분석

SyntaxError: Unexpected token은 JavaScript의 구문 분석 단계에서 발생하는 에러입니다. 이 에러는 코드 실행 전, 파싱(Parsing) 단계에서 감지되므로 코드가 한 줄도 실행되지 않습니다. 에러 메시지는 보통 “SyntaxError: Unexpected token ‘{‘” 또는 “SyntaxError: Unexpected token ‘}’ “와 같은 형태로 나타나며, 어떤 토큰이 문제인지 명확히 알려줍니다.

JavaScript 엔진은 코드를 토큰(Token) 단위로 분해하여 분석합니다. 토큰은 키워드, 식별자, 연산자, 괄호, 세미콜론 등 코드의 최소 의미 단위를 말합니다. 엔진이 문법 규칙에 맞지 않는 토큰을 만나면 즉시 SyntaxError를 발생시킵니다. 예를 들어, 객체 리터럴에서 중괄호가 닫히지 않았거나, JSON 데이터에 후행 쉼표가 있거나, 함수 선언에서 괄호가 누락된 경우 등이 해당됩니다. 이 에러는 브라우저와 Node.js 환경 모두에서 동일하게 발생하며, 에러 메시지와 함께 문제가 발생한 파일명과 줄 번호가 표시되어 디버깅에 도움을 줍니다.

발생 원인 5가지

1. 괄호 불일치

가장 흔한 원인은 여는 괄호와 닫는 괄호의 개수가 맞지 않는 경우입니다. 중괄호 {}, 대괄호 [], 소괄호 ()의 짝이 맞지 않으면 에러가 발생합니다. 특히 중첩된 구조에서 실수하기 쉽습니다.

// 잘못된 코드
const user = {
  name: 'John',
  address: {
    city: 'Seoul'
  // 중괄호 누락
};

2. 쉼표 오류

객체나 배열에서 쉼표를 빠뜨리거나 불필요한 후행 쉼표(trailing comma)를 사용하면 에러가 발생할 수 있습니다. 특히 JSON 데이터에서는 후행 쉼표가 허용되지 않습니다.

// 잘못된 코드 - 쉼표 누락
const config = {
  host: 'localhost'
  port: 3000
};

3. 예약어 오용

JavaScript의 예약어(const, let, class, return 등)를 변수명이나 속성명으로 잘못 사용하면 문법 오류가 발생합니다.

4. 잘못된 JSON 형식

JSON.parse()를 사용할 때 잘못된 JSON 문자열을 파싱하려고 하면 에러가 발생합니다. JSON은 엄격한 문법 규칙을 따르므로 작은따옴표, 후행 쉼표, 주석 등이 허용되지 않습니다.

5. 잘못된 화살표 함수 문법

화살표 함수의 문법을 잘못 작성하거나, 매개변수 괄호를 빠뜨리거나, 화살표(=>)를 잘못 입력하면 에러가 발생합니다.

// 잘못된 코드
const multiply = x, y => x * y; // 매개변수 괄호 누락

해결방법 7가지

해결법 1: 괄호 짝 맞추기

모든 여는 괄호에 대응하는 닫는 괄호가 있는지 확인합니다. IDE의 괄호 매칭 기능을 활용하면 쉽게 찾을 수 있습니다.

// 올바른 코드
const user = {
  name: 'John',
  address: {
    city: 'Seoul'
  }
};

해결법 2: 쉼표 확인

객체와 배열의 각 요소 사이에 쉼표가 정확히 있는지 확인합니다.

// 올바른 코드
const config = {
  host: 'localhost',
  port: 3000,
  debug: true
};

해결법 3: JSON 유효성 검사

JSON 데이터를 파싱하기 전에 유효성을 검사합니다. try-catch 블록으로 에러를 처리합니다.

// 올바른 코드
try {
  const data = JSON.parse(jsonString);
  console.log(data);
} catch (error) {
  console.error('JSON 파싱 에러:', error.message);
}

해결법 4: 린터(Linter) 사용

ESLint나 JSHint 같은 린터를 사용하면 코드 작성 중 실시간으로 문법 오류를 감지할 수 있습니다.

// .eslintrc.json 설정
{
  "extends": "eslint:recommended",
  "parserOptions": {
    "ecmaVersion": 2021
  }
}

해결법 5: 화살표 함수 문법 수정

화살표 함수에서 매개변수가 여러 개일 때는 반드시 괄호로 감싸야 합니다.

// 올바른 코드
const multiply = (x, y) => x * y;
const square = x => x * x; // 매개변수가 하나일 때는 괄호 생략 가능

해결법 6: 코드 포맷터 사용

Prettier 같은 코드 포맷터를 사용하면 자동으로 코드를 정리하고 문법 오류를 예방할 수 있습니다.

// package.json에 Prettier 스크립트 추가
{
  "scripts": {
    "format": "prettier --write \"src/**/*.js\""
  }
}

해결법 7: 브라우저 개발자 도구 활용

브라우저의 개발자 도구 콘솔에서 정확한 에러 위치와 메시지를 확인합니다. 에러 메시지를 클릭하면 해당 코드 라인으로 바로 이동할 수 있습니다.

// 에러 메시지 예시
// Uncaught SyntaxError: Unexpected token '}' at script.js:15:3
// 15번째 줄, 3번째 문자에서 에러 발생

예방법과 베스트 프랙티스

일관된 코딩 스타일 유지: 팀 전체가 동일한 코딩 컨벤션을 따르면 실수를 줄일 수 있습니다. Airbnb JavaScript Style Guide나 Google JavaScript Style Guide를 참고하세요.

자동화 도구 활용: ESLint, Prettier, 그리고 pre-commit hook을 설정하여 커밋 전에 자동으로 코드를 검사하고 포맷팅합니다.

코드 리뷰: 동료의 코드 리뷰를 통해 놓친 문법 오류를 발견할 수 있습니다.

테스트 작성: 단위 테스트를 작성하면 코드 실행 전에 문법 오류를 발견할 수 있습니다.

IDE 기능 활용: VS Code, WebStorm 등 현대적인 IDE는 실시간 문법 검사 기능을 제공합니다. 이런 기능을 적극 활용하세요.

마무리

SyntaxError: Unexpected token 에러는 JavaScript 개발에서 자주 마주치지만, 원인을 정확히 파악하면 쉽게 해결할 수 있습니다. 괄호 짝 맞추기, 쉼표 확인, JSON 유효성 검사 등 기본적인 체크리스트를 습관화하고, 린터와 포맷터 같은 자동화 도구를 적극 활용하세요. 이 가이드에서 소개한 해결법과 예방법을 실천하면 문법 오류로 인한 개발 시간 낭비를 크게 줄일 수 있습니다. 깨끗하고 오류 없는 코드를 작성하여 생산성을 높이세요!