Hướng dẫn cài đặt Laravel trên Windows, macOS và Linux

Để cài Laravel 13 (bản hiện hành), máy cần PHP 8.3 trở lên, Composer và Laravel installer; thêm Node/NPM hoặc Bun để build giao diện. Cách nhanh nhất: cài môi trường bằng php.new hoặc Laravel Herd, chạy laravel new ten-du-an, rồi composer run dev và mở http://localhost:8000. Toàn bộ mất khoảng vài phút trên Windows, macOS lẫn Linux.

Hướng dẫn dưới đây đi theo tài liệu chính thức Laravel 13 Installation (truy cập 01/10/2026). Nếu bạn chưa rõ Laravel là gì, hãy đọc trước bài giới thiệu framework Laravel.

Cần chuẩn bị gì trước khi cài Laravel?

Nếu dự án bắt buộc chạy Laravel 12 (ví dụ hosting chỉ có PHP 8.2), lưu ý Laravel 12 chỉ còn nhận vá bảo mật đến 24/02/2027 theo bảng hỗ trợ chính thức.

Cách 1: Cài PHP, Composer và Laravel installer bằng php.new

php.new là script chính thức được tài liệu Laravel giới thiệu, cài cùng lúc PHP, Composer và Laravel installer. Chọn lệnh theo hệ điều hành:

macOS

/bin/bash -c "$(curl -fsSL https://php.new/install/mac/8.5)"

Windows (PowerShell, chạy bằng quyền Administrator)

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://php.new/install/windows/8.5'))

Linux

/bin/bash -c "$(curl -fsSL https://php.new/install/linux/8.5)"

Chạy xong, đóng và mở lại terminal. Muốn cập nhật PHP, Composer và installer về sau, chỉ cần chạy lại lệnh trên.

Nếu máy đã có sẵn PHP 8.3+ và Composer, bạn chỉ cần cài Laravel installer:

composer global require laravel/installer

Cách 2: Dùng Laravel Herd trên macOS và Windows

Laravel Herd là môi trường phát triển có giao diện đồ họa, đã kèm PHP, Nginx và các lệnh php, composer, laravel, node, npm. Tải bộ cài tại herd.laravel.com. Herd tạo sẵn thư mục "parked" (~/Herd trên macOS, %USERPROFILE%\Herd trên Windows); mọi dự án trong thư mục này tự chạy ở tên miền ten-thu-muc.test.

cd ~/Herd
laravel new my-app
cd my-app
herd open

Bản Herd Pro có thêm quản lý MySQL, PostgreSQL, Redis cục bộ. Đây là lựa chọn dễ nhất cho người mới vì không phải tự cấu hình web server.

Tạo dự án Laravel mới và chạy thử

Sau khi có môi trường, tạo dự án bằng Laravel installer. Trình cài đặt sẽ hỏi bạn có muốn dùng starter kit hay không (React, Svelte, Vue hoặc Livewire, đã có sẵn đăng nhập, đăng ký, quên mật khẩu). Nếu chỉ học framework, có thể chọn không dùng.

laravel new example-app
cd example-app
npm install && npm run build
composer run dev

Lệnh composer run dev khởi động cùng lúc máy chủ phát triển, queue worker và Vite. Mở http://localhost:8000 trên trình duyệt: thấy trang chào mừng của Laravel là cài đặt thành công.

Cấu hình file .env và cơ sở dữ liệu

Các cấu hình phụ thuộc môi trường (khóa ứng dụng, thông tin database, mail…) nằm trong file .env ở thư mục gốc. Không đưa file này lên Git, vì nó chứa mật khẩu và khóa bí mật.

Mặc định, dự án mới dùng SQLite: trình cài đặt đã tạo file database/database.sqlite và chạy migration sẵn. Muốn dùng MySQL, sửa các biến DB_* trong .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=

Tạo database tương ứng rồi chạy migration:

php artisan migrate

Lỗi thường gặp khi cài Laravel và cách xử lý

"laravel: command not found"

Thư mục vendor/bin toàn cục của Composer chưa nằm trong biến PATH. Mở lại terminal sau khi cài php.new; nếu cài bằng Composer, thêm thư mục bin toàn cục của Composer vào PATH (xem bằng lệnh composer global config bin-dir --absolute).

Composer báo yêu cầu phiên bản PHP cao hơn

Thông báo dạng "requires php ^8.3" nghĩa là PHP trên máy thấp hơn yêu cầu của Laravel 13. Kiểm tra php -v, nâng PHP (chạy lại php.new hoặc đổi phiên bản trong Herd) rồi thử lại.

"No application encryption key has been specified"

File .env chưa có APP_KEY, thường gặp khi clone dự án có sẵn. Sao chép .env.example thành .env rồi chạy php artisan key:generate.

"SQLSTATE[HY000] [1045] Access denied for user"

Sai thông tin đăng nhập database trong .env. Kiểm tra lại DB_USERNAME, DB_PASSWORD, DB_DATABASE và chắc chắn database đã được tạo.

"Vite manifest not found"

Chưa build tài nguyên frontend. Chạy npm install && npm run build, hoặc dùng composer run dev khi đang phát triển.

Sau khi cài xong nên học gì tiếp?

• Nắm vai trò từng thư mục trong cấu trúc thư mục Laravel.
• Hiểu một request đi qua những bước nào trong vòng đời request của Laravel.
• Ôn lại mô hình MVC trước khi viết route, controller và view đầu tiên.

Kinh nghiệm từ Hozitech

Website Hozitech chạy trên Laravel. Một lỗi hay gặp khi đưa dự án Laravel lên hosting là trỏ tên miền vào thư mục gốc dự án thay vì thư mục public. Tài liệu Laravel nhấn mạnh ứng dụng phải được phục vụ từ thư mục gốc web (document root trỏ vào public), không đặt trong thư mục con, nếu không có thể lộ file nhạy cảm như .env. Nếu bạn cần một website hoàn chỉnh được lập trình và triển khai sẵn thay vì tự dựng, có thể tham khảo dịch vụ thiết kế website theo yêu cầu.