Sửa lỗi TypeScript 'Cannot redeclare block-scoped variable' Xung đột với Global Types

TL;DR — Sửa Nhanh

Thêm một dòng export {} trỗng vào đầu file. Một dòng duy nhất đó biến file thành ES module và loại bỏ xung đột với các DOM global tích hợp sẵn của TypeScript.

// Thêm dòng này vào đầu file
export {};

const name = 'John';

Lỗi Gặp Phải

Cannot redeclare block-scoped variable 'name'.

Bạn viết const name = 'John' — một khai báo hoàn toàn bình thường. TypeScript lại báo lỗi. Không có biến name nào khác trong file. Mọi thứ trông ổn. Vậy mà dấu gạch đỏ vẫn xuất hiện ngay lập tức.

Nguyên Nhân

Một file .ts không có câu lệnh import hay export nào sẽ bị TypeScript xem là global script, không phải ES module. Điều này có nghĩa là các biến cục bộ của bạn dùng chung phạm vi với các khai báo kiểu tích hợp sẵn của TypeScript.

Sâu bên trong lib.dom.d.ts, TypeScript có khai báo này:

// Bên trong lib.dom.d.ts (tích hợp sẵn của TypeScript)
declare var name: string;

const name của bạn đụng thẳng vào khai báo đó. Các biến thường gây ra xung đột này:

• name — window.name
• document — window.document
• location — window.location
• event — window.event
• status — window.status
• origin — window.origin

Các Cách Sửa

Cách 1: Thêm export {} vào file (Khuyên dùng)

Chỉ một dòng. Không có tác dụng phụ. Một export rỗng báo cho TypeScript biết file này là một module, do đó nó có phạm vi riêng biệt.

// Ở đầu file của bạn
export {};

const name = 'Alice';
const location = 'Tokyo';

console.log(name, location);

Mọi thứ bên dưới vẫn giữ nguyên. Đây là cách sửa phổ biến nhất cho ứng dụng trình duyệt, các dự án React/Vue/Angular — bất cứ thứ gì liên quan đến DOM.

Cách 2: Xóa lib.dom khỏi tsconfig (chỉ dành cho Node.js)

Đang xây dựng công cụ CLI hay script backend? Bạn có thể không cần DOM types. Hãy bỏ dom khỏi mảng lib:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"]
  }
}

Không có dom, TypeScript sẽ không tải lib.dom.d.ts, nên name, document và các biến tương tự sẽ không còn tồn tại dưới dạng global nữa.

Cảnh báo: Đừng bao giờ làm vậy trong dự án React, Vue hay Angular. Xóa dom sẽ làm hỏng tất cả các kiểu browser API ngay lập tức.

Cách 3: Đổi tên biến bị xung đột

Đôi khi cách nhanh nhất là đổi tên. Chọn một tên không bị trùng:

// Trước (xung đột với window.name)
const name = getUserName();

// Sau
const userName = getUserName();
const displayName = getUserName();

Ổn với code mới. Kém hấp dẫn hơn khi bạn đang refactor và cần sửa một biến được dùng ở 40 chỗ.

Cách 4: Bật isolatedModules trong tsconfig

Đang dùng Vite, esbuild hay Babel? Các bundler này biên dịch từng file độc lập — và isolatedModules: true giúp TypeScript hoạt động nhất quán với điều đó:

{
  "compilerOptions": {
    "isolatedModules": true,
    "target": "ESNext",
    "module": "ESNext"
  }
}

Khi bật flag này, TypeScript sẽ cảnh báo bất cứ khi nào một file không có import hay export và không được xác định rõ là module. Bạn phát hiện vấn đề từ gốc thay vì đuổi theo triệu chứng.

Cách 5: Bọc code trong block scope hoặc IIFE

Đang chạy script thử nhanh với ts-node? Thêm export có vẻ thừa. Block scope hoặc IIFE cũng cho kết quả tương tự:

// Block scope
{
  const name = 'Bob';
  console.log(name);
}

// Hoặc IIFE
(function () {
  const name = 'Bob';
  console.log(name);
})();

Cách này hoạt động được. Chỉ là ít mang tính chuẩn hơn export {} đối với bất cứ thứ gì ngoài script dùng một lần.

Kiểm Tra Sau Khi Sửa

Chạy trình biên dịch TypeScript ở chế độ chỉ kiểm tra — không xuất file, chỉ báo lỗi:

# Chạy TypeScript compiler với no-emit để chỉ kiểm tra lỗi
npx tsc --noEmit

# Hoặc nếu đã cài tsc globally
tsc --noEmit

Không có output nghĩa là code sạch. Trong VS Code, dấu gạch đỏ sẽ biến mất ngay khi bạn lưu file — không cần khởi động lại.

Tại Sao Lỗi Này Hay Xảy Ra Với File Mới

File .ts mới tạo, chưa có import — bạn đang ở chế độ global script ngay từ phím gõ đầu tiên. Ngay khi bạn thêm một import thực sự (chẳng hạn import một utility từ file khác), TypeScript sẽ tự động chuyển file sang chế độ ES module và xung đột sẽ tự biến mất.

Đó là lý do lỗi này thường xuất hiện ở:

• Các script tiện ích độc lập không có import
• Các file cấu hình TypeScript
• Các đoạn code thử nghiệm độc lập
• Các file bị xóa hết import trong quá trình refactor gần đây

Tóm Tắt

Tình huốngCách sửa tốt nhất


Ứng dụng Browser / React / VueThêm `export {}` vào file
Node.js / công cụ CLIXóa `dom` khỏi `lib` trong tsconfig
Dự án Vite / esbuildBật `isolatedModules: true`
Script nhanh, không cần moduleBọc trong block scope `{ }`