Tài liệu kỹ thuật tiêu chuẩn

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.

Quy trình triển khai 5 bước

Các bước cài đặt tiêu chuẩn từ A đến Z

01

Chuẩn bị môi trường hệ thống

Bước 01 / 05

Đả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:

Node.js phiên bản LTS (khuyến nghị v18.x hoặc v20.x trở lên)
Trình quản lý gói: npm (đi kèm Node.js), pnpm hoặc yarn
Cơ sở dữ liệu: MongoDB Community Server (local) hoặc kết nối MongoDB Atlas (Cloud)
Công cụ lập trình: Visual Studio Code, Git và MongoDB Compass để trực quan hóa dữ liệu
Terminal / Command Prompt
# Kiểm tra phiên bản môi trường đã cài đặt
node -v
npm -v
git --version
02

Giải nén mã nguồn & Mở dự án

Bước 02 / 05

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:

Giải nén tệp .zip (không nên giải nén vào thư mục có đường dẫn chứa dấu tiếng Việt hoặc khoảng trắng)
Mở thư mục dự án bằng Visual Studio Code
Cấu trúc thư mục chuẩn bao gồm: /app (hoặc /src), /components, /models, /lib, .env.example, README.md
Terminal / Command Prompt
# Mở thư mục dự án trong terminal
cd /duong-dan/thu-muc-ma-nguon
code .
03

Cấu hình biến môi trường (.env)

Bước 03 / 05

Sao chép file .env.example thành .env và điền các tham số kết nối cần thiết:

MONGODB_URI: Chuỗi kết nối cơ sở dữ liệu MongoDB (mặc định mongodb://localhost:27017/ten_du_an)
PORT: Cổng lắng nghe của server (mặc định 3000 hoặc 5000)
JWT_SECRET: Khóa bí mật dùng để mã hóa và xác thực token đăng nhập
NEXT_PUBLIC_APP_URL: Địa chỉ domain hoặc http://localhost:3000 khi chạy thử nghiệm
Terminal / Command Prompt
# Linux / macOS / Git Bash
cp .env.example .env

# Windows Command Prompt
copy .env.example .env
04

Cài đặt thư viện dependencies

Bước 04 / 05

Cài đặt toàn bộ các gói thư viện cần thiết được khai báo trong package.json:

Chạy lệnh cài đặt thư viện bằng npm hoặc pnpm
Nếu gặp thông báo cảnh báo peer dependencies cũ, thêm cờ --legacy-peer-deps
Đợi quá trình tải các package hoàn tất vào thư mục node_modules
Terminal / Command Prompt
# 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-deps
05

Khởi tạo dữ liệu mẫu (Seed) & Chạy dự án

Bước 05 / 05

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:

Chạy lệnh seed data (nếu package.json có khai báo script seed)
Khởi chạy server ở chế độ phát triển (Development Mode)
Mở trình duyệt truy cập http://localhost:3000 để kiểm tra giao diện
Tài khoản quản trị viên mặc định: admin@l2code.dev (Mật khẩu: 123456)
Terminal / Command Prompt
# 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 dev
Khắc phục lỗi cài đặt

Sự 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`.

Hỗ trợ trực tiếp từ Kỹ thuật viên

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.

Yêu cầu hỗ trợ Ultraview