Sửa lỗi "Failed opening required vendor/autoload.php" — PHP Composer Autoload Not Found

TL;DR — Sửa nhanh

Chạy composer install trong thư mục gốc của project — thư mục chứa file composer.json. Lệnh này sẽ tạo lại thư mục vendor/ và file autoload.php bị thiếu.

cd /path/to/your/project
composer install

Không có lệnh composer? Xem Cách sửa 3 trước.

Nguyên nhân gây ra lỗi này

Lỗi đầy đủ trông như thế này:

Fatal error: require(): Failed opening required '/var/www/html/vendor/autoload.php'
(include_path='.:/usr/share/php') in /var/www/html/index.php on line 3

PHP gặp dòng lệnh như require __DIR__ . '/vendor/autoload.php'; nhưng file không tồn tại. Có bốn nguyên nhân gây ra điều này:

• vendor/ chưa được tạo — bạn đã clone repo nhưng bỏ qua bước composer install. Đây là nguyên nhân phổ biến nhất.
• vendor/ bị loại trừ có chủ đích — .gitignore không đưa thư mục vendor/ vào version control, nên nó sẽ biến mất sau khi clone mới.
• Sai thư mục làm việc — script của bạn chạy từ một thư mục khác với nơi chứa composer.json, làm hỏng đường dẫn tương đối.
• Autoload map đã cũ — bạn thêm class mới hoặc namespace PSR-4 mới nhưng chưa tạo lại autoloader bằng lệnh dump-autoload.

Các bước sửa lỗi chi tiết

Cách sửa 1 — Chạy composer install (phổ biến nhất)

Di chuyển đến thư mục chứa composer.json và chạy:

composer install

Composer sẽ tải tất cả các dependency vào thư mục vendor/ và ghi file autoload.php. Trên server production khi không cần các package dev:

composer install --no-dev --optimize-autoloader

Cách sửa 2 — Kiểm tra bạn đang ở đúng thư mục

Thông báo lỗi cho bạn biết chính xác nơi PHP đã tìm kiếm. Nếu thông báo là /var/www/html/vendor/autoload.php, hãy xác nhận file composer.json thực sự nằm trong /var/www/html/:

ls /var/www/html/composer.json

Nếu composer.json nằm ở một cấp trên (ví dụ /var/www/), thì đường dẫn require trong file PHP của bạn đang sai. Hãy sửa lại:

// Sai — trỏ đến thư mục không đúng
require __DIR__ . '/vendor/autoload.php';

// Đúng — lên một cấp thư mục
require __DIR__ . '/../vendor/autoload.php';

Khi không chắc chắn, hãy dùng đường dẫn tuyệt đối dựa trên vị trí của composer.json. Cách này không bao giờ sai.

Cách sửa 3 — Cài đặt Composer nếu chưa có

Gặp lỗi command not found: composer? Hãy cài đặt nó globally:

# Linux/macOS
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

# Kiểm tra
composer --version

Người dùng Ubuntu/Debian có thể dùng cách nhanh hơn:

sudo apt install composer

Lưu ý: package từ apt thường chậm cập nhật hơn bản gốc. Để dùng Composer 2.x, phương pháp cài qua curl đáng tin cậy hơn.

Cách sửa 4 — Tạo lại autoload map sau khi thêm class

Nếu thư mục vendor/ đã tồn tại nhưng một class cụ thể vẫn không tìm thấy, autoload map đã bị cũ. Bạn đã thêm code mới mà chưa thông báo cho Composer:

composer dump-autoload

# Classmap được tối ưu cho production (phân giải class nhanh hơn)
composer dump-autoload --optimize

Cách sửa 5 — Sửa lỗi phân quyền khiến Composer bị chặn

Trên shared hosting hoặc bên trong Docker container, composer install có thể thất bại âm thầm khi không thể ghi vào thư mục project. Hãy kiểm tra quyền sở hữu trước:

# Xem ai sở hữu các file
ls -la /var/www/html/

# Sửa quyền sở hữu (thay www-data bằng web user thực tế của bạn)
sudo chown -R www-data:www-data /var/www/html/

# Rồi thử lại
composer install

Cách sửa 6 — Tích hợp vào CI/CD và Docker

Thư mục vendor/ không bao giờ được commit, nên các pipeline tự động cần tự chạy composer install. Một Dockerfile tối giản:

FROM php:8.2-fpm
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer
WORKDIR /var/www/html
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader
COPY . .

Copy composer.json và composer.lock trước phần còn lại của source code. Docker sẽ cache layer install đó và bỏ qua trong các lần build tiếp theo khi hai file này không thay đổi — giúp tiết kiệm đáng kể thời gian cho các project lớn.

Cho GitHub Actions:

- name: Install PHP dependencies
  run: composer install --no-dev --prefer-dist --optimize-autoloader

Kiểm tra kết quả

Kiểm tra nhanh — file autoload.php đã tồn tại chưa?

ls vendor/autoload.php
# vendor/autoload.php

Tải lại ứng dụng của bạn. Với các script CLI:

php index.php

Vẫn thấy lỗi? Đường dẫn require trong file PHP của bạn có thể đang trỏ đến vị trí sai. Hãy so sánh lại với nơi file vendor/autoload.php thực sự tồn tại trên ổ đĩa.

Phòng tránh lỗi tái xảy ra

• Commit composer.lock, không bao giờ commit vendor/.
• Thêm vendor/ vào .gitignore — thư mục này không thuộc về version control.
• Ghi lệnh composer install vào phần setup trong README. Những người đóng góp sau này sẽ cảm ơn bạn.
• Trong Docker, luôn copy composer.json và composer.lock trước các file source để layer dependency được cache đúng cách.