Hướng dẫn cài đặt mã nguồn mẫu
Quy chuẩn các bước chuẩn bị môi trường, giải nén mã nguồn, cấu hình biến môi trường .env, cài đặt dependencies, import cơ sở dữ liệu mẫu và chạy ứng dụng thành công.
Các bước cài đặt tiêu chuẩn từ A đến Z
Chuẩn bị môi trường hệ thống
Đảm bảo máy tính hoặc máy chủ VPS của bạn đã cài đặt các công cụ nền tảng cần thiết:
# Kiểm tra phiên bản môi trường đã cài đặt
node -v
npm -v
git --versionGiải nén mã nguồn & Mở dự án
Sau khi tải file ZIP về từ hệ thống L2 Team, thực hiện giải nén vào thư mục làm việc:
# Mở thư mục dự án trong terminal
cd /duong-dan/thu-muc-ma-nguon
code .Cấu hình biến môi trường (.env)
Sao chép file .env.example thành .env và điền các tham số kết nối cần thiết:
# Linux / macOS / Git Bash
cp .env.example .env
# Windows Command Prompt
copy .env.example .envCài đặt thư viện dependencies
Cài đặt toàn bộ các gói thư viện cần thiết được khai báo trong package.json:
# Cài đặt thư viện tiêu chuẩn
npm install
# Nếu có xung đột phiên bản phụ thuộc
npm install --legacy-peer-depsKhởi tạo dữ liệu mẫu (Seed) & Chạy dự án
Nạp dữ liệu tài khoản quản trị và danh mục mẫu vào MongoDB, sau đó khởi chạy ứng dụng:
# Khởi tạo dữ liệu mẫu vào MongoDB
npm run seed
# Khởi chạy server phát triển
npm run devSự cố thường gặp & Cách xử lý
Dưới đây là một số tình huống lỗi phổ biến trong quá trình cài đặt môi trường và giải pháp khắc phục nhanh chóng:
Lỗi kết nối MongoDB (ECONNREFUSED 127.0.0.1:27017)
Cách khắc phục:Dịch vụ MongoDB chưa được khởi động trên máy tính của bạn. Hãy mở Services (Windows) hoặc chạy `sudo systemctl start mongod` (Linux) hoặc `brew services start mongodb-community` (macOS), hoặc sử dụng chuỗi kết nối MongoDB Atlas Cloud miễn phí.
Lỗi trùng cổng port (EADDRINUSE: address already in use :::3000)
Cách khắc phục:Có một ứng dụng khác đang chiếm cổng 3000. Bạn có thể tắt tiến trình cũ đang chạy, hoặc chỉ định cổng khác trong file .env (ví dụ: PORT=3001) hoặc chạy `npm run dev -- -p 3001`.
Lỗi cảnh báo phiên bản Node.js (ERESOLVE / unsupported engine)
Cách khắc phục:Hãy đảm bảo bạn đang dùng Node.js LTS (v18.x hoặc v20.x). Nếu dùng nvm, gõ `nvm use 20` để chuyển sang phiên bản chuẩn, sau đó xóa thư mục node_modules và chạy lại `npm install`.
Gặp khó khăn khi cài đặt?
Nếu bạn đã làm theo hướng dẫn nhưng vẫn không thể khởi chạy dự án, hãy liên hệ ngay với L2 Team để được kỹ thuật viên hỗ trợ gỡ lỗi trực tiếp qua Ultraview.