SyntaxError: Unexpected token 완벽 해결법 – 원인부터 예방까지

도입

JavaScript 개발을 하다 보면 “SyntaxError: Unexpected token” 에러를 한 번쯤은 마주하게 됩니다. 이 에러는 JavaScript 엔진이 코드를 파싱하는 과정에서 예상하지 못한 문자나 토큰을 발견했을 때 발생합니다. 초보 개발자부터 숙련된 개발자까지 누구나 겪을 수 있는 흔한 에러이지만, 원인을 정확히 파악하지 못하면 디버깅에 많은 시간을 소비하게 됩니다. 이 글에서는 SyntaxError: Unexpected token 에러의 근본 원인부터 실전 해결 방법, 그리고 예방법까지 완벽하게 다루어 여러분의 개발 시간을 절약해드리겠습니다.

에러 상세 분석

SyntaxError: Unexpected token 에러는 JavaScript의 구문 에러(Syntax Error) 중 하나로, 코드 실행 전 파싱 단계에서 발생합니다. 에러 메시지에는 보통 “Unexpected token ‘{‘” 또는 “Unexpected token ‘;'”처럼 어떤 토큰이 문제인지 표시됩니다. 토큰(token)이란 JavaScript 엔진이 코드를 분석할 때 의미를 가진 최소 단위로, 키워드, 연산자, 괄호, 세미콜론 등이 여기에 해당합니다.

이 에러가 발생하면 코드는 전혀 실행되지 않습니다. 런타임 에러와 달리 파싱 단계에서 즉시 차단되기 때문에, 에러가 발생한 파일의 어떤 코드도 동작하지 않습니다. 에러 메시지에는 파일명과 줄 번호가 함께 표시되지만, 실제 문제는 그 이전 줄에 있을 수 있어 주의가 필요합니다. 브라우저 콘솔이나 Node.js 환경에서 에러 스택을 확인하면 정확한 위치를 파악할 수 있습니다.

발생 원인 5가지

1. 괄호, 중괄호, 대괄호 불일치

가장 흔한 원인 중 하나는 여는 괄호와 닫는 괄호의 개수가 맞지 않는 경우입니다. 함수 선언, 객체 리터럴, 배열, 조건문 등에서 중괄호나 괄호를 빠뜨리거나 하나 더 입력하면 발생합니다.

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

JavaScript는 자동 세미콜론 삽입(ASI) 기능이 있지만, 모든 경우에 제대로 작동하지 않습니다. 특히 return 문 다음 줄에 값을 작성하거나, 배열/객체 리터럴 앞에서 세미콜론이 없으면 문제가 발생할 수 있습니다.

3. 문자열 따옴표 처리 오류

문자열을 작성할 때 시작과 끝의 따옴표 종류가 다르거나, 문자열 내부에 이스케이프 처리 없이 같은 종류의 따옴표를 사용하면 에러가 발생합니다. 또한 템플릿 리터럴의 백틱(`)을 잘못 사용해도 같은 문제가 생깁니다.

4. JSON 파싱 오류

JSON.parse()를 사용할 때 잘못된 형식의 JSON 문자열을 전달하면 SyntaxError가 발생합니다. JSON은 JavaScript 객체 리터럴과 비슷하지만 더 엄격한 규칙을 따르므로, 키에 반드시 큰따옴표를 사용해야 하고 후행 쉼표를 허용하지 않습니다.

5. 예약어 잘못 사용

JavaScript의 예약어(class, const, let, return 등)를 변수명이나 속성명으로 사용하거나, 잘못된 위치에서 사용하면 구문 에러가 발생합니다. 특히 오래된 브라우저에서는 strict mode에서만 예약어로 취급되는 단어들도 있어 주의가 필요합니다.

해결방법 7가지

1. 괄호 짝 맞추기

에디터의 괄호 하이라이팅 기능을 활용하거나, 코드 포맷터를 사용하여 괄호 짝이 맞는지 확인합니다.

// 잘못된 예 - 닫는 중괄호 누락
function calculateSum(a, b) {
  return a + b;
// }

// 올바른 예
function calculateSum(a, b) {
  return a + b;
}

2. 세미콜론 올바르게 추가

문장의 끝에 세미콜론을 명시적으로 추가하여 ASI에 의존하지 않도록 합니다.

// 잘못된 예
const result = doSomething()
[1, 2, 3].forEach(item => console.log(item))

// 올바른 예
const result = doSomething();
[1, 2, 3].forEach(item => console.log(item));

3. 문자열 따옴표 통일

문자열의 시작과 끝을 같은 종류의 따옴표로 감싸고, 내부에 같은 따옴표가 필요하면 이스케이프 처리합니다.

// 잘못된 예
const message = "Hello World';

// 올바른 예 1 - 따옴표 통일
const message = "Hello World";

// 올바른 예 2 - 이스케이프 처리
const quote = "He said \"Hello\"";

// 올바른 예 3 - 템플릿 리터럴 사용
const greeting = `He said "Hello"`;

4. JSON 형식 검증

JSON 문자열이 올바른 형식인지 확인하고, JSON 린터를 사용하여 검증합니다.

// 잘못된 예 - 키에 따옴표 없음, 후행 쉼표 존재
const jsonString = '{name: "John", age: 30,}';

// 올바른 예
const jsonString = '{"name": "John", "age": 30}';
const data = JSON.parse(jsonString);

5. 화살표 함수 문법 확인

화살표 함수에서 객체 리터럴을 반환할 때는 괄호로 감싸야 합니다.

// 잘못된 예 - 중괄호를 함수 본문으로 인식
const createUser = (name) => {name: name, role: 'user'};

// 올바른 예 - 괄호로 객체 리터럴 감싸기
const createUser = (name) => ({name: name, role: 'user'});

6. 조건부 연산자 올바르게 사용

삼항 연산자의 구조를 정확히 지키고, 복잡한 경우 괄호로 명확히 구분합니다.

// 잘못된 예 - 콜론 누락
const status = age >= 18 ? 'adult' 'minor';

// 올바른 예
const status = age >= 18 ? 'adult' : 'minor';

7. try-catch로 JSON 파싱 에러 처리

JSON.parse()를 사용할 때 에러를 대비하여 try-catch 문으로 감싸 안전하게 처리합니다.

// 안전한 JSON 파싱
try {
  const data = JSON.parse(jsonString);
  console.log(data);
} catch (error) {
  console.error('JSON 파싱 실패:', error.message);
  // 기본값 사용 또는 에러 처리
}

예방법과 베스트 프랙티스

1. ESLint 같은 린터 사용: 코드 작성 중 실시간으로 구문 에러를 감지하여 미리 방지할 수 있습니다.

2. Prettier 같은 코드 포맷터 활용: 자동으로 코드를 정리하고 일관된 스타일을 유지하여 괄호 누락 같은 실수를 줄입니다.

3. 모던 에디터의 기능 활용: VS Code, WebStorm 등 모던 에디터는 괄호 짝 맞추기, 구문 하이라이팅, 에러 표시 기능을 제공합니다.

4. 코드 리뷰 문화: 동료 개발자의 코드 리뷰를 통해 놓치기 쉬운 구문 에러를 사전에 발견할 수 있습니다.

5. 단위 테스트 작성: 코드 변경 시마다 테스트를 실행하여 구문 에러를 조기에 발견하고 수정할 수 있습니다.

마무리

SyntaxError: Unexpected token 에러는 JavaScript 개발에서 가장 자주 마주치는 에러 중 하나이지만, 원인을 정확히 파악하면 쉽게 해결할 수 있습니다. 괄호 짝 맞추기, 세미콜론 확인, 문자열 따옴표 통일 등 기본적인 규칙을 지키고, 린터와 포맷터 같은 도구를 활용하면 대부분의 에러를 예방할 수 있습니다. 에러 메시지를 꼼꼼히 읽고, 에러가 발생한 줄뿐만 아니라 그 이전 줄도 함께 확인하는 습관을 들이시기 바랍니다. 이 글이 여러분의 디버깅 시간을 줄이고 더 생산적인 개발에 도움이 되길 바랍니다.