TypeScript Cannot find name 오류 해결 방법

문제 상황

TypeScript에서 다음과 같은 오류가 표시될 수 있습니다.

TS2304: Cannot find name 'process'.

또는 아래처럼 test global이 잡히지 않을 수 있습니다.

TS2304: Cannot find name 'describe'.

같은 코드가 Node.js, browser, Jest, Vitest 같은 runtime에서는 실행될 수도 있습니다. 그래서 이 오류가 헷갈립니다. Cannot find name은 TypeScript compiler가 compile time에 변수, 함수, type, global name을 볼 수 없다는 뜻입니다.

해결책이 항상 새 변수를 만드는 것은 아닙니다. 대부분은 import를 추가하거나, 올바른 type package를 설치하거나, tsconfig.json 설정을 바로잡아야 합니다.

원인

주요 원인은 다음과 같습니다.

• 필요한 import가 빠졌습니다.
• 변수, 함수, type, interface 이름에 오타가 있습니다.
• package는 설치했지만 type definition이 없습니다.
• process, Buffer, __dirname 같은 Node global을 Node type 없이 사용했습니다.
• describe, it, expect 같은 test global을 test framework type 없이 사용했습니다.
• document, window 같은 browser global을 쓰는데 lib에 DOM이 없습니다.
• 수정한 tsconfig.json이 실제로 해당 파일을 검사하는 config가 아닙니다.
• types option이 있고, 기대한 global type package가 그 목록에서 빠져 있습니다.

오류 메시지에 나온 정확한 이름부터 봐야 합니다. process, User, document, describe의 해결 방법은 서로 다릅니다.

빠른 해결

빠진 이름이 직접 만든 함수, class, type, value라면 import를 추가합니다.

import { createUser } from "./create-user";

빠진 이름이 Node global이라면 Node type definition을 설치합니다.

npm install -D @types/node

그리고 tsconfig.json에서 Node type을 허용하는지 확인합니다.

{
  "compilerOptions": {
    "types": ["node"]
  }
}

이미 types 배열이 있다면 전체를 바꾸지 말고 기존 배열에 node를 추가합니다.

단계별 해결 방법

1. 빠진 Import 확인하기

오류가 다른 파일에서 가져와야 하는 이름을 가리킨다면 TypeScript에는 import가 필요합니다.

잘못된 예:

const user = createUser("Ada");

올바른 예:

import { createUser } from "./create-user";

const user = createUser("Ada");

Type도 마찬가지입니다.

import type { User } from "./types";

function printUser(user: User) {
  console.log(user.name);
}

Editor가 auto-import를 제안하더라도 의도한 파일에서 가져왔는지 확인해야 합니다.

2. 오타와 Scope 문제 확인하기

TypeScript는 대소문자를 구분합니다.

const userName = "Ada";

console.log(username);

userName과 username은 다른 이름입니다.

Scope도 확인합니다.

if (ready) {
  const token = "abc";
}

console.log(token);

token은 if block 안에서만 존재합니다. 필요한 위치에서 사용할 수 있도록 선언 위치를 옮기거나 값을 명시적으로 전달해야 합니다.

3. Node Global 해결하기

빠진 이름이 process, Buffer, __dirname, require라면 Node type이 필요할 가능성이 큽니다.

설치합니다.

npm install -D @types/node

tsconfig.json에 types가 없다면 TypeScript는 보통 보이는 @types package를 자동으로 포함합니다. 하지만 types가 설정되어 있으면 그 목록에 있는 package만 global scope에 추가됩니다.

예시:

{
  "compilerOptions": {
    "types": ["node"]
  }
}

여러 global이 필요한 프로젝트라면 모두 포함합니다.

{
  "compilerOptions": {
    "types": ["node", "vitest/globals"]
  }
}

4. Test Global 해결하기

describe, it, test, expect를 찾지 못한다면 test framework type을 설치하거나 활성화해야 합니다.

Jest:

npm install -D @types/jest

{
  "compilerOptions": {
    "types": ["jest"]
  }
}

Vitest globals:

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

또 다른 안전한 방법은 test function을 명시적으로 import하는 것입니다.

import { describe, expect, it } from "vitest";

이 방식은 project 전체에 global을 늘리지 않습니다.

5. Browser Global 해결하기

document, window, HTMLElement, Event를 찾지 못한다면 lib 설정을 확인합니다.

Browser code라면 DOM을 포함합니다.

{
  "compilerOptions": {
    "lib": ["ES2022", "DOM"]
  }
}

Node-only code라면 DOM을 일부러 제외했을 수 있습니다. Runtime이 실제로 browser API를 제공하지 않는다면 server code에 browser global type을 추가하지 않는 것이 좋습니다.

6. 실제 tsconfig 파일 확인하기

Framework 프로젝트는 config 파일이 여러 개일 수 있습니다.

• tsconfig.json
• tsconfig.app.json
• tsconfig.node.json
• tsconfig.spec.json
• tsconfig.test.json

tsconfig.json을 수정했지만 오류가 test file에서 난다면 실제 config는 tsconfig.spec.json 또는 tsconfig.test.json일 수 있습니다.

다음 명령으로 최종 compiler 설정을 확인합니다.

npx tsc --noEmit --showConfig

기대한 types, lib, include 설정이 없다면 해당 파일을 실제로 포함하는 config를 수정해야 합니다.

7. 오류를 숨기지 않기

아래 코드는 대부분 실제 해결책이 아닙니다.

// @ts-ignore
unknownName();

declare const unknownName: any;

Runtime global을 의도적으로 연결하는 상황이 아니라면 이런 방식은 피하는 것이 좋습니다. 일반적인 app code에서는 빠진 이름을 import하거나 올바른 type definition을 추가해야 합니다.

해결 확인 방법

파일을 생성하지 않고 TypeScript compiler만 실행합니다.

npx tsc --noEmit

Project에 typecheck script가 있다면 그 명령을 사용합니다.

npm run typecheck

관련 app 또는 test 명령도 함께 확인합니다.

npm test
npm run build

대상 symbol에 대한 TS2304: Cannot find name이 사라지고, 설정 변경으로 새로운 type error가 대량으로 생기지 않아야 해결된 것입니다.

흔한 실수

• @types/node를 설치했지만 types 배열에서 node를 빠뜨립니다.
• Runtime 확인 없이 Node-only 프로젝트에 DOM type을 추가합니다.
• 실제로는 tsconfig.app.json이나 tsconfig.spec.json이 쓰이는데 tsconfig.json만 수정합니다.
• 빠진 import 대신 // @ts-ignore를 사용합니다.
• 오류를 없애기 위해 any를 추가합니다.
• Editor auto-import가 항상 올바른 파일을 고른다고 가정합니다.

공식 문서

• TypeScript TSConfig types option
• TypeScript TSConfig lib option
• TypeScript compiler options

관련 글

• JavaScript 오류 ‘Uncaught ReferenceError: is not defined’ 해결 방법
• JavaScript var, let, const 차이 정리
• JavaScript innerHTML과 textContent 차이

자주 묻는 질문

이 글은 언제 먼저 적용하면 좋나요?

오류 메시지, 실행한 명령, 사용 중인 OS와 버전을 먼저 기록한 뒤 이 글의 원인별 순서대로 확인하는 것이 좋습니다.

초보자가 가장 먼저 확인할 부분은 무엇인가요?

처음에는 환경 변수, 설치 경로, 권한, 캐시처럼 재현 가능성이 높은 항목부터 확인하세요. 그다음 로그와 설정 파일을 비교하면 원인을 좁히기 쉽습니다.

더 찾아볼 때 어떤 키워드를 쓰면 좋나요?

추가 검색할 때는 “TypeScript Cannot find name 오류 해결 방법” 같은 핵심 문구와 error message, version, Windows, GitHub Pages, Jekyll 같은 실제 환경 키워드를 붙이면 더 정확한 결과를 얻기 쉽습니다.