Bỏ qua

🔧 Hướng Dẫn Xử Lý Lỗi Build

Tài liệu này hướng dẫn cách xử lý các lỗi build thường gặp trong dự án.

📋 Mục Lục

  1. Nguyên Nhân Gốc Rễ
  2. Các Lỗi Thường Gặp
  3. Giải Pháp Nhanh
  4. Các Lệnh Build
  5. Khi Nào Cần Build Lại
  6. Troubleshooting Chi Tiết

🔍 Nguyên Nhân Gốc Rễ

1. TypeScript Incremental Compilation Cache

  • Vấn đề: TypeScript sử dụng cache để tăng tốc build, nhưng khi thêm file mới hoặc thay đổi cấu trúc, cache có thể không nhận ra file mới.
  • Triệu chứng: Lỗi File not found mặc dù file đã tồn tại.

2. NX Cache

  • Vấn đề: NX cache các kết quả build để tăng tốc, nhưng cache có thể chứa thông tin cũ.
  • Triệu chứng: Build thành công nhưng chạy lỗi, hoặc không nhận ra thay đổi.

3. Race Condition

  • Vấn đề: Khi chạy yarn dev, các service có thể khởi động trước khi dependencies build xong.
  • Triệu chứng: Lỗi Cannot find module hoặc Could not find main.js.

4. Module Resolution Issues

  • Vấn đề: Path mapping không được resolve đúng trong runtime.
  • Triệu chứng: Lỗi Cannot find module '@football-booking/...'.

⚠️ Các Lỗi Thường Gặp

Lỗi 1: Cannot find module './app.module'

Error: Cannot find module './app.module'
Require stack:
- /path/to/dist/apps/payment-service/src/main.js

Nguyên nhân: Build chưa hoàn tất hoặc cache cũ.

Giải pháp:

yarn build:clean
# Hoặc
yarn dev:fresh

Lỗi 2: Could not find main.js

Error: Could not find /path/to/dist/apps/booking-service/src/main.js

Nguyên nhân: Build chưa chạy hoặc build failed.

Giải pháp:

yarn build:all
# Sau đó
yarn dev

Lỗi 3: File not found (TypeScript)

error TS6053: File '...auth.module.ts' not found.

Nguyên nhân: TypeScript cache không nhận ra file mới.

Giải pháp:

yarn build:clean

Lỗi 4: Cannot find module '@football-booking/...'

Error: Cannot find module '@football-booking/config'

Nguyên nhân: Library chưa được build hoặc path mapping không đúng.

Giải pháp:

# Build tất cả libraries trước
nx run-many --target=build --projects=tag:scope:lib --skip-nx-cache
# Sau đó build tất cả
yarn build:all

⚡ Giải Pháp Nhanh

Khi Thêm Code Mới và Gặp Lỗi

Bước 1: Dừng dev server (nếu đang chạy)

# Nhấn Ctrl+C trong terminal đang chạy yarn dev
# Hoặc
yarn dev:stop

Bước 2: Chọn một trong các giải pháp:

Option 1: Quick Fix (Khuyến nghị)

yarn dev:clean
  • Clear cache
  • Build lại tất cả
  • Start dev server

Option 2: Fresh Start (Khi lỗi nghiêm trọng)

yarn dev:fresh
  • Stop tất cả services
  • Clear cache hoàn toàn
  • Build lại từ đầu
  • Start dev server

Option 3: Chỉ Build Lại

yarn build:clean
# Sau đó
yarn dev

🛠️ Các Lệnh Build

Build Cơ Bản

# Build một project cụ thể
nx build <project-name>

# Build tất cả projects
yarn build:all
# hoặc
nx run-many --target=build --all

Build với Clear Cache

# Clear cache và build lại tất cả
yarn build:clean

Lệnh này sẽ:

  1. Xóa dist/ folder
  2. Xóa .nx/cache/
  3. Xóa node_modules/.cache/
  4. Xóa tất cả *.tsbuildinfo files
  5. Reset NX cache
  6. Build lại tất cả projects (skip cache)

Dev với Clear Cache

# Clear cache, build, và start dev
yarn dev:clean

Lệnh này sẽ:

  1. Clear tất cả cache
  2. Build lại tất cả projects
  3. Start dev server với tất cả services

Fresh Start (Khuyến nghị khi lỗi nghiêm trọng)

# Stop services, clear cache, build, và start lại
yarn dev:fresh

Lệnh này sẽ:

  1. Stop tất cả services đang chạy
  2. Clear tất cả cache
  3. Build lại từ đầu
  4. Start dev server

📅 Khi Nào Cần Build Lại

✅ KHÔNG CẦN Build Lại

  • Sửa code trong file hiện có: NX watch mode sẽ tự động rebuild
  • Thay đổi logic nhỏ: Watch mode sẽ detect và rebuild
  • Sửa lỗi syntax: Watch mode sẽ rebuild

⚠️ CẦN Build Lại

  • Thêm file mới:

bash yarn build:clean

  • Thêm module/service mới:

bash yarn dev:clean

  • Thay đổi cấu trúc thư mục:

bash yarn dev:fresh

  • Thêm dependency mới:

bash yarn install yarn build:clean

  • Gặp lỗi Cannot find module:

bash yarn dev:fresh

  • Gặp lỗi File not found:

bash yarn build:clean

  • Sau khi pull code mới từ git: bash yarn install yarn build:clean

🔧 Troubleshooting Chi Tiết

Vấn đề: Service không khởi động được

Triệu chứng:

Error: Cannot find module './app.module'
Error: Could not find .../main.js

Giải pháp:

  1. Kiểm tra build output:

bash ls -la dist/apps/<service-name>/src/

Nếu không có file .js, cần build lại.

  1. Build lại service cụ thể:

bash nx build <service-name> --skip-nx-cache

  1. Build tất cả: bash yarn build:clean

Vấn đề: Module không được tìm thấy

Triệu chứng:

Error: Cannot find module '@football-booking/config'

Giải pháp:

  1. Kiểm tra library đã được build chưa:

bash ls -la dist/libs/<library-name>/src/

  1. Build library trước:

bash nx build <library-name> --skip-nx-cache

  1. Build tất cả libraries:

bash nx run-many --target=build --projects=tag:scope:lib --skip-nx-cache

  1. Build tất cả: bash yarn build:clean

Vấn đề: TypeScript không nhận ra file mới

Triệu chứng:

error TS6053: File '...new-file.ts' not found.

Giải pháp:

  1. Xóa TypeScript cache:

bash find . -name "*.tsbuildinfo" -delete

  1. Reset NX:

bash nx reset

  1. Build lại: bash yarn build:clean

Vấn đề: Port đã được sử dụng

Triệu chứng:

Error: Port 3000 is already in use

Giải pháp:

  1. Stop tất cả services:

bash yarn dev:stop

  1. Hoặc kill process thủ công:

bash lsof -ti:3000 | xargs kill -9

  1. Start lại: bash yarn dev

Vấn đề: Build chậm hoặc bị treo

Giải pháp:

  1. Clear cache và build lại:

bash yarn build:clean

  1. Kiểm tra disk space:

bash df -h

  1. Kiểm tra memory: bash free -h # Linux # hoặc Activity Monitor trên macOS

📝 Checklist Khi Gặp Lỗi Build

  • [ ] Đã dừng dev server chưa? (yarn dev:stop hoặc Ctrl+C)
  • [ ] Đã clear cache chưa? (yarn build:clean)
  • [ ] Đã build lại tất cả chưa? (yarn build:all)
  • [ ] Đã kiểm tra file có tồn tại không?
  • [ ] Đã kiểm tra dependencies đã được build chưa?
  • [ ] Đã thử yarn dev:fresh chưa?

🚀 Best Practices

1. Luôn Build Sau Khi Thêm File Mới

# Sau khi thêm file mới
yarn build:clean
yarn dev

2. Sử Dụng dev:clean Khi Thêm Module Mới

# Sau khi thêm module/service mới
yarn dev:clean

3. Sử Dụng dev:fresh Khi Gặp Lỗi Nghiêm Trọng

# Khi gặp lỗi không rõ nguyên nhân
yarn dev:fresh

4. Kiểm Tra Build Output

# Sau khi build, kiểm tra output
ls -la dist/apps/<service-name>/src/

5. Build Libraries Trước

# Khi thay đổi library, build library trước
nx build <library-name>
# Sau đó build services
yarn build:all

📞 Cần Giúp Đỡ?

Nếu vẫn gặp vấn đề sau khi thử các giải pháp trên:

  1. Kiểm tra logs chi tiết:

bash nx build <project-name> --verbose

  1. Kiểm tra NX daemon:

bash nx reset

  1. Clean hoàn toàn:

bash rm -rf node_modules dist .nx yarn install yarn build:clean

  1. Kiểm tra TypeScript version: bash npx tsc --version

📚 Tài Liệu Tham Khảo

Lưu ý: File này sẽ được cập nhật khi có thêm các lỗi mới hoặc giải pháp mới.