给 Next.js 16 博客做 SEO:代码不报错,结果全是错的

metadataBase 拼出 https://undefined、调了 notFound() 状态码还是 200、JSON-LD 里一个标题让浏览器弹窗、分享卡片发布后一直 404。七个 SEO 练习里,最难查的问题都不报错,只能靠看最终输出发现。

2026-10-10

这个博客用 Next.js 16.3 App Router 搭建,开了 Cache Components,文章存在 Postgres 里。上一阶段把文章页做成了静态页,这一阶段补 SEO:metadata、canonical、sitemap、robots、结构化数据、分享卡片图,最后绑域名上线验证。

做完回头看,SEO 代码本身都不难,几行配置而已。难的是它们写错了不报错:类型检查通过,pnpm build 通过,页面正常打开,只有去看 <head> 里的最终输出、看 HTTP 状态码、看缓存文件,才知道结果是错的。

这篇按做的顺序,记下每一步的关键知识点和最有代表性的问题。

一、metadataBase:合法的 URL,错误的地址

canonical、og:image 这些字段,规范要求是完整 URL。Next.js 的做法是在根 layout 配一个 metadataBase 作为前缀,各页面只写 /posts/xxx ,由框架拼成完整地址。没配却写了相对路径,build 会直接报错。

这个值不能写死。预览部署、*.vercel.app 地址、正式域名都能访问同一个站点,而 canonical 的意思是「正版在这里」,必须永远指向生产域名。Vercel 提供了系统变量 VERCEL_PROJECT_PRODUCTION_URL ,文档原话是:

We select the shortest production custom domain, or vercel.app domain if no custom domain is available. Note, that this is always set, even in preview deployments.

预览部署里它也指向生产域名,正好合适。不用 VERCEL_URL ,因为那是每次部署各自的临时地址。

问题出在本地。本地没有这个变量,第一版代码拼出来的是:

https://undefined/

new URL('https://undefined') 是合法 URL,不报错。metadataBase 的类型又允许 string ,tsc 也发现不了。补上兜底后,第二版写成了 'http://localhost:300' ,少了一个 0,同样合法,同样不报错。

两次都是临时给某个页面加一行 canonical、curl 看实际输出才发现的。这是整个阶段的第一条教训:值错了不报错的配置,验收必须看最终输出。

顺带两个小点:

  • title.template 只作用于子路由段。首页和根 layout 在同一个段,用不上 template,所以 default 必须写。
  • <html lang="cn"> 不合法。BCP 47 标签第一段是语言(zh ),第二段才是地区(CN ),应该写 zh-CN 。

二、generateMetadata:没写的字段,有人替你写了

文章页的 title、description 来自数据库,用 generateMetadata 。它和页面组件都要查同一篇文章,会不会查两次库?不会:两处都调用带 'use cache' 的 getPostBySlug ,同一个 slug 命中同一条缓存。

两个出乎意料的行为,都是读 Next 源码 resolve-metadata.js 确认的:

1. og:title 不用写。 我只返回了顶层的 title 和 description ,openGraph 里只写了 type 和 url ,head 里却有完整的 og:title 、og:description 、twitter:title ,值和 <title> 一模一样,连 template 加的站点名后缀都在。源码里的注释写得很直白:

// If there's no title and description configured in openGraph or twitter,
// use the title and description from metadata.
inheritFromMetadata(openGraph, metadata);
inheritFromMetadata(twitter, metadata);

所以手动在 openGraph.title 里再拼一遍站点名,反而是多余的:改站点名要改两处。

2. 返回 undefined 不等于「不写」。 我以为文章没有摘要时返回 description: undefined ,就会沿用根 layout 的站点描述。实际不会。合并逻辑遍历的是返回对象上存在的 key,description 这个 key 在,值是 null 还是 undefined 都会被解析成 null ,把父级覆盖掉。想继承只能不写这个 key。

百度为什么要单独关心

国内做 SSR/SSG 常被提到的理由是:百度爬虫执行 JS 的能力远弱于 Google。Next.js 对此有专门处理,我实测了一次。

请求时才渲染的页面,Next 会先发 UI,再把 metadata 流式追加进 <body> 。但对一份内置的「HTML-limited bots」名单(含 baiduspider 、sogou 、Twitterbot 等),它会阻塞渲染,把 metadata 放进 <head> 。

我在构建后插入一篇测试文章(不在预渲染列表里),分别用两种 UA 请求,看 <title> 的字节位置:

页面UA<title> 位置</head> 位置结果
构建后新发布的文章普通 Chrome11504980在 <body>
同上Baiduspider8652089在 <head>
预渲染的文章两种 UA9072452都在 <head> ,字节位置完全相同

预渲染页的 metadata 在构建时就定了,不涉及流式。对国内 SEO 来说,能预渲染就预渲染最稳。

三、真 404:做不到,于是接受软 404

不存在的文章,页面里调了 notFound() ,状态码却是 200,只在页面里补了一行 <meta name="robots" content="noindex"> 。

原因是 HTTP 的约束:响应头(含状态码)只能发一次。流式渲染一开始送 body,头就已经发出去了。notFound() 在 Suspense 里面触发时,200 已经发出,改不回来。

官方文档给的真 404 写法,是在 Suspense 之外先做存在性检查。我照做了,结果:

  • build 没报错,状态码还是 200。
  • 产物里这条路由的 App Shell 变成了 0 字节的空壳。Next 16.3 对 generateStaticParams 没列出的参数,第一次访问会先送 App Shell 和 200,再恢复渲染。检查挪出去了,外壳照样先发。
  • 按 dev 浮层的提示加上 export const instant = false ,提示消失,行为完全不变。文档对这个选项的原话是「This doesn't change how the route renders. It only opts out of validation」。

剩下的路都很贵:在 proxy.ts 里每个请求先查一次库(拖慢所有正常请求),或者放弃 Cache Components。软 404 的实际伤害又有限:有 noindex 不会被收录,sitemap 只列存在的文章。所以我回退了改动,接受 200 + noindex,在代码里注释了原因。

用 Nuxt 对比更好理解:Nuxt 3 默认把整页渲染成字符串再一次性发出,渲染中任何时候都能改状态码,代价是首字节要等整页渲染完。Next 的流式渲染反过来,用 HTTP 语义换首屏速度。

四、sitemap 与 robots:两条反直觉的规则

Next.js 里 app/sitemap.ts 默认导出一个函数,返回数组,框架序列化成 XML。查库函数挂上 cacheTag('posts') 后,发布文章的 Server Action 里已有的 updateTag('posts') 会连带让 sitemap 失效。实测发布后第一次请求 /sitemap.xml 就包含新文章,发布逻辑一行没改。

Google 的文档里有两条规则,和很多教程写法不一样:

lastmod 要准,priority 和 changefreq 不用写。 Google 原文:「Google ignores <priority> and <changefreq> values」,而 <lastmod> 只在「consistently and verifiably accurate」时才采用。Next 官方示例里 lastModified: new Date() 的写法,等于每次构建都声明「全站刚改过」。我用的是文章的 updatedAt 。

Disallow 会让 noindex 失效。 直觉上后台 /admin 应该在 robots.txt 里 Disallow 。但 Google 说 robots.txt「is not a mechanism for keeping a web page out of Google」,而且「For the noindex rule to be effective, the page or resource must not be blocked by a robots.txt file」。被挡住的页面,爬虫看不到它的 noindex ,有外链时 URL 仍可能出现在搜索结果里。所以 /admin 只加 noindex 、不 Disallow ,真正的保护是鉴权。

这一节的代码 review 里,sitemap 曾漏掉文章 URL 的 /posts 前缀,robots 里写成过 /sitmap.xml ,tsc 和 lint 都查不出,是 curl 看产物逐条对出来的。

另外,metadataBase 只管 metadata 字段,管不到 sitemap 和 JSON-LD。站点根地址要抽到 lib/site.ts 共用,否则 layout 和 sitemap 各写一份判断,改一处漏一处。

五、JSON-LD:一个文章标题让浏览器弹了窗

结构化数据用 JSON-LD,写在 <script type="application/ld+json"> 里。metadata API 没有这个字段,官方做法是在页面里直接渲染 <script> ,用 dangerouslySetInnerHTML 输出 JSON.stringify 的结果,并且要把 < 替换成 \u003c 。

为什么要替换?我做了对照实验:发布一篇标题为 </script><script>alert(1)</script> 的测试文章,临时去掉替换,重新 build。页面里的 JSON-LD 变成:

<script type="application/ld+json">{"@context":"https://schema.org","@type":"BlogPosting","headline":"</script><script>alert(1)</script>","datePublished":...}</script>

HTML 解析器在 <script> 里只认一件事:遇到 </script 就结束这个元素,不管它是不是在 JSON 字符串里。于是数据块在 "headline":" 后面就被关掉了,紧跟着的 <script>alert(1)</script> 是一个没写 type 的普通脚本,会执行。打开页面,浏览器弹了 2 次 alert,对应 Article 和面包屑两段 JSON-LD。

替换之后,HTML 里写的是 \u003c/script> ,解析器找不到 </script ,数据块关不掉。而 \u003c 是合法的 JSON 转义,Google 的解析器 JSON.parse 读回来就是原来的 < ,数据没被改。不用 HTML 实体 &lt; ,是因为 <script> 里的实体不会被解码,Google 会读到字面量 &lt; 。

同一个恶意标题也出现在 <h1> 、<title> 、og:title 里,那些地方都没弹窗:JSX 文本插值和 metadata 默认把 < 转成 &lt; 。用 Vue 的话说,{{ }} 是安全的,v-html 不是。XSS 风险集中在 dangerouslySetInnerHTML 这一处。

本站文章只有持管理员 token 的人能写,外部攻击面很小。但这是技术博客,一篇讲 script 标签的文章标题里出现 </script> 很正常,不转义的话,页面会被自己的内容弄坏。

六、分享卡片图:最大的坑在缓存

app/posts/[slug]/opengraph-image.tsx 默认导出一个函数,用 next/og 的 ImageResponse 把 JSX 渲染成 1200×630 的 PNG,Next 自动在 head 里输出 og:image 及宽高、类型、alt,twitter:image 也自动带上。ImageResponse 内部是 Satori 排版成 SVG、再由 Resvg 转成 PNG,不是浏览器,只支持 flexbox 和部分 CSS。

中文字体:失败不报错

next/og 只内置了一个拉丁字体。图里出现中文时,它会按实际用到的字,从 Google Fonts 拉取 Noto Sans SC 的子集。读源码发现,拉取失败只是 console.error("Failed to load dynamic font for", ...) ,图照样生成,中文缺字,build 照样成功。所以验收时专门 grep 了 build 和运行日志里的这句话,再打开 PNG 肉眼确认中文完整。

从 ƒ 到 ●:首次请求 10 秒变 7 毫秒

第一版写完,路由表里文章卡片图是 ƒ :要用 params 查库,构建时不知道有哪些 slug,只能请求时现场渲染。实测第一次请求 10 秒(拉字体加渲染)。社交平台抓图等不了这么久。

文章页的 generateStaticParams 写在 page.tsx 里,但它管不到同目录的图片路由,每个路由文件各管各的。给图片路由也导出一份后:

加之前加之后
路由表ƒ● ,构建时生成 PNG
首次请求10 秒7ms,x-nextjs-cache: HIT

第一版图省事,写成了 export { generateStaticParams } from './page' 。能用,但检查产物发现,图片路由的服务端代码里多了 Markdown 解析器 micromark 和代码高亮 shiki 的代码:导入一个模块会执行整个模块,page.tsx 顶部的依赖全被带了进来。最后把 slug 查询抽到 lib/posts.ts ,两个文件各自调用。

notFound() 的 404 被缓存了,而且清不掉

查不到文章时返回什么?一开始我选了 notFound() ,理由是「图片只服务真实文章,404 更诚实」。

验收「发布即更新」时,我按「发布前先请求一次 → 发布 → 再请求」测试,结果发布后图片还是 404,响应头 x-nextjs-cache: HIT 。

加了 generateStaticParams 之后,没预生成的 slug 第一次请求的结果会写进缓存。去 .next 里看缓存文件:

缓存条目状态缓存标签
构建时生成的文章卡片图200含 posts
发布前请求留下的 404404,内容为空无

发布文章时,Server Action 调 updateTag('posts') 清掉所有带 posts 标签的缓存。notFound() 产生的这条 404 没有标签,清不到它。也就是说:**发布前只要有人请求过这张图(爬虫、自己预览、手误),发布后分享卡片就一直是坏的,而且没有任何报错。**这个行为官方文档里没写,是看缓存文件发现的。

改成查不到时返回站点默认卡片后,缓存条目是 200,标签里有 posts 。重测:发布前请求得到默认卡片,发布后第一次请求是 MISS 、现场生成了带新标题的卡片,第二次 HIT 。代价是不存在的链接也能分享出一张站点卡片,卡片上只有站点名,危害很小。

一个小误区:带不带 .png

JSON-LD 的 Article.image 要填卡片图地址。我第一次写成了 /posts/<slug>/opengraph-image.png ,实测 404。代码生成的图片路由地址没有扩展名,.png 是直接放静态图片文件时才有的文件名。以 head 里 og:image 的路径为准,去掉后面的 ?<hash> 即可。

七、上线验证

绑定域名、部署后,做了三项检查:

  • Google Search Console:网域验证、提交 sitemap、对文章页请求编入索引。收录结果要等几天。
  • Rich Results Test:用线上网址测试,「文章」和「路径」(面包屑)各 1 项有效,image 被正确识别。唯一的非严重问题是 author.url 未填,本站暂时没有作者页。
  • 分享卡片:X 的发推框里粘贴链接,大图卡片正常,中文标题完整。微信里直接发链接、从微信内置浏览器「发送给朋友」,两种方式都只显示纯文本链接,没有卡片。

微信这一项,同一个链接在 X 能出卡片,说明问题不在 og:image 本身,而是微信不按 Open Graph 生成卡片。我查到的方向是微信需要通过 JS-SDK 配合公众号设置分享内容,但这次没能打开官方文档核对,暂不下结论。

回头看

把这个阶段的问题放在一起,有一个共同点:它们都过了类型检查和构建。

问题怎么发现的
https://undefined 、localhost:300curl 看 canonical 的实际输出
notFound() 状态码仍是 200看 HTTP 状态码和产物字节数
sitemap 地址拼写错误curl 看 sitemap 内容
</script> 关掉 JSON-LD对照实验,浏览器弹窗
卡片图地址多了 .png请求那个地址,404
404 缓存清不掉「先请求、再发布、再请求」,看缓存文件

SEO 的产物是给机器读的:给爬虫、给社交平台的抓取器。它们读错了不会报错,只会安静地不收录、不显示卡片。所以验收不能停在「代码跑通」,要站在读取方的位置,看它实际拿到了什么。

AI 只依据本文内容回答,可能出错,请以原文为准。