SEO Next.js: metadata, sitemap và JSON-LD cho blog
SEO Next.js cho blog: đặt metadata, sơ đồ trang và JSON-LD để Google hiểu bài viết, kèm bẫy sitemap không cập nhật trên Vercel và cách chặn preview bị index.
SEO kỹ thuật cho blog Next.js gồm ba phần: metadata (tiêu đề, mô tả, canonical) để Google biết mỗi trang nói gì, sơ đồ trang (sitemap) để nó tìm thấy mọi bài, và JSON-LD để nó hiểu đó là một bài viết. Bạn muốn blog mình được tìm thấy chứ? Cùng thử nhé!
Ba thứ Google cần để biết blog của bạn tồn tại
Ở bài trước, blog đã có trình soạn bài an toàn và ảnh được nén gọn. Nhưng Google chưa biết nó có mặt, và nếu biết rồi thì nó cũng chưa có đủ thông tin để hiểu từng trang. Mình chia việc thành ba phần, và với mỗi phần mình sẽ cho bạn thấy cả code dựng nó lẫn cách kiểm tra.
Phần đầu là metadata: thẻ <title>, mô tả, địa chỉ chuẩn (canonical) và các bản ngôn ngữ khác (hreflang). Phần hai là sơ đồ trang, một file XML liệt kê mọi địa chỉ để công cụ tìm kiếm không phải mò từng liên kết. Phần ba là dữ liệu có cấu trúc JSON-LD, một khối dữ liệu nói rõ "đây là một BlogPosting, tác giả là ai, đăng ngày nào". Thêm một thứ nữa là chặn bản xem trước (preview deployment) khỏi bị index, vì đó là chuyện dễ làm ngược.
Có một điều cần nói trước: không phần nào trong số này bảo đảm trang sẽ lên top. Chúng chỉ giúp công cụ tìm kiếm hiểu đúng trang của bạn. Nội dung tốt vẫn là thứ quyết định.
Để bạn làm theo được mà không cần Next.js, mình dựng các thành phần dưới dạng hàm thuần chạy bằng Node.js. Ý tưởng giống hệt code của blog này, chỉ là blog thật gọi chúng từ bên trong Next.js. Bạn cần Node.js 22.18 trở lên, vì từ bản đó Node chạy thẳng file .ts, và không cần cài thêm gì. Tạo thư mục seo-blog với cấu trúc:
seo-blog/
package.json
thu.ts
src/ld.ts
src/sitemap-xml.ts
src/head.ts
src/kiem-seo.ts{
"name": "seo-blog",
"private": true,
"type": "module"
}Metadata: title, description, canonical, hreflang
Với Next.js (App Router), bạn khai báo metadata bằng cách export một hàm generateMetadata trong trang, hoặc một đối tượng metadata. Framework biến nó thành các thẻ trong <head>. Cách dùng đầy đủ có trong tài liệu về metadata của Next.js. Mình không chép lại cú pháp ở đây, vì điều đáng nói hơn là hai cái bẫy thực tế mình gặp ở blog này.
Cái bẫy thứ nhất: metadata từ nhiều tầng (layout và page) được gộp nông (shallow merge), và khóa trùng bị thay thế chứ không trộn. Tài liệu của Next.js nói điều này ở phần về thứ tự gộp. Hậu quả là nếu trang bài viết đặt alternates hay openGraph thì nó thay hẳn đối tượng của layout, và mọi thứ layout đã đặt trong đó (tên site, ngôn ngữ, đường dẫn RSS) biến mất. Trong file src/lib/metadata.ts của blog có hẳn một ghi chú về chuyện này, và giải pháp là dựng metadata của mọi trang qua một hàm duy nhất, pageMetadata, để không trang nào quên điều gì.
Cái bẫy thứ hai nằm ở địa chỉ chuẩn (canonical). Nếu một bài có thể truy cập bằng nhiều địa chỉ (có hay không có dấu gạch chéo cuối, có tham số theo dõi, hay bản tiếng Anh cạnh bản tiếng Việt), Google cần biết địa chỉ nào là bản chính. Bạn khai báo bằng một thẻ <link rel="canonical">, và Google giải thích lý do ở đây. Với bài có bản dịch, mỗi bản trỏ canonical về chính nó và liệt kê các bản kia bằng hreflang, như hướng dẫn về phiên bản địa phương hóa của Google mô tả.
Để thấy thứ này trông ra sao, mình viết hàm dựng phần <head>, và một bộ kiểm tra nhỏ chấm điểm nó. Hàm dựng <head> nhận thông tin một trang và trả về chuỗi HTML. Chú ý nó escape mọi giá trị đưa vào thuộc tính, vì tiêu đề có dấu ngoặc kép sẽ làm hỏng cả thẻ:
// Dựng phần <head> của một trang bài viết: thứ mà metadata của Next.js (generateMetadata) cuối cùng cũng tạo ra.
import { serializeJsonLd } from "./ld.ts";
import { escapeXml as escapeHtml } from "./sitemap-xml.ts";
export type ThongTinTrang = {
title?: string;
description?: string;
canonical?: string;
languages?: Record<string, string>;
noindex?: boolean;
jsonLd?: object;
};
export function renderHead(page: ThongTinTrang): string {
const lines: string[] = ['<meta charset="utf-8" />'];
if (page.title) lines.push(`<title>${escapeHtml(page.title)}</title>`, `<meta property="og:title" content="${escapeHtml(page.title)}" />`);
if (page.description) lines.push(`<meta name="description" content="${escapeHtml(page.description)}" />`, `<meta property="og:description" content="${escapeHtml(page.description)}" />`);
if (page.canonical) lines.push(`<link rel="canonical" href="${escapeHtml(page.canonical)}" />`);
for (const [hreflang, href] of Object.entries(page.languages ?? {})) lines.push(`<link rel="alternate" hreflang="${escapeHtml(hreflang)}" href="${escapeHtml(href)}" />`);
if (page.noindex) lines.push('<meta name="robots" content="noindex" />');
if (page.jsonLd) lines.push(`<script type="application/ld+json">${serializeJsonLd(page.jsonLd)}</script>`);
return lines.join("\n");
}Hai hàm bổ trợ, escapeXml và serializeJsonLd, nằm trong hai file dưới. Bạn sẽ thấy chúng ở các mục sau. Cái chấm điểm thì dùng biểu thức chính quy cho gọn. Mình ghi rõ trong file rằng nó đủ cho phần head do chính mình dựng, nhưng không dùng được để đọc HTML bất kỳ trên mạng:
// Kiểm tra nhanh phần <head> của một trang. Dùng biểu thức chính quy cho gọn: đủ cho phần head do chính mình dựng,
// không dùng được để đọc HTML bất kỳ trên mạng (muốn vậy hãy dùng bộ phân tích HTML thật).
export type KetQua = { dau: "✓" | "✗"; noiDung: string };
const lay = (html: string, mau: RegExp) => html.match(mau)?.[1];
export function kiemSeo(head: string): KetQua[] {
const kq: KetQua[] = [];
const ghi = (dat: boolean, noiDung: string) => kq.push({ dau: dat ? "✓" : "✗", noiDung });
const title = lay(head, /<title>([^<]*)<\/title>/);
ghi(title !== undefined && title.length >= 30 && title.length <= 65, title === undefined ? "Thiếu thẻ <title>" : `Tiêu đề ${title.length} ký tự (nên 30–65)`);
const mota = lay(head, /<meta name="description" content="([^"]*)"/);
ghi(mota !== undefined && mota.length >= 120 && mota.length <= 160, mota === undefined ? "Thiếu meta description" : `Mô tả ${mota.length} ký tự (nên 120–160)`);
const canonical = head.match(/<link rel="canonical" href="([^"]*)"/g) ?? [];
ghi(canonical.length === 1 && /href="https?:\/\//.test(canonical[0]), canonical.length === 0 ? "Thiếu canonical" : canonical.length > 1 ? "Có hơn một canonical" : "Có đúng một canonical, là URL đầy đủ");
const hreflang = head.match(/<link rel="alternate" hreflang=/g) ?? [];
ghi(hreflang.length === 0 || hreflang.length >= 2, hreflang.length === 1 ? "Chỉ có một hreflang: cần ít nhất hai (hoặc không có)" : `hreflang: ${hreflang.length} liên kết`);
const ld = [...head.matchAll(/<script type="application\/ld\+json">([\s\S]*?)<\/script>/g)];
if (ld.length === 0) ghi(false, "Thiếu dữ liệu có cấu trúc JSON-LD");
for (const [, noiDung] of ld) {
try {
const du = JSON.parse(noiDung);
ghi(typeof du["@type"] === "string", `JSON-LD hợp lệ, @type = ${du["@type"]}`);
} catch {
ghi(false, "JSON-LD không đọc được (không phải JSON hợp lệ)");
}
}
ghi(!/<meta name="robots" content="[^"]*noindex/.test(head), /noindex/.test(head) ? "Trang đang noindex: Google sẽ không đưa vào kết quả" : "Không noindex");
return kq;
}Các ngưỡng 30 đến 65 ký tự cho tiêu đề và 120 đến 160 cho mô tả là quy ước mình đặt để chúng không bị cắt trên trang kết quả. Không có con số chính thức nào từ Google ở đây.
Sơ đồ trang: và vì sao sitemap của blog này từng không cập nhật
Sơ đồ trang là một file XML liệt kê địa chỉ các trang. Hướng dẫn của Google (mình đọc ngày 12/11/2026) nêu mấy điều đáng nhớ. Mọi giá trị trong file phải được escape ký tự đặc biệt của XML. Google bỏ qua <priority> và <changefreq>. Nó chỉ dùng <lastmod> khi giá trị đó luôn khớp với lần sửa trang thật. Và một file chỉ chứa tối đa 50.000 địa chỉ hoặc 50 MB chưa nén. Vì vậy bản của mình chỉ có <loc>, <lastmod> và các liên kết ngôn ngữ, bỏ hai thẻ bị bỏ qua:
// Sơ đồ trang (sitemap) dạng XML: mỗi trang một <url>, kèm bản ngôn ngữ khác (hreflang) và ngày sửa lần cuối.
export type MucSitemap = { url: string; lastModified?: string; languages?: Record<string, string> };
// Mọi giá trị trong XML phải được escape; một dấu & trong URL mà không escape làm hỏng cả tệp.
export function escapeXml(value: string): string {
return value.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, """).replace(/'/g, "'");
}
export function buildSitemapXml(entries: MucSitemap[]): string {
const urls = entries.map((entry) => {
const lines = ["<url>", `<loc>${escapeXml(entry.url)}</loc>`];
for (const [hreflang, href] of Object.entries(entry.languages ?? {})) {
lines.push(`<xhtml:link rel="alternate" hreflang="${escapeXml(hreflang)}" href="${escapeXml(href)}" />`);
}
if (entry.lastModified) lines.push(`<lastmod>${escapeXml(entry.lastModified)}</lastmod>`);
lines.push("</url>");
return lines.join("\n");
});
return [
'<?xml version="1.0" encoding="UTF-8"?>',
'<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">',
...urls,
"</urlset>",
"",
].join("\n");
}Hàm escapeXml là lý do một địa chỉ có dấu & không làm hỏng cả file. Mình viết một test cho nó trong bộ test ở cuối bài.
Giờ đến chuyện thật của blog này, vì nó cho thấy sơ đồ trang cũng có thể sai theo cách bạn không ngờ. Lúc đầu blog dùng cách Next.js chuẩn: một file app/sitemap.ts. Trên Vercel, bản nó phục vụ là bản dựng lúc deploy, và nó bỏ qua revalidate = 3600. Hậu quả là các bài đăng sau đó không có trong /sitemap.xml cho tới lần deploy kế tiếp, trong khi rss.xml, một route handler thường với cùng cấu hình, vẫn cập nhật bình thường. Đó là nội dung commit 7a06c11 ngày 10/11/2026 của dự án. Cách sửa đầu tiên là chuyển sitemap sang một route handler tại app/sitemap.xml/route.ts.
Nhưng nó vẫn không cập nhật. Commit 00d85b6 cùng ngày giải thích: Next.js coi mọi route đặt ở /sitemap.xml là route metadata, bất kể file được viết theo kiểu nào, nên trên production nó vẫn được phục vụ như một file tĩnh. Cách sửa cuối cùng là phục vụ handler ở một địa chỉ khác, /sitemap-all.xml, rồi dùng rewrites trong next.config.ts để địa chỉ công khai /sitemap.xml (cái đã nằm trong robots.txt và Search Console) vẫn giữ nguyên:
// The sitemap lives at /sitemap-all.xml (see that route) and keeps its public address.
async rewrites() {
return [{ source: "/sitemap.xml", destination: SITEMAP_ROUTE }];
},Bài học mình rút ra: một lỗi như vậy không hiện ra khi chạy thử trên máy, vì chỉ xảy ra trên Vercel sau khi có bài mới. Nên mình viết một test để nó không quay lại. Test kiểm tra hai điều: địa chỉ công khai được rewrite sang địa chỉ không phải route metadata, và không còn file nào ở đúng đường dẫn /sitemap.xml. Với sơ đồ trang, theo mình cái đáng kiểm nhất không phải là nội dung file, mà là việc nó có thật sự thay đổi sau khi đăng bài trên môi trường thật.
JSON-LD: nói cho máy biết đây là một bài viết
JSON-LD là một khối JSON mô tả trang theo từ vựng của schema.org. Hướng dẫn JSON-LD của Next.js khuyên đặt nó trong một thẻ <script type="application/ld+json"> ở layout hoặc page. Với bài viết, kiểu thích hợp là BlogPosting, và các trường mình dùng là tiêu đề, mô tả, ngày đăng, ngày sửa, từ khóa, tác giả và nơi xuất bản. Tài liệu của Google về dữ liệu có cấu trúc cho bài viết mô tả những trường được dùng.
// JSON-LD (schema.org) cho một bài viết: các hàm thuần trả về đối tượng, để test được. Cùng ý với src/lib/structured-data.ts của blog Tech Notes.
/** Chuỗi để đặt trong <script type="application/ld+json">. Thay "<" bằng < để nội dung không bao giờ đóng được thẻ script. */
export function serializeJsonLd(data: object): string {
return JSON.stringify(data).replace(/</g, "\\u003c");
}
export type Crumb = { name: string; url: string };
export function breadcrumbLd(crumbs: Crumb[]) {
return {
"@context": "https://schema.org",
"@type": "BreadcrumbList",
itemListElement: crumbs.map((crumb, index) => ({ "@type": "ListItem", position: index + 1, name: crumb.name, item: crumb.url })),
};
}
export type BaiViet = {
title: string;
description: string;
url: string;
publishedAt: string;
updatedAt?: string;
tags: string[];
authorName: string;
siteName: string;
siteUrl: string;
};
export function blogPostingLd(post: BaiViet) {
return {
"@context": "https://schema.org",
"@type": "BlogPosting",
headline: post.title,
description: post.description,
datePublished: post.publishedAt,
dateModified: post.updatedAt ?? post.publishedAt,
inLanguage: "vi",
keywords: post.tags.join(", "),
mainEntityOfPage: { "@type": "WebPage", "@id": post.url },
url: post.url,
author: { "@type": "Person", name: post.authorName },
publisher: { "@type": "Organization", name: post.siteName, url: post.siteUrl },
};
}Hàm serializeJsonLd là chỗ mình muốn bạn dừng lại. Nó gọi JSON.stringify rồi thay mọi ký tự < bằng <. Tài liệu của Next.js cũng dặn đúng điều này: JSON.stringify không làm sạch chuỗi nguy hiểm, nên bạn nên thay < bằng dạng Unicode của nó. Lý do giống hệt chuyện Markdown ở bài về trình soạn bài an toàn: tiêu đề bài viết là dữ liệu do người viết nhập, và nếu nó chứa </script> thì thẻ script bị đóng sớm và phần phía sau chạy như HTML thường. Mình thử điều đó trong script dưới đây, cùng với việc chấm hai trang và in sơ đồ trang:
// Chạy: node thu.ts. Dựng head của một bài viết theo hai cách rồi chấm điểm; thử sơ đồ trang; thử JSON-LD khi tiêu đề chứa mã độc.
import { renderHead } from "./src/head.ts";
import { kiemSeo } from "./src/kiem-seo.ts";
import { blogPostingLd, serializeJsonLd } from "./src/ld.ts";
import { buildSitemapXml } from "./src/sitemap-xml.ts";
const SITE = "https://blog.example.com";
const bai = {
title: "Nén ảnh trước khi upload: từ 8,7 MB xuống 440 KB cho blog",
description: "Nén ảnh trước khi upload cho blog Next.js: thu nhỏ còn 1600 px, đổi sang WebP, bỏ EXIF và GPS. Có số đo thật, bẫy ảnh dọc bị nằm ngang.",
url: `${SITE}/bai-viet/nen-anh-truoc-khi-upload`,
publishedAt: "2026-11-15T08:00:00+07:00",
tags: ["Next.js", "ảnh", "WebP"],
authorName: "Tác giả",
siteName: "Blog mẫu",
siteUrl: SITE,
};
const BAN_EN = `${SITE}/en/posts/compress-images-before-upload`;
const inKetQua = (ten: string, head: string) => {
console.log(`--- ${ten}`);
for (const muc of kiemSeo(head)) console.log(`${muc.dau} ${muc.noiDung}`);
};
// Cách 1: chỉ có tiêu đề, như một trang vừa tạo xong chưa ai nghĩ tới SEO.
inKetQua("Trang chỉ có tiêu đề", renderHead({ title: "Bài viết" }));
// Cách 2: đủ metadata và JSON-LD, như generateMetadata cộng với thẻ <script> JSON-LD tạo ra.
inKetQua("Trang đủ metadata và JSON-LD", renderHead({
title: bai.title,
description: bai.description,
canonical: bai.url,
languages: { vi: bai.url, en: BAN_EN, "x-default": bai.url },
jsonLd: blogPostingLd(bai),
}));
console.log("\n--- Sơ đồ trang");
console.log(buildSitemapXml([
{ url: bai.url, lastModified: bai.publishedAt, languages: { vi: bai.url, en: BAN_EN } },
{ url: `${SITE}/chu-de/web-thuc-chien` },
]));
// Tiêu đề do người viết đặt: nếu chứa </script>, serialize ngây thơ cho phép thoát khỏi thẻ.
console.log("--- JSON-LD khi tiêu đề chứa mã độc");
const doc = blogPostingLd({ ...bai, title: 'Bài </script><script>alert("xss")</script>' });
const ngayTho = `<script type="application/ld+json">${JSON.stringify(doc)}</script>`;
const antoan = `<script type="application/ld+json">${serializeJsonLd(doc)}</script>`;
const demThe = (html: string) => (html.match(/<script/g) ?? []).length;
console.log(`JSON.stringify thẳng: ${demThe(ngayTho)} thẻ <script> trong kết quả`);
console.log(`serializeJsonLd: ${demThe(antoan)} thẻ <script> trong kết quả`);node thu.ts--- Trang chỉ có tiêu đề
✗ Tiêu đề 8 ký tự (nên 30–65)
✗ Thiếu meta description
✗ Thiếu canonical
✓ hreflang: 0 liên kết
✗ Thiếu dữ liệu có cấu trúc JSON-LD
✓ Không noindex
--- Trang đủ metadata và JSON-LD
✓ Tiêu đề 57 ký tự (nên 30–65)
✓ Mô tả 135 ký tự (nên 120–160)
✓ Có đúng một canonical, là URL đầy đủ
✓ hreflang: 3 liên kết
✓ JSON-LD hợp lệ, @type = BlogPosting
✓ Không noindex
--- Sơ đồ trang
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
<url>
<loc>https://blog.example.com/bai-viet/nen-anh-truoc-khi-upload</loc>
<xhtml:link rel="alternate" hreflang="vi" href="https://blog.example.com/bai-viet/nen-anh-truoc-khi-upload" />
<xhtml:link rel="alternate" hreflang="en" href="https://blog.example.com/en/posts/compress-images-before-upload" />
<lastmod>2026-11-15T08:00:00+07:00</lastmod>
</url>
<url>
<loc>https://blog.example.com/chu-de/web-thuc-chien</loc>
</url>
</urlset>
--- JSON-LD khi tiêu đề chứa mã độc
JSON.stringify thẳng: 2 thẻ <script> trong kết quả
serializeJsonLd: 1 thẻ <script> trong kết quảPhần đầu cho thấy một trang vừa tạo (chỉ có tiêu đề "Bài viết") trượt gần mọi mục: tiêu đề quá ngắn, thiếu mô tả, canonical và JSON-LD. Phần hai là cùng loại trang với đủ thông tin, đạt hết. Dòng hreflang: 0 liên kết ở trang đầu được tính là đạt vì một trang không có bản dịch thì không cần hreflang, và cái chấm điểm chỉ báo khi có đúng một liên kết, vì hreflang cần ít nhất hai bản để có nghĩa. Phần sơ đồ trang là file XML hợp lệ với một bài có bản tiếng Anh và một trang chủ đề. Phần cuối là kết quả quan trọng nhất: với tiêu đề chứa </script><script>alert("xss")</script>, cách ngây thơ cho ra hai thẻ <script> trong HTML (thẻ thứ hai là mã của kẻ tấn công), còn serializeJsonLd chỉ cho một. Địa chỉ blog.example.com và bài mẫu là minh họa.
Sau khi triển khai thật, bạn kiểm tra JSON-LD bằng công cụ của chính Google: Rich Results Test, hoặc Schema Markup Validator (cả hai được tài liệu Next.js nhắc tới). Cái chấm điểm của mình chỉ kiểm tra JSON hợp lệ và có @type. Nó không thay được hai công cụ đó.
Bản xem trước không được phép bị index
Còn một chuyện nhỏ mà hậu quả lớn. Mỗi pull request của blog này có một bản xem trước trên Vercel với địa chỉ riêng. Nếu Google index chúng, bạn sẽ có nhiều bản sao của cùng một bài trên những địa chỉ kỳ lạ, và nội dung nháp có thể lộ ra kết quả tìm kiếm. Vì vậy quy ước của dự án (viết trong AGENTS.md) là bản xem trước phải noindex, và chỉ bản production mới được index. Code làm điều đó rất ngắn. Hàm isIndexable trong src/lib/site.ts chỉ trả true khi biến môi trường VERCEL_ENV bằng production, và robots.ts dùng nó để chọn luật:
export default function robots(): MetadataRoute.Robots {
if (!isIndexable()) {
return { rules: { userAgent: "*", disallow: "/" } };
}
return {
rules: { userAgent: "*", allow: "/", disallow: "/tim-kiem" },
sitemap: absoluteUrl("/sitemap.xml"),
};
}Test của nó kiểm tra một điều đáng giá: chỉ giá trị production mới cho phép index, còn preview, development và chuỗi rỗng đều bị chặn. Mặc định an toàn ở đây là "không index", và mình phải chủ động bật nó cho production, thay vì mặc định index rồi nhớ tắt cho bản xem trước. Quên bật thì trang chưa lên Google, còn quên tắt thì nội dung nháp lộ ra, nên mình chọn lỗi dễ sửa hơn.
Test cho các hàm SEO
Tám test cho các hàm trong bài nằm ở repo demo (escape XML và JSON-LD, dateModified mặc định, vị trí breadcrumb, sơ đồ trang có &, hreflang đơn lẻ và noindex bị báo, JSON-LD hỏng bị báo). Chúng chạy bằng bộ test sẵn có của Node, không cần cài gì:
node --test src/seo.test.ts# tests 8
# pass 8
# fail 0Bạn có thể tự viết lại chúng từ các quy tắc ở trên, vì hàm nào cũng nhỏ.
Chia sẻ lên Facebook thì sao?
Đến đây Google có đủ thứ để hiểu và tìm thấy các bài viết. Nhưng còn một nơi nữa người ta tìm thấy bài của bạn: khi ai đó dán đường dẫn vào Facebook, Zalo hay Slack. Lúc đó ứng dụng không hiện kết quả tìm kiếm mà hiện một thẻ xem trước, và thẻ xem trước cần một tấm ảnh. Làm ảnh chia sẻ cho từng bài mà không phải thiết kế thủ công là việc của các bài viết sau.
Bạn theo dõi cả series ở Xây blog với Next.js + Supabase. Nếu đang ôn phỏng vấn, các câu hỏi về Next.js, React và bảo mật có trong ngân hàng câu hỏi phỏng vấn.