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
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 đó:
git log --all --oneline -S aspect-ratio -- package.json tailwind.config.js
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:
- 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ó.
Hộp ảnh sập còn 0px ở ProjectCard, ProjectRow và Related
3 component dùng chung một mẫu: hộp relative aspect-video chứa <Image fill>. Đây là ProjectCard:
<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):
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:
printf '@tailwind utilities;\n' > in.css
Rồi sinh CSS cho ProjectCard:
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:
.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ả:
// 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 →- check:seo và check:links trên out/ của Next.js: kiểm HTML đã build, không kiểm source2 gate chạy trong postbuild đọc thẳng out/**/*.html: canonical, og:image, hreflang hai chiều, title trùng, xhtml:link của sitemap, link nội bộ chết. Lỗi làm build fail trước khi deploy.đọc tiếp →
- Critical CSS cho Next.js static: critters, font và màn hình đầu trên PSI mobileSite Next.js static của tôi dính 3 bẫy PSI mobile: CSS chặn render, font inline tải sớm và JS chờ ở màn hình đầu. Đây là cách xử lý từng cái, bắt đầu từ critical CSS bằng critters ở postbuild.đọc tiếp →
- Blog song ngữ trên Next.js static export: translationOf, hreflang và gate fail buildMỗi bài có 2 file Markdown nối nhau bằng một dòng translationOf. Map URL, hreflang, nút đổi ngôn ngữ và gate fail build đều suy ra từ dòng đó, không dùng i18n của Next.đọc tiếp →
- Bỏ server: chuyển site Next.js tĩnh sang Cloudflare Workers Static AssetsSite này chỉ là HTML, JS và ảnh, vậy mà từng nằm trên một VPS 2 GB RAM chung với khoảng 28 site khác. Cách chuyển nó sang Workers Static Assets: dịch cấu hình nginx sang _redirects và _headers, vì sao request không tính vào hạn mức gói Free, và 2 chỗ vấp sau ngày chuyển.đọc tiếp →