Sửa lỗi TypeScript TS2688: 'Cannot find type definition file for node'

Thông báo lỗi

Nếu bạn đang xây dựng một ứng dụng Node.js với TypeScript, việc gặp lỗi TS2688 giống như đụng phải một bức tường ngay khi vừa bắt đầu. Terminal hoặc tab Problems của VS Code thường sẽ hiển thị thông báo này:

error TS2688: Cannot find type definition file for 'node'. 
The file is in the program because: Entry point of type library 'node' specified in compilerOptions

Lỗi này làm dừng quá trình build của bạn. Nó xảy ra do TypeScript theo mặc định không nhận diện được các biến global tiêu chuẩn của Node.js như process, __dirname, hoặc Buffer.

Nguyên nhân gây ra lỗi này?

TypeScript cần một "sổ tay hướng dẫn" chuyên biệt để hiểu các lệnh của Node.js. Nếu sổ tay đó bị thiếu hoặc đường dẫn đến nó bị hỏng, bạn sẽ gặp lỗi TS2688. Điều này thường bắt nguồn từ ba vấn đề sau:

Thiếu Package: Bạn chưa cài đặt package @types/node.
Cấu hình bị hạn chế: Tệp tsconfig.json của bạn liệt kê rõ ràng "node" trong mảng types, nhưng các tệp này không có trong node_modules.
Nhầm lẫn đường dẫn: Cài đặt typeRoots tùy chỉnh đang dẫn trình biên dịch đến sai thư mục.

Bước 1: Cài đặt Type Definitions cho Node.js

Cách sửa nhanh nhất là cài đặt các định nghĩa kiểu (type definitions) còn thiếu. Vì Node.js không phải là một phần của thư viện tiêu chuẩn của trình duyệt, TypeScript yêu cầu một package bên ngoài để hiểu môi trường này.

Mở terminal và chạy lệnh tương ứng với trình quản lý package bạn đang dùng:

Sử dụng npm:

npm install --save-dev @types/node

Sử dụng yarn:

yarn add -D @types/node

Sử dụng pnpm:

pnpm add -D @types/node

Luôn sử dụng flag -D hoặc --save-dev. Các định nghĩa này chỉ hữu ích trong quá trình phát triển và không nên làm tăng kích thước mã nguồn sản phẩm cuối cùng của bạn.

Bước 2: Kiểm tra tệp tsconfig.json

Nếu package đã có sẵn nhưng lỗi vẫn không biến mất, hãy xem kỹ bên trong tsconfig.json. Mục compilerOptions thường là nguyên nhân.

Mảng "types"

Khi bạn định nghĩa một mảng types, TypeScript sẽ ngừng tự động tìm kiếm các package khác. Nó sẽ chỉ tải những gì bạn liệt kê. Nếu node có trong danh sách nhưng việc cài đặt package thất bại, lỗi TS2688 sẽ xuất hiện.

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

Hãy thử xóa hoàn toàn thuộc tính "types". Theo mặc định, TypeScript sẽ tự động tìm thấy mọi package bên trong node_modules/@types mà không cần trợ giúp thêm.

Thuộc tính "typeRoots"

Kiểm tra xem bạn có đang bật typeRoots hay không. Cài đặt này sẽ ghi đè đường dẫn tìm kiếm mặc định. Nếu sử dụng nó, bạn phải bao gồm đường dẫn đến thư mục types của mình một cách rõ ràng:

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./src/custom-types"]
  }
}

Bước 3: Làm mới môi trường làm việc

Đôi khi cache của trình soạn thảo chỉ là bị mất đồng bộ. VS Code rất tuyệt, nhưng TypeScript server nội bộ của nó thỉnh thoảng có thể bị kẹt với các lỗi cũ.

Mở bất kỳ tệp .ts nào trong dự án.
Nhấn Ctrl+Shift+P (Windows/Linux) hoặc Cmd+Shift+P (macOS).
Tìm kiếm "TypeScript: Restart TS Server" và nhấn Enter.

Nếu cách đó thất bại, hãy thử "biện pháp mạnh": xóa thư mục node_modules và tệp lock (package-lock.json hoặc pnpm-lock.yaml), sau đó chạy lại npm install. Việc này thường mất chưa đầy 60 giây và sẽ sửa được hầu hết các cây dependency bị lỗi.

Xác minh: Xác nhận lỗi đã được sửa

Để đảm bảo mọi thứ hoạt động bình thường, hãy tạo một tệp check.ts tạm thời. Dán đoạn mã này vào đó:

import os from 'os';
console.log(process.env.NODE_ENV);
console.log(os.platform());

Nếu process và os xuất hiện mà không có các đường răng cưa màu đỏ, bạn đã thành công. Di chuột qua process sẽ hiển thị tooltip xác định nó là một đối tượng NodeJS.Process.

Mẹo nâng cao

Khớp phiên bản chính (Major Version)

Hãy để phiên bản @types/node khớp với Node.js runtime thực tế của bạn. Nếu bạn đang chạy Node 20, hãy cài đặt các types tương ứng để tránh sự sai lệch nhỏ về API:

npm install --save-dev @types/node@20

Sử dụng skipLibCheck

Nếu bạn bắt đầu thấy lỗi từ bên trong thư mục node_modules sau khi sửa lỗi TS2688, hãy bật skipLibCheck trong cấu hình của bạn. Điều này sẽ bỏ qua việc kiểm tra kiểu cho các tệp .d.ts, giúp tăng tốc quá trình build và bỏ qua các lỗi trong thư viện bên thứ ba mà bạn không kiểm soát.

{
  "compilerOptions": {
    "skipLibCheck": true
  }
}