SyntaxError: Unexpected token 완벽 해결 가이드

도입

JavaScript 개발 중 SyntaxError: Unexpected token 에러를 만나면 당황스러울 수 있습니다. 이 에러는 JavaScript 엔진이 코드를 파싱하는 과정에서 예상하지 못한 문자나 구문을 발견했을 때 발생합니다. 초보 개발자부터 숙련된 개발자까지 누구나 한 번쯤 마주치는 흔한 에러이지만, 원인을 정확히 파악하면 빠르게 해결할 수 있습니다. 이 가이드에서는 SyntaxError: Unexpected token 에러의 발생 원인과 구체적인 해결 방법, 그리고 예방하는 베스트 프랙티스까지 상세히 다룹니다. 코드 예제와 함께 실전에서 바로 적용할 수 있는 솔루션을 제공하므로, 이 글을 통해 에러를 완벽하게 해결하고 더 나은 코드를 작성할 수 있습니다.

에러 상세 분석

SyntaxError는 JavaScript의 구문 규칙을 위반했을 때 발생하는 에러입니다. ‘Unexpected token’은 파서가 특정 위치에서 예상하지 못한 토큰(문자, 기호, 키워드 등)을 발견했다는 의미입니다. 예를 들어, SyntaxError: Unexpected token '}'는 닫는 중괄호가 예상치 못한 위치에 있다는 뜻이며, SyntaxError: Unexpected token 'const'는 const 키워드가 잘못된 위치에 사용되었음을 나타냅니다.

이 에러는 코드 실행 전 파싱 단계에서 발생하므로, 해당 코드 블록은 전혀 실행되지 않습니다. 에러 메시지는 일반적으로 문제가 발생한 파일명, 줄 번호, 컬럼 위치를 포함하고 있어 디버깅에 도움이 됩니다. 브라우저 개발자 도구나 Node.js 콘솔에서 에러 스택 트레이스를 확인하면 정확한 위치를 파악할 수 있습니다. 다만, 실제 문제는 에러가 표시된 위치보다 앞쪽에 있는 경우가 많으므로 주의 깊게 살펴봐야 합니다.

발생 원인 5가지

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

가장 흔한 원인은 여는 괄호와 닫는 괄호의 개수가 맞지 않는 경우입니다. 함수, 객체, 배열, 조건문 등에서 괄호를 빠뜨리거나 추가로 작성하면 발생합니다. 특히 중첩된 구조에서 실수하기 쉽습니다.

2. 콤마(,) 누락 또는 잘못된 사용

객체 리터럴이나 배열에서 요소 사이의 콤마를 빠뜨리거나, 마지막 요소 뒤에 불필요한 콤마를 추가하면(구버전 브라우저) 에러가 발생할 수 있습니다. JSON 데이터를 다룰 때 특히 주의해야 합니다.

3. 세미콜론(;) 누락

JavaScript는 자동 세미콜론 삽입(ASI) 기능이 있지만, 특정 상황에서는 예상과 다르게 동작할 수 있습니다. 특히 즉시 실행 함수(IIFE)나 배열/객체로 시작하는 라인에서 문제가 발생합니다.

4. 예약어 잘못된 사용

JavaScript의 예약어(const, let, class, return 등)를 변수명이나 속성명으로 사용하거나, 잘못된 컨텍스트에서 사용하면 에러가 발생합니다. 엄격 모드(strict mode)에서는 더 많은 제약이 있습니다.

5. 문자열 따옴표 불일치

문자열을 시작한 따옴표(‘, “, `)와 종료 따옴표가 일치하지 않거나, 문자열 내부에서 이스케이프 처리 없이 같은 따옴표를 사용하면 에러가 발생합니다. 템플릿 리터럴(백틱)과 일반 따옴표를 혼동하는 경우도 많습니다.

해결방법 7가지 (코드 포함)

해결법 1: 괄호 짝 맞추기

여는 괄호와 닫는 괄호의 개수를 확인하고 누락된 부분을 추가합니다.

// 잘못된 코드
function calculate(a, b) {
  return a + b;
// 닫는 중괄호 누락

// 올바른 코드
function calculate(a, b) {
  return a + b;
}

해결법 2: 객체 리터럴 콤마 수정

객체의 각 속성 사이에 콤마를 올바르게 추가합니다.

// 잘못된 코드
const user = {
  name: 'John'
  age: 30
};

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

해결법 3: 배열 요소 콤마 확인

배열 요소 사이의 콤마를 정확하게 위치시킵니다.

// 잘못된 코드
const numbers = [1, 2 3, 4];

// 올바른 코드
const numbers = [1, 2, 3, 4];

해결법 4: 문자열 따옴표 통일

문자열의 시작과 끝 따옴표를 일치시키고, 내부 따옴표는 이스케이프 처리합니다.

// 잘못된 코드
const message = "He said, "Hello"";

// 올바른 코드 1: 이스케이프 사용
const message = "He said, \"Hello\"";

// 올바른 코드 2: 다른 따옴표 사용
const message = "He said, 'Hello'";

// 올바른 코드 3: 템플릿 리터럴 사용
const message = `He said, "Hello"`;

해결법 5: JSON 파싱 에러 해결

JSON 데이터의 구조를 올바르게 작성하고, 파싱 시 try-catch로 에러를 처리합니다.

// 잘못된 JSON
const jsonString = '{name: "John", age: 30}';

// 올바른 JSON (속성명에 큰따옴표 필요)
const jsonString = '{"name": "John", "age": 30}';

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

해결법 6: 화살표 함수 구문 수정

화살표 함수의 괄호와 중괄호를 올바르게 사용합니다.

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

// 올바른 코드 1: 중괄호와 return 사용
const multiply = (a, b) => {
  return a * b;
};

// 올바른 코드 2: 암시적 반환
const multiply = (a, b) => a * b;

해결법 7: 조건문 구문 확인

if, for, while 등의 조건문에서 괄호와 중괄호를 정확하게 배치합니다.

// 잘못된 코드
if (x > 10)
  console.log('크다');
  console.log('아주 크다');  // 항상 실행됨

// 올바른 코드
if (x > 10) {
  console.log('크다');
  console.log('아주 크다');
}

예방법과 베스트 프랙티스

1. 린터(Linter) 사용

ESLint 같은 린터를 프로젝트에 적용하면 코드 작성 중 실시간으로 구문 에러를 감지할 수 있습니다. 자동 포맷팅과 함께 사용하면 더욱 효과적입니다.

2. 코드 에디터 활용

VS Code, WebStorm 등의 최신 에디터는 괄호 짝 맞추기, 구문 강조, 에러 표시 기능을 제공합니다. 이러한 도구를 적극 활용하세요.

3. 일관된 코딩 스타일

Prettier 같은 자동 포맷터를 사용하여 일관된 들여쓰기와 코딩 스타일을 유지하면 구문 에러를 줄일 수 있습니다.

4. 코드 리뷰

동료 개발자와 코드 리뷰를 진행하면 본인이 놓친 구문 에러를 발견할 수 있습니다.

5. 점진적 개발

많은 코드를 한 번에 작성하기보다, 작은 단위로 나누어 작성하고 테스트하면 에러 발생 시 원인을 쉽게 찾을 수 있습니다.

마무리

SyntaxError: Unexpected token 에러는 JavaScript 개발에서 매우 흔하게 발생하지만, 원인을 이해하고 체계적으로 접근하면 빠르게 해결할 수 있습니다. 괄호 짝 맞추기, 콤마 확인, 따옴표 통일 등의 기본적인 체크리스트를 습관화하고, 린터와 코드 에디터의 도움을 받으면 대부분의 구문 에러를 사전에 방지할 수 있습니다. 이 가이드에서 제시한 해결 방법들을 실전에 적용하여 더욱 안정적인 JavaScript 코드를 작성하시기 바랍니다. 에러는 학습의 기회이므로, 각 에러를 통해 JavaScript 구문 규칙을 더 깊이 이해하고 성장하시길 바랍니다.