en

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
Next.js 16SEOhreflangBuild gate
Cửa sổ out/ ở giữa liệt kê vài file html và xml, 3 thẻ nhỏ bên trái ghi frontmatter, Seo.jsx và public/ nối vào, 2 đường màu accent đi ra tới 2 thẻ có dấu tích tên check:seo và check:links

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

json
"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/

js
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.

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:

js
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:

js
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 đó:

js
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.js lấy mọi <a href="/..."> trong mọi trang, bỏ /_next và //, rồi tìm file tương ứng trong out/:

js
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 .svg thà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.js chỉ nhìn href bắt đầu bằng /; link ra ngoài do cron tuần check-content-freshness.yml kiểm.
  • Anchor. Gate cắt phần #... trước khi tìm file, nên /x#khong-co vẫ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 →