blog
check:seo và check:links trên out/ của Next.js: kiểm HTML đã build, không kiểm source
2 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.
- Ngày đăng
check:seo và check:links đọc HTML trong out/ sau khi next build xong, không đọc frontmatter. Thứ Google và Facebook nhận được là HTML, và HTML là kết quả của frontmatter, components/Seo.jsx, file trong public/ và bước rasterize cover. Hỏng ở bất kỳ mắt xích nào thì source vẫn nhìn đúng. Cả 2 gate nằm trong postbuild, nên lỗi làm npm run build fail và workflow deploy dừng ở đó.
postbuild chạy sitemap trước, 2 gate đọc sau
"postbuild": "node scripts/inline-critical-css.js && node scripts/generate-sitemaps.js && node scripts/check-seo.js && node scripts/check-links.js"
npm chạy postbuild ngay sau npm run build, nên build:static của CI cũng đi qua nó. Ở workflow deploy, job publish khai needs: build: build đỏ thì không có gì lên Cloudflare.
Cả 2 script dùng chung scripts/lib/out-html.js, liệt kê mọi .html trong out/ trừ _next, 404 và not-found (các trang noindex, không phải bề mặt công khai). generate-sitemaps.js đứng trước và tự fail nếu số trang blog hoặc dự án trong out/ lệch số file .md: bài thiếu trong out/ nghĩa là build đã hỏng.
og:image phải trỏ tới file có thật trong out/
const ogImage = pick(html, /<meta property="og:image" content="([^"]+)"/)
if (!ogImage) errors.push(`${rel}: thiếu og:image`)
else if (ogImage.startsWith(SITE_URL) && !fs.existsSync(path.join(OUT, ogImage.slice(SITE_URL.length)))) {
errors.push(`${rel}: og:image trỏ file không có trong out/ (${ogImage})`)
}
Cover của bài là SVG, nhưng Facebook, X, LinkedIn và Zalo không render SVG trong og:image. lib/og-image.js đổi /covers/x.svg thành /covers/x.png cho thẻ og, và scripts/rasterize-covers.js sinh file PNG đó ở prebuild. Frontmatter ghi .svg đúng cả khi PNG có lẫn khi PNG vắng. Chỉ HTML cho biết thẻ og trỏ file nào, và chỉ out/ cho biết file đó có thật không.
Trang không khai ảnh thì Seo.jsx rơi về localeMeta[locale].ogImage. Frontmatter của trang đó không để lộ điều này, nên gate cũng bắt ở HTML.
hreflang hai chiều, title trùng, xhtml:link của sitemap
Trên từng trang, gate đòi 0 hoặc 3 thẻ hreflang, x-default trỏ bản vi, và og:locale:alternate phải có khi đủ cặp. Trang /page/N không được có hreflang. Sau đó nó gom mọi trang vào một map theo canonical rồi kiểm chéo:
for (const l of ['vi', 'en']) {
if (!p.hreflang[l] || l === p.lang) continue
const other = pages.get(p.hreflang[l])
if (!other) errors.push(`${p.rel}: hreflang ${l} trỏ tới trang không tồn tại (${p.hreflang[l]})`)
else if (other.hreflang[p.lang] !== canonical) errors.push(`${p.rel}: hreflang ${l} không trỏ ngược lại`)
}
pages.get tra trang thật trong out/ chứ không chỉ so chuỗi, nên hreflang trỏ vào URL không tồn tại cũng đỏ. Cặp vi/en được nối bằng translationOf, như trong bài về blog song ngữ.
Title trùng là lỗi chỉ HTML mới lộ. Danh sách blog là 1 file nguồn nhưng ra nhiều trang /blog/page/N, và nếu không có hậu tố thì chúng cùng title. Seo.jsx thêm (Trang N) hoặc (Page N) vào title và description của các trang đó, còn gate báo trùng bằng một dòng:
for (const [title, rels] of byTitle) if (rels.length > 1) errors.push(`title trùng "${title}": ${rels.join(', ')}`)
Sitemap có một lớp kiểm riêng. Với mỗi <url> trong out/sitemap-*.xml, các thẻ xhtml:link phải bằng hreflang trong HTML của chính trang đó:
if (JSON.stringify(linkMap(body, 'xhtml:link')) !== JSON.stringify(page.hreflang)) {
errors.push(`${name}: ${loc} có xhtml:link lệch hreflang trong HTML`)
}
Hai phía đi qua 2 đường code khác nhau. generate-sitemaps.js đọc translationOf từ frontmatter và chỉ giữ cặp có đủ cả 2 trang trong out/; HTML lấy cặp từ getAlternates trong lib/translations.js. Cùng một fact, 2 cách dựng, và gate so chúng với nhau. JSON.stringify nhạy với thứ tự key, nên cả 2 phía phải in vi, en, x-default theo cùng thứ tự.
check:links bắt link nội bộ chết và link chéo ngôn ngữ
check-links.js lấy mọi <a href="/..."> trong mọi trang, bỏ /_next và //, rồi tìm file tương ứng trong out/:
function exists(href) {
const clean = decode(href.split('#')[0].split('?')[0]).replace(/\/$/, '') || '/'
if (clean === '/') return fs.existsSync(path.join(OUT, 'index.html'))
const p = path.join(OUT, clean)
return (
fs.existsSync(p + '.html') ||
fs.existsSync(path.join(p, 'index.html')) ||
(path.extname(clean) && fs.existsSync(p))
)
}
/x khớp out/x.html hoặc out/x/index.html, giống cách Cloudflare auto-trailing-slash phục vụ site. Hàm chỉ tìm file trong out/ và không đọc _redirects, nên link tới URL cũ dạng /blog/<slug> bị tính là chết dù 301 vẫn chạy. Kết quả có lợi: link trong bài buộc phải trỏ thẳng URL mới.
Luật thứ hai chỉ áp cho phần <article> (thân bài, mục lục, thẻ bài liên quan): trang vi không được link sang /en/... và ngược lại, trừ trang chủ /. LanguageSwitch và footer nằm ngoài <article>, nên chúng được phép link chéo. Bài mồ côi (không bài nào khác link vào) chỉ in cảnh báo, không fail.
Vì sao kiểm trên out/ chứ không trên source
Plan SEO song ngữ bắt buộc chạy gate trên out/ cũ trước khi vá bất cứ thứ gì, và nó phải đỏ. Mốc đo khi review là 270 lỗi trên 70 trang, gồm 20 trang thiếu og:image và 4 trang danh sách vi cùng 4 trang danh sách en trùng title. Nhiều lỗi trong số đó không có dòng frontmatter nào để chỉ vào: trang không khai ảnh, và 4 trang /page/N sinh ra từ 1 file. Gate chưa từng đỏ thì chưa chứng minh được là nó bắt được gì.
Có 3 lý do kiểm output:
- 1 file nguồn có thể ra nhiều trang (phân trang), và lỗi nằm ở từng trang.
- Giữa frontmatter và HTML có code chen vào: fallback og:image, hậu tố
(Trang N), đổi.svgthành.png, điều kiện in hreflang. - Nhiều thứ chỉ tồn tại sau build: PNG song sinh,
sitemap-*.xml, trang đã export.
Chỗ 2 gate này chưa kiểm
- Nội dung ảnh og. Gate kiểm file có trong
out/, nên sửa SVG mà quên rasterize thì PNG cũ vẫn qua. Mắt người là lưới cuối. - Link ngoài.
check-links.jschỉ nhìnhrefbắt đầu bằng/; link ra ngoài do cron tuầncheck-content-freshness.ymlkiểm. - Anchor. Gate cắt phần
#...trước khi tìm file, nên/x#khong-covẫn qua. - Độ dài. Description ngoài khoảng 70-165 ký tự và title trên 65 ký tự chỉ là cảnh báo, không làm build đỏ.
Bài viết liên quan
tất cả bài viết →- 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 →
- Link nội bộ tự động và focusKeyword bằng TF-IDF cho blog Markdown song ngữTF-IDF đề xuất focusKeyword, một script Node chèn link nội bộ thẳng vào file .md của từng ngôn ngữ, và tôi duyệt từng anchor bằng git diff thay vì để build tự chèn.đọc tiếp →
- Gỡ @tailwindcss/aspect-ratio: lỗi im lặng khiến mọi ảnh cover cao 0pxPlugin 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.đọ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 →