Tổng hợp những lỗi thường gặp khi phát triển website bán hàng Laravel (Shop-main) và cách khắc phục hiệu quả

Shop-main là một nền tảng website bán hàng mã nguồn mở được xây dựng trên nền tảng Laravel, hỗ trợ đầy đủ các chức năng như quản lý sản phẩm, giỏ hàng, thanh toán online, nhập – xuất kho và phân quyền người dùng. Trong quá trình phát triển và triển khai dự án này ở cả môi trường local và production, có nhiều lỗi quen thuộc mà lập trình viên hoặc người triển khai thường gặp phải. Dưới đây là những lỗi tiêu biểu và cách xử lý hiệu quả nhất đã được kiểm chứng trong thực tế.

InvalidArgumentException: Please provide a valid cache path in Shop-main(Itcctv shop) Laravel 11

Lỗi này xảy ra khi hệ thống không tìm thấy các thư mục cache cần thiết trong storage/, đặc biệt khi bạn vừa clone source code Shop-main về hoặc chưa cấp quyền đầy đủ cho thư mục.

– Cách khắc phục:

mkdir -p storage/framework/cache/data

chmod -R 775 storage

chown -R www-data:www-data storage

php artisan config:clear

php artisan cache:clear

php artisan config:cache

php artisan route:cache

Laravel không hiển thị ảnh khi chuyển từ Amazon S3 sang Localhost

Shop-main hỗ trợ lưu ảnh trên Amazon S3 ở môi trường production. Tuy nhiên, khi bạn chuyển source code về máy local mà không có kết nối với S3, ảnh sẽ không hiển thị nếu không điều chỉnh cấu hình.

– Cách xử lý:

+ Chuyển sang sử dụng disk local trong .env:

FILESYSTEM_DISK=public

+ Cập nhật mã lưu ảnh từ:

Storage::disk(‘s3’)->put(…) sang: Storage::disk(‘public’)->put(…)

+ Tạo symbolic link:

php artisan storage:link

+ Ảnh sau đó sẽ được lưu tại storage/app/public/ và truy cập qua URL /storage/….

500 Internal Server Error khi deploy

Lỗi 500 thường gặp khi lần đầu triển khai Shop-main lên môi trường production và có thể đến từ nhiều nguyên nhân.

– Các bước xử lý:

+ Cài đặt thư viện:

composer install

+ Tạo file .env nếu chưa có và cập nhật đầy đủ biến cấu hình.

+ Tạo APP_KEY:

php artisan key:generate

+ Cấp quyền cho thư mục:

chmod -R 775 storage bootstrap/cache

+ Clear và cache lại:

php artisan config:cache

php artisan route:cache

Class not found khi tạo Controller, Model, hoặc Service

Lỗi này xảy ra khi bạn tạo file mới mà không chạy lại autoload hoặc sai namespace.

– Cách xử lý:

+ Kiểm tra lại namespace đầu file.

+ Chạy lại:

composer dump-autoload

CSRF Token mismatch khi submit form hoặc gọi AJAX

Shop-main sử dụng CSRF để bảo vệ các form gửi POST. Nếu bạn gửi form mà thiếu token, hệ thống sẽ báo lỗi CSRF token mismatch.

– Cách khắc phục:

+ Với Blade, luôn dùng @csrf trong form.

+ Với HTML thuần:

<input type=”hidden” name=”_token” value=”{{ csrf_token() }}”>

+ Với AJAX:

$.ajaxSetup({

headers: {

‘X-CSRF-TOKEN’: $(‘meta[name=”csrf-token”]’).attr(‘content’)

}

});

SQLSTATE[HY000]: Connection refused / Access denied

Lỗi này xuất hiện khi Laravel không thể kết nối đến database.

– Cách xử lý:

+ Kiểm tra cấu hình .env:

DB_CONNECTION=mysql

DB_HOST=127.0.0.1

DB_PORT=3306

DB_DATABASE=shopmain

DB_USERNAME=root

DB_PASSWORD=

– Kiểm tra xem MySQL có đang chạy: sudo service mysql status

Không tạo được symbolic link khi upload ảnh sản phẩm

Để ảnh được upload qua backend có thể hiển thị trên frontend, bạn cần tạo symbolic link đúng cách.

– Cách xử lý:

php artisan storage:link

Đảm bảo thư mục public/storage liên kết đúng với storage/app/public.

Lỗi khi gọi API từ frontend hoặc app di động

Nếu bạn phát triển thêm frontend mobile hoặc SPA dùng API từ Laravel, lỗi CORS hoặc xác thực token là điều thường gặp.

– Cách khắc phục:

+ Cài middleware fruitcake/laravel-cors nếu chưa có.

+ Cấu hình file config/cors.php cho phép domain frontend:

‘paths’ => [‘api/*’],

‘allowed_origins’ => [‘*’], // hoặc [‘https://your-frontend.com’]

Trong quá trình phát triển và triển khai hệ thống Shop-main, việc gặp lỗi là điều khó tránh khỏi, nhưng nếu nắm rõ nguyên nhân và cách xử lý, bạn có thể giải quyết nhanh chóng và hiệu quả. Hy vọng bài viết này sẽ là tài liệu tham khảo hữu ích cho các lập trình viên đang làm việc với Laravel nói chung và hệ thống bán hàng Shop-main nói riêng.