Cách sửa lỗi 'SyntaxError: Unexpected token <' trong các dự án React JSX

Kịch bản lỗi

Bạn vừa kết thúc một phiên lập trình hoặc chuyển sang một công cụ build mới. Bạn nhấn làm mới, mong đợi thấy ứng dụng của mình, nhưng màn hình vẫn trắng xóa. Khi mở console của trình duyệt, bạn nhận được một dòng thông báo bí ẩn:

Uncaught SyntaxError: Unexpected token '<'

Lỗi này rất gây ức chế vì nó hiếm khi chỉ ra một component cụ thể. Thay vào đó, nó báo hiệu một sự đứt gãy cơ bản giữa server và trình duyệt của bạn. Về cơ bản, trình duyệt đang mong đợi một file JavaScript nhưng lại nhận được thứ khác—thường là một file HTML.

Tại sao trình duyệt lại thấy ký tự '<'?

Có hai vấn đề chính thường gây ra lỗi này trong môi trường React:

Lỗi Transpilation JSX: Trình duyệt không thể đọc trực tiếp JSX. Nếu bạn cố gắng chạy <App /> mà không chuyển đổi nó sang JavaScript chuẩn trước, trình duyệt sẽ gặp ký tự < đầu tiên và dừng lại ngay lập tức. Điều này xảy ra nếu công cụ build của bạn (Babel, Vite, hoặc SWC) không xử lý các file một cách chính xác.
Bẫy HTML Fallback: Đây là nguyên nhân phổ biến nhất. File index.html của bạn có thể yêu cầu /main.js, nhưng nếu server không tìm thấy file đó, nó thường trả về index.html thay thế. Vì các file HTML bắt đầu bằng <!DOCTYPE html>, trình duyệt cố gắng phân tích ký tự < đầu tiên đó dưới dạng JavaScript và thất bại.

Khắc phục nhanh: Kiểm tra đường dẫn và phần mở rộng file

Hãy bắt đầu với những giải pháp đơn giản nhất trước khi can thiệp vào các file cấu hình.

1. Sử dụng tab Network

Mở Developer Tools (F12) và đi tới tab Network. Làm mới trang. Tìm các gói JavaScript (bundles) của bạn, chẳng hạn như bundle.js hoặc main.jsx. Nếu bạn thấy trạng thái 404 Not Found, đường dẫn script của bạn đã sai. Nhấp vào yêu cầu bị lỗi và kiểm tra tab con "Response"; nếu bạn thấy mã HTML ở đó, nghĩa là server đang trả về trang chủ thay vì script của bạn.

2. Quy định nghiêm ngặt về phần mở rộng file trong Vite

Vite nhanh hơn Webpack nhưng nghiêm ngặt hơn nhiều. Theo mặc định, nó sẽ không transpile JSX bên trong một file có đuôi .js. Nếu component của bạn chứa các thẻ <div> nhưng lại được đặt tên là App.js, hãy đổi tên nó thành App.jsx. Thay đổi duy nhất này sẽ khắc phục lỗi cho nhiều lập trình viên khi chuyển từ Create React App sang.

Khắc phục triệt để: Cấu hình Build Pipeline

Nếu các đường dẫn đã đúng nhưng trình duyệt vẫn thấy JSX thô, bạn cần kiểm tra lại các thiết lập transpiler.

Cấu hình Webpack và Babel

Các dự án React hiện đại sử dụng Webpack yêu cầu babel-loader và React preset. Trước tiên, hãy xác nhận rằng các package đã được cài đặt:

npm install --save-dev @babel/preset-react babel-loader

Cập nhật file babel.config.json của bạn để sử dụng modern JSX transform. Điều này giúp loại bỏ yêu cầu phải import React trong mọi file:

{
  "presets": [
    ["@babel/preset-react", {
      "runtime": "automatic"
    }]
  ]
}

Trong file webpack.config.js, hãy đảm bảo loader nhắm mục tiêu đến cả các file .js và .jsx:

module.exports = {
  module: {
    rules: [
      {
        test: /\.(js|jsx)$/,
        exclude: /node_modules/,
        use: "babel-loader"
      }
    ]
  },
  resolve: {
    extensions: [".js", ".jsx"]
  }
};

Cấu hình Vite

Vite yêu cầu plugin React chính thức để xử lý JSX. Nếu bạn bắt đầu một dự án Vite "vanilla" và thêm React sau đó, có thể bạn đang thiếu plugin này. Cài đặt nó qua terminal:

npm install @vitejs/plugin-react --save-dev

Sau đó, hãy đảm bảo file vite.config.js của bạn đã bao gồm plugin này:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()]
})

Xử lý Routing phía Server (Express/Nginx)

Lỗi này có chỉ xuất hiện khi bạn làm mới một trang như myapp.com/settings không? Điều này xảy ra vì trình duyệt tìm kiếm script tại myapp.com/settings/main.js thay vì ở thư mục gốc. Nếu thẻ script của bạn sử dụng đường dẫn tương đối như src="main.js", nó sẽ bị lỗi trên bất kỳ trang con nào.

Cách khắc phục: Buộc trình duyệt tìm kiếm ở thư mục gốc bằng cách thêm một dấu gạch chéo vào trước nguồn script trong file index.html:

<!-- Tránh cách này -->
<script src="bundle.js"></script>

<!-- Sử dụng đường dẫn tuyệt đối -->
<script src="/bundle.js"></script>

Debug và Phòng ngừa

Các lỗi build thường ẩn nấp trong những sai sót cú pháp nhỏ trong phần cấu hình của bạn. Khi tôi khắc phục sự cố trong package.json hoặc các đối tượng Babel phức tạp, tôi thường sử dụng JSON Formatter của ToolCraft. Nó làm nổi bật các dấu phẩy bị thiếu hoặc các dấu ngoặc không khớp khiến các công cụ build âm thầm bỏ qua các thiết lập của bạn. Nếu bạn đang chuyển cấu hình từ pipeline CI/CD dựa trên YAML quay lại cấu hình JSON cục bộ, bộ chuyển đổi YAML sang JSON của ToolCraft sẽ giúp đảm bảo logic vẫn giữ nguyên.

Xác minh cuối cùng

Xóa sạch Cache: Xóa thư mục node_modules/.cache (Webpack) hoặc node_modules/.vite (Vite) và khởi động lại server.
Kiểm tra Page Source: Nhấp chuột phải vào ứng dụng của bạn trong trình duyệt và chọn "View Page Source". Nhấp vào liên kết dẫn đến file JavaScript của bạn. Nếu bạn thấy <!DOCTYPE html>, routing của server đang bị sai. Nếu bạn thấy các thẻ <div>, transpiler của bạn đã bị bỏ qua.