en

blog

Gỡ @tailwindcss/aspect-ratio: lỗi im lặng khiến mọi ảnh cover cao 0px

Plugin aspect-ratio thay theme.aspectRatio nên Tailwind core ngừng phát aspect-video. Hộp ảnh sập còn 0px, mọi cover vô hình, build vẫn xanh. Đây là cách tôi lần ra và chặn lỗi này.

Ngày đăng
Tailwind CSS 3Next.js 16Silent failureDebugging
2 khung so sánh cấu hình aspect-ratio: bên trái là hộp ảnh 16:9 đầy đủ khi chỉ dùng core, bên phải chỉ còn một vạch mảnh ghi height 0px khi có plugin, kèm dòng build passed, warnings 0

Plugin aspect-ratio của Tailwind (@tailwindcss/aspect-ratio) bị gỡ khỏi site này có chủ đích. Khi nó còn trong config, class aspect-video biến mất khỏi CSS, mọi hộp ảnh cover sập còn 0px, và next build vẫn xanh, không một cảnh báo. Bài này ghi lại nguyên nhân, cách lỗi lọt qua mọi gate, và cách kiểm để nó không quay lại.

Plugin aspect-ratio ghi đè theme.aspectRatio, core ngừng phát aspect-video

Plugin phục vụ cú pháp aspect-w-16 aspect-h-9 của chính nó. Để làm vậy, nó thay theme.aspectRatio bằng {1..16}. Tailwind core đọc theme.aspectRatio để phát aspect-video và aspect-square, nên khi bảng đó bị thay, 2 class này không còn được sinh ra.

Config gốc của repo còn tắt luôn core plugin. Lịch sử git cho thấy plugin vào cùng lúc với cả khối đó:

bash
git log --all --oneline -S aspect-ratio -- package.json tailwind.config.js
text
0aa5692 feat: add new blog posts and automate cover image generation pipeline
02d9ed8 baseline before upgrades

Commit 02d9ed8 (2025-10-01) đưa cả require('@tailwindcss/aspect-ratio') lẫn corePlugins: { aspectRatio: false } vào tailwind.config.js. Commit 0aa5692 (2026-07-21) gỡ cả hai:

text
-  corePlugins: {
-    aspectRatio: false,
-  },
   plugins: [
-    require('@tailwindcss/aspect-ratio'),

Tailwind 3 hỗ trợ aspect-ratio sẵn. Plugin chỉ cần cho browser đời cũ, và tôi chọn bỏ nó.

3 component dùng chung một mẫu: hộp relative aspect-video chứa <Image fill>. Đây là ProjectCard:

jsx
<div className="relative aspect-video w-full overflow-hidden border-b border-black/10 bg-omega-800 dark:border-white/10">
  <Image src={cover.src} alt={cover.alt || title} fill ... />
</div>

Với fill, ảnh nằm tuyệt đối trong hộp cha, nên hộp không có nội dung nào đẩy chiều cao ra. Chiều cao của nó đến hoàn toàn từ aspect-video. Mất class đó trong CSS là hộp còn 0px, và mọi ảnh cover ở /du-an, trang chủ và card bài liên quan thành vô hình. ProjectRow và Related có cùng mẫu.

PostRow nhẹ hơn: ảnh thật ở đó có width và height nên giữ được kích thước, còn aspect-video chỉ nằm ở khung placeholder { } khi bài thiếu cover. Grep toàn repo thấy aspect-video ở 5 file (thêm ImageGallery qua wrapperClassName):

bash
grep -rn "aspect-video" components layouts pages

Build xanh và không cảnh báo: vì sao không gate nào bắt được

Với Tailwind, một class không có rule tương ứng chỉ là một chuỗi trong thuộc tính className. Không có gì để báo lỗi. HTML vẫn hợp lệ, CSS vẫn biên dịch, và các gate của repo kiểm thứ khác: check:seo kiểm canonical, hreflang, và file og:image có trong out/, không kiểm hộp ảnh có cao hơn 0px.

Repo cũng không có test runner (AGENTS.md mục 1). Lưới cuối là bước ghi ở mục review: build thật rồi mở trang ra xem, cả light lẫn dark mode. Lỗi này lọt qua mọi lớp tự động và chỉ lộ ra khi nhìn trang.

Nó cùng họ với một lỗi im lặng khác của repo: thiếu secret của workflow deploy vẫn build xanh nhưng inline undefined, nên form liên hệ và newsletter hỏng mà không ai báo.

Cách phát hiện: kiểm CSS được phát ra, đừng chờ cảnh báo

Cảnh báo không có thì phải kiểm đầu ra. Tailwind CLI cho phép sinh CSS chỉ từ một file component, nên kiểm được aspect-video có mặt hay không mà không cần build cả site. Tạo file đầu vào một dòng:

bash
printf '@tailwind utilities;\n' > in.css

Rồi sinh CSS cho ProjectCard:

bash
npx tailwindcss -c tailwind.config.js -i in.css -o out.css --content components/ProjectCard.jsx

Tôi chạy lệnh này với config hiện tại, và out.css có đúng khối cần thấy:

css
.aspect-video {
  aspect-ratio: 16 / 9
}

Theo ghi chú trong tailwind.config.js, thêm lại plugin thì khối này biến mất, nên grep aspect-video out.css trả rỗng là tín hiệu lỗi. Kiểm tra này chưa nằm trong gate của repo; hiện nó là một lệnh chạy tay khi đụng tới tailwind.config.js.

Chặn lỗi quay lại: ghi bẫy ngay cạnh dòng config

Lần sau ai đó (hoặc một agent) thấy aspect-w-16 trong tài liệu và định thêm plugin, thứ chặn họ phải nằm đúng chỗ họ sẽ sửa. Repo ghi bẫy ở 2 nơi: comment ngay trên khối plugins của tailwind.config.js, và AGENTS.md mục 4 với dòng "đừng thêm lại". Comment trong config mô tả cả nguyên nhân lẫn hậu quả:

js
// KHÔNG thêm lại @tailwindcss/aspect-ratio. Plugin đó ghi đè `theme.aspectRatio`
// thành {1..16} để phục vụ cú pháp `aspect-w-16 aspect-h-9`, khiến core không
// còn sinh ra `aspect-video`/`aspect-square` nữa.

Ghi chú trong config nói plugin chỉ cần cho browser đời cũ, nên đó là nhóm duy nhất chịu thiệt khi bỏ nó, và tôi chấp nhận. Còn cú pháp aspect-w-16 aspect-h-9 thì không còn dùng ở đâu trong repo: grep ở components, layouts, pages, styles không thấy aspect-w- hay aspect-h-.

Bài viết liên quan

tất cả bài viết →