Cách khắc phục lỗi 'Module not found: Can't resolve' trong React

Kịch bản lỗiBạn đang tập trung xây dựng một component React mới. Bạn lưu tệp, mong đợi một bản hot reload, nhưng thay vào đó, màn hình của bạn chuyển sang màu đỏ. Một bảng thông báo lỗi khổng lồ xuất hiện, thông báo rằng:

Module not found: Can't resolve './Component' in '/src/components'

Hầu như mọi lập trình viên React đều gặp phải tình trạng này. Điều này đơn giản có nghĩa là bundler của bạn—dù là Vite, Webpack hay Turbopack—đang tìm kiếm một tệp không nằm ở vị trí mà bạn đã chỉ định. Ngay cả khi bạn có thể thấy tệp đó trong thanh bên (sidebar), trình biên dịch vẫn đang bị lạc đường.

Tại sao điều này xảy raTrình biên dịch thường không thể giải quyết (resolve) một đường dẫn vì một trong năm lý do phổ biến sau:

• Sai chính tả đơn giản: Bạn đã viết import Header from './Headr'. Tất cả chúng ta đều đã từng mắc lỗi này.- Phân biệt chữ hoa chữ thường: Bạn đặt tên tệp là Navbar.jsx nhưng lại import là navbar. Điều này hoạt động trên Windows nhưng sẽ gây lỗi ngay lập tức trên các máy chủ triển khai dựa trên Linux như Vercel hoặc Netlify.- Nhầm lẫn phần mở rộng: Vite, không giống như các phiên bản cũ của Create React App, thường yêu cầu phần mở rộng .jsx hoặc .tsx rõ ràng trong đường dẫn import.- Độ sâu đường dẫn: Bạn đang sử dụng ../ trong khi thực tế bạn đang ở sâu ba cấp và cần ../../../.- Cache cũ: Công cụ build của bạn đang ghi nhớ một cấu trúc tệp không còn tồn tại.## Các bước khắc phục từng bước### 1. Kiểm tra các đường dẫn tương đốiBắt đầu bằng cách kiểm tra đường dẫn thực tế. Hãy nhìn kỹ vào thông báo lỗi; nó cho bạn biết chính xác thư mục nào đang được tìm kiếm. Hãy lần theo đường dẫn theo cách thủ công từ tệp chứa lệnh import. Trong 90% trường hợp, tệp chỉ nằm cao hơn hoặc thấp hơn một thư mục so với bạn nghĩ. Sai:

// Vị trí: src/components/layout/Header.js
import Button from './components/Button'; // Lỗi: 'components' là thư mục cùng cấp với 'layout', không phải thư mục con.

Đúng:

// Sử dụng '../' để quay lại một cấp trước
import Button from '../Button';

2. Giải quyết bẫy phân biệt chữ hoa chữ thườngĐây là lỗi dễ gây nhầm lẫn nhất trong phát triển web. Windows và macOS thường không phân biệt chữ hoa chữ thường, nghĩa là chúng coi UserCard.js và usercard.js là cùng một tệp. Tuy nhiên, Linux thì có phân biệt. Nếu kiểu chữ trong lệnh import của bạn không khớp chính xác với tên tệp, ứng dụng của bạn sẽ chạy được ở máy cục bộ nhưng sẽ bị lỗi khi triển khai.

Nếu bạn đã đổi tên tệp và Git không nhận diện được, hãy sử dụng lệnh này để bắt buộc thay đổi:

git mv src/components/oldname.js src/components/OldName.js

3. Xử lý phần mở rộng trong Vite và Next.jsCác công cụ build hiện đại như Vite khắt khe hơn so với các thiết lập mặc định của Webpack cũ. Nếu bạn đang import một component và gặp lỗi resolution, hãy thử thêm phần mở rộng một cách rõ ràng.

import MyComponent from './MyComponent.jsx';

Nếu việc thêm phần mở rộng khắc phục được vấn đề, bạn có thể giữ nó rõ ràng (khuyến nghị cho Vite) hoặc cập nhật vite.config.js để bao gồm extensions: ['.js', '.jsx', '.ts', '.tsx'] trong đối tượng resolve.

4. Chuyển sang Absolute ImportsHãy ngừng vật lộn với "cơn ác mộng chấm-chấm-gạch-chéo". Absolute imports cho phép bạn tham chiếu thư mục src như một thư mục gốc, giúp mã của bạn sạch hơn và dễ dàng di chuyển hơn. Đây là một giải pháp lâu dài cho các vấn đề về đường dẫn.

Thêm tệp jsconfig.json (hoặc tsconfig.json cho TypeScript) vào thư mục gốc của dự án:

{
  "compilerOptions": {
    "baseUrl": "src"
  }
}

Bây giờ, bất kể tệp của bạn nằm sâu đến mức nào, bạn có thể import các component như thế này:

import Button from 'components/shared/Button';

5. Xóa sạch CacheĐôi khi development server bị nhầm lẫn sau một đợt tái cấu trúc mã lớn hoặc chuyển đổi branch. Nếu mã đã hoàn hảo nhưng lỗi vẫn không biến mất, hãy xóa bộ nhớ cache nội bộ. Dừng terminal của bạn và chạy:

• Vite: rm -rf node_modules/.vite && npm run dev- Next.js: rm -rf .next && npm run dev- CRA: Đơn giản chỉ cần khởi động lại quy trình với npm start.## Cách xác minh bản sửa lỗiĐừng chỉ tin vào hot reload. Hãy làm theo ba bước sau để đảm bảo lỗi đã được khắc phục hoàn toàn:
• Hard Refresh: Giữ phím Shift và nhấp vào nút tải lại trong trình duyệt để xóa cache frontend.- Kiểm tra Terminal: Đảm bảo thông báo "Compiled successfully" xuất hiện mà không có cảnh báo ẩn nào.- Chạy Production Build: Chạy lệnh npm run build tại máy cục bộ. Nếu quá trình build thành công, việc xử lý đường dẫn của bạn đã ổn định và sẽ không bị lỗi khi triển khai.## Tóm tắt các giải phápNguyên nhânCách khắc phục nhanhSai chính tảKhớp tên import với tên tệp một cách chính xác.Cấp độ đường dẫnKiểm tra kỹ các bước ../.Kiểu chữ hệ điều hànhSử dụng git mv để sửa kiểu chữ tên tệp cho Linux.Cấu hình ViteThêm phần mở rộng .jsx vào lệnh import.Lỗi ảo (Ghost Error)Xóa thư mục .vite hoặc .next và khởi động lại.