Block template không áp dụng trong WordPress? Hãy bắt đầu từ database

File template của bạn gần như chắc chắn đang bị bỏ qua vì một bản sao trong database đang thắng. Ngay khi bạn mở một template trong Site Editor và bấm Save, WordPress ghi ra một bản ghi wp_template, và từ đó trở đi bản ghi ấy được phục vụ thay cho file .html trong thư mục theme — nên mọi chỉnh sửa bạn làm với file sau đó đều vô hình ngoài front end. Xoá bản ghi đó là cách sửa, và đây là thứ đầu tiên cần kiểm tra trước khi bạn đụng tới cây phân cấp, tên file hay cache.

Xác nhận bản sao trong database có tồn tại

Vào Appearance → Editor → Templates. Mọi template mà WordPress đang phục vụ từ database đều được đánh dấu trong danh sách — tuỳ phiên bản WordPress, nhãn ghi “Customized” hoặc template xuất hiện dưới bộ lọc “Customized”. Cái nhãn đó chính là toàn bộ câu trả lời. Nếu nó có ở đó, file của bạn không hề được dùng.

Bạn có thể kiểm tra đúng điều đó từ dòng lệnh, cách này nhanh hơn và vẫn chạy được ngay cả khi Site Editor đang trở chứng:

wp post list --post_type=wp_template --fields=ID,post_name,post_status,post_title
wp post list --post_type=wp_template_part --fields=ID,post_name,post_status,post_title

Mỗi dòng là một bản ghi đè trong database. post_name khớp với slug của template, nên một dòng tên single đang che mất templates/single.html.

Có một chi tiết hay làm người ta vấp: các bản ghi này gắn với một theme thông qua một term trong taxonomy, chứ không phải qua đường dẫn. Nếu bạn đổi tên thư mục theme, các template đã lưu vẫn nằm trong database nhưng ngừng khớp với theme đang kích hoạt, và site đột ngột rơi về dùng file. Chuyện đó trông giống “tuỳ biến của tôi bay mất” hơn là “file của tôi bị bỏ qua” — cùng một cơ chế, triệu chứng ngược nhau.

Xoá nó đi

Trong Site Editor, mở menu tuỳ chọn của template (dấu ba chấm bên cạnh) và chọn Clear customizations — một số phiên bản ghi là Reset. Thao tác đó xoá bản ghi trong database và quyền điều khiển quay về file trên đĩa.

Nếu menu hiện Delete thay vì Clear customizations hay Reset, nghĩa là template đó chỉ tồn tại trong database và không có file nào phía sau. Xoá nó là gỡ hẳn template đi và WordPress sẽ rơi xuống các bậc thấp hơn trong cây phân cấp.

Từ WP-CLI, dùng một ID lấy từ danh sách bên trên:

wp post delete 482 --force

Hãy thành thật với chính mình về cái giá ở đây: xoá tuỳ biến là vứt vĩnh viễn mọi thứ bạn đã dựng trong Site Editor cho template đó, và không hoàn tác được. Nếu bản trong Site Editor chứa công sức thật, hãy chép markup block ra trước — mở template trong editor, chuyển sang chế độ xem code, rồi dán kết quả vào file .html của bạn. Như vậy file trở thành nguồn chân lý duy nhất và không mất gì cả.

WordPress chọn template như thế nào

Block theme dùng đúng logic phân cấp như classic theme, chỉ khác là file .html trong templates/ thay vì file .php ở gốc theme. WordPress đi từ cụ thể nhất tới chung nhất và dùng file đầu tiên tồn tại.

Đang xem	Kiểm tra theo thứ tự này
Một bài viết đơn	single-post-{slug}.html → single-post.html → single.html → singular.html → index.html
Một trang	page-{slug}.html → page-{id}.html → page.html → singular.html → index.html
Một trang lưu trữ chuyên mục	category-{slug}.html → category-{id}.html → category.html → archive.html → index.html
Một custom post type	single-{post-type}.html → single.html → singular.html → index.html
Trang 404	404.html → index.html

Có hai thứ đè lên toàn bộ chuyện này. Thứ nhất là bản ghi trong database đã nói ở trên. Thứ hai là một template được gán thẳng cho một bài viết hoặc một trang — mở trình soạn thảo bài viết, tìm panel Template trong sidebar, và xem có cái gì cụ thể đang được chọn ở đó không. Việc gán rõ ràng luôn thắng cây phân cấp, và nó vô hình trừ khi bạn chủ động đi tìm.

Template dựa trên slug mong manh theo một cách rất đáng ghi nhớ. page-about.html chỉ khớp khi slug của trang còn là about. Đổi tên trang thành about-us là template ngừng áp dụng, không cảnh báo, không báo lỗi.

Template và template part

Một template render trọn một khung nhìn và được chọn bởi cây phân cấp. Một template part là một mảnh ghép — header, footer, sidebar — mà template kéo vào. Part nằm trong parts/, template nằm trong templates/, và chúng được lưu riêng trong database dưới dạng bản ghi wp_template_part.

Nhầm lẫn hay gặp: bạn sửa header, và thay đổi hiện ra ở cả những trang bạn không định đụng tới. Đó là hành vi đúng. Một part được dùng chung bởi mọi template có gọi nó. Nếu bạn muốn một header khác cho riêng một template, bạn cần một file part thứ hai và một template tham chiếu tới nó — sửa cái part dùng chung sẽ không bao giờ cho bạn sự khác biệt theo từng template.

Chiều ngược lại cũng xảy ra. Bạn nhét cả bố cục một trang vào parts/ rồi thắc mắc vì sao cây phân cấp chẳng bao giờ nhặt nó lên. Part hoàn toàn không phải ứng viên trong cây phân cấp; không có gì định tuyến thẳng tới chúng cả.

Đặt tên và vị trí file

Hãy kiểm tra những điều này trước khi nghĩ tới thứ gì cao siêu hơn:

• Thư mục là templates/, số nhiều, ở gốc theme. Không phải template/, không phải block-templates/. block-templates/ là tên đúng thời còn plugin Gutenberg, trước khi block theme vào core, và khối bài hướng dẫn vẫn còn ghi như vậy — nó không chạy trên WordPress hiện tại.
• Template part nằm trong parts/, không phải template-parts/ (đó là quy ước của classic theme cho các file partial PHP).
• Đuôi mở rộng là .html. File .php nằm trong templates/ sẽ bị bỏ qua.
• Tên file viết thường và dùng dấu gạch ngang. single-Post.html hay single_post.html sẽ không khớp. Trên hệ thống file không phân biệt hoa thường như macOS thì nó chạy ngon ở máy bạn rồi vỡ trên server Linux — một ca “chạy tốt trên máy tôi” kinh điển.
• Bắt buộc phải có templates/index.html. Thiếu nó, WordPress không xếp theme vào loại block theme và Site Editor có thể không xuất hiện chút nào.
• Nếu bạn đang làm trong child theme, template của nó được ưu tiên hơn của theme cha. Một file còn sót lại trong child theme sẽ lặng lẽ thắng file bạn đang sửa ở theme cha.

Các template tuỳ chỉnh cần chọn được trong trình soạn thảo bài viết còn phải được khai báo trong theme.json dưới customTemplates, kèm tên gốc của file, một tiêu đề dễ đọc, và các post type mà nó áp dụng. Không có mục đó thì file vẫn tồn tại nhưng không bao giờ xuất hiện trong panel Template.

Cache — kiểm tra sau cùng

Cache là chuyện có thật nhưng nó là nguyên nhân ít khả năng nhất, và nhảy vào nó trước là cách người ta đốt cả buổi chiều.

Xả cache trang, và nếu bạn chạy object cache lâu dài như Redis hay Memcached thì xả luôn cái đó — kết quả phân giải template có thể bị giữ trong đó. Rồi tải lại trang với chế độ bỏ qua cache trình duyệt.

Thứ sẽ không giúp gì: xoá OPcache. Block template là file .html và không bao giờ được PHP biên dịch, nên OPcache chẳng liên quan gì tới chúng. Nếu có lần xả OPcache trông như đã sửa được lỗi này cho bạn, thì có thứ khác đã thay đổi cùng lúc đó.

Vẫn tắc?

Nếu không có bản ghi nào trong database, tên file đã đúng, không có template nào được gán rõ ràng cho bài viết, và cache đã xả rồi, hãy ngó sang plugin. Bất cứ thứ gì can thiệp vào quá trình phân giải template — page builder, plugin hội viên, plugin đa ngôn ngữ, LMS — đều có thể tráo template của riêng nó vào muộn trong request. Chuyển sang một block theme mặc định và thử với toàn bộ plugin đã tắt, rồi bật lại từng cái một.

Còn nếu template có áp dụng nhưng render ra rỗng, đó lại là vấn đề khác: hãy kiểm tra markup block trong file có hợp lệ không, vì một comment block viết sai có thể khiến editor lặng lẽ cắt bỏ nội dung thay vì báo lỗi.