Sửa lỗi 'The package could not be installed. The theme is missing the style.css stylesheet' trong WordPress

Lỗi Gặp Phải

Bạn vào Appearance → Themes → Add New → Upload Theme trong wp-admin, chọn file .zip, nhấn Install, và WordPress trả về thông báo:

The package could not be installed. The theme is missing the style.css stylesheet.

Theme không được cài đặt. WordPress từ chối gói ngay lập tức — không có file nào được giải nén, không có thông báo rollback hữu ích, chỉ là một cái chặn hoàn toàn.

Nguyên Nhân

WordPress tìm kiếm style.css ở thư mục gốc của zip sau khi giải nén. File đó phải tồn tại và chứa comment header hợp lệ của theme. Thiếu một trong hai điều kiện là WordPress sẽ không xử lý tiếp.

Có bốn nguyên nhân phổ biến trong thực tế:

• Cấu trúc zip sai — zip chứa một thư mục bọc ngoài, khiến WordPress giải nén thành my-theme/my-theme/style.css thay vì my-theme/style.css.
• Zip từ GitHub — "Download ZIP" từ repo thường đặt style.css bên trong thư mục con như dist/ hoặc src/, không nằm ở thư mục gốc.
• Thiếu theme header — style.css tồn tại nhưng thiếu dòng Theme Name: bắt buộc trong khối comment ở đầu file.
• Zip nhầm thư mục — bạn vô tình nén thư mục cha chứa thư mục theme, tạo thêm một cấp lồng nhau thừa.

Cách Sửa 1: Kiểm Tra và Sửa Cấu Trúc Zip

Chín trong mười trường hợp, đây là vấn đề của bạn. Trước khi upload bất cứ thứ gì, hãy kiểm tra xem bên trong zip thực sự chứa gì.

Trên macOS/Linux:

unzip -l my-theme.zip | head -20

Trên Windows, mở zip bằng File Explorer hoặc 7-Zip và kiểm tra nội dung ở cấp trên cùng.

Cấu trúc đúng cần thấy:

my-theme/
my-theme/style.css
my-theme/index.php
my-theme/functions.php
...

Cấu trúc gây ra lỗi (lồng nhau hai cấp):

my-theme/
my-theme/my-theme/
my-theme/my-theme/style.css
my-theme/my-theme/index.php
...

Bị lồng nhau hai cấp? Hãy nén lại zip từ đúng thư mục:

# Giải nén zip
unzip my-theme.zip

# Vào thư mục theme thực sự
cd my-theme/my-theme

# Nén lại từ bên trong — style.css sẽ nằm ở gốc zip
zip -r ../../my-theme-fixed.zip .

# Upload my-theme-fixed.zip

Cách Sửa 2: Zip Từ GitHub / Kho Mã Nguồn

Chức năng "Download ZIP" của GitHub đóng gói toàn bộ repo — không chỉ riêng theme. Nhiều theme premium và mã nguồn mở lưu theme có thể cài đặt bên trong một thư mục con như theme/, dist/, hoặc src/. Bạn cần nén thư mục con đó, không phải thư mục gốc của repo.

• Tải về và giải nén zip từ GitHub.
• Tìm thư mục có style.css nằm trực tiếp bên trong.
• Chỉ nén thư mục đó:

# Sau khi giải nén zip GitHub:
ls repo-main/
# → dist/  src/  README.md  ...

ls repo-main/dist/
# → style.css  index.php  functions.php  ← đây là thứ bạn cần

cd repo-main/dist
zip -r ../../my-theme.zip .

# Bây giờ upload my-theme.zip

Cũng nên kiểm tra thêm: một số repo có sẵn file my-theme.zip được đóng gói sẵn bên trong bản tải về. Đó thường là file dành cho WordPress — hãy tìm nó trước khi tự đóng gói lại thủ công.

Cách Sửa 3: Thêm hoặc Sửa Header trong style.css

Một file style.css tồn tại nhưng không có theme header cũng tệ như file bị thiếu. WordPress cần đọc header để đăng ký theme. Mở style.css và đảm bảo phần đầu file trông như thế này:

/*
Theme Name: My Theme
Theme URI: https://example.com/my-theme
Author: Your Name
Author URI: https://example.com
Description: A short description of the theme.
Version: 1.0.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: my-theme
*/

Về mặt kỹ thuật, Theme Name: là dòng duy nhất bắt buộc. Mọi thứ còn lại là tùy chọn — nhưng điền đầy đủ là thói quen tốt. Thêm header vào, nén lại zip, rồi upload lần nữa.

Cách Sửa 4: Cài Đặt Qua FTP

Chán phải vật lộn với trình upload của wp-admin? Hãy bỏ qua nó hoàn toàn bằng FTP/SFTP và đưa thư mục theme thẳng vào wp-content/themes/:

# Kết nối qua SFTP
sftp user@your-server.com

# Điều hướng đến thư mục themes
cd /var/www/html/wp-content/themes/

# Upload thư mục theme trực tiếp
put -r /local/path/to/my-theme .

Hoặc dùng rsync nếu bạn thích:

rsync -avz /local/path/to/my-theme/ user@your-server.com:/var/www/html/wp-content/themes/my-theme/

Sau khi upload xong, vào Appearance → Themes trong wp-admin. Theme sẽ hiển thị và bạn có thể kích hoạt trực tiếp — không cần hộp thoại upload nữa.

Cách Sửa 5: WP-CLI (Nhanh Nhất Khi Có SSH)

Có quyền truy cập SSH? WP-CLI là lựa chọn gọn nhất:

# Cài từ file zip local
wp theme install /path/to/my-theme.zip --activate

# Cài từ WordPress.org theo slug
wp theme install twentytwentyfour --activate

# Kiểm tra các theme đã cài
wp theme list

WP-CLI cũng cho thông báo lỗi chi tiết hơn nhiều so với wp-admin khi gói vẫn còn vấn đề.

Kiểm Tra Sau Khi Sửa

Sau khi sửa và upload lại:

• Vào Appearance → Themes — thẻ theme phải hiển thị với tên và ảnh thumbnail.
• Nhấn Activate — trang web phải tải với theme mới được áp dụng.
• Truy cập frontend và xác nhận giao diện hiển thị đúng.
• Mở Appearance → Customize và kiểm tra xem có lỗi nào không.

Theme đã kích hoạt nhưng trang web trông bị lỗi? Đó là vấn đề khác — thiếu plugin bắt buộc, child theme không có parent theme, v.v. Không liên quan đến lỗi upload này.

Phòng Ngừa

• Kiểm tra trước khi upload — chạy unzip -l theme.zip | head -5 ở local để xác nhận cấu trúc đúng trước khi đụng vào wp-admin.
• Tải từ dashboard của nhà cung cấp, không phải GitHub — các nhà cung cấp theme premium đóng gói zip cài đặt đúng cách. Zip mã nguồn từ GitHub hầu như không bao giờ đúng cấu trúc.
• Tự động hóa việc đóng gói — đang tự xây dựng theme? Một target trong Makefile đảm bảo bạn luôn nén từ đúng thư mục:

# Ví dụ Makefile target
pack:
    cd .. && zip -r my-theme.zip my-theme/ --exclude "my-theme/.git/*" --exclude "my-theme/node_modules/*"
    mv my-theme.zip my-theme/dist/