元数据不是「再塞一个 head 组件」——是路由级产品契约
App Router 把 SEO 元数据收进一等 API 之后，团队仍常踩三类坑：根布局写死一个 title，子路由全站撞车；CMS 有字段但 generateMetadata 忘记 await 或抛错回落默认；中英路由各写一套字符串，hreflang 与 canonical 互相矛盾。Next.js Metadata API 实战模式要解决的不是语法罗列，而是代理商与企业官网上线时真正会炸的契约：默认值从哪来、动态页如何失败安全、社交卡片与搜索标题是否同源、预览环境如何不污染索引。可上线在交付 Next 营销站与产品壳（含制造品牌站、机构信任站、双语服务站）时，把 Metadata 当作「路由的对外接口」写进开发规范与 PR 检查。下文按 2026 仍稳妥的模式拆开：metadataBase、模板、静态与动态、规范与多语言、OG/Twitter、CMS 管线、观测与门禁。
metadataBase 与绝对 URL：先定站的「地址原点」
所有 OG 图、canonical、alternates 若写成相对路径，最终解析依赖 metadataBase。生产环境应指向正式站点源（含 https），预览与本地用环境变量覆盖，避免卡片指向 localhost 或错误部署域。常见事故：Vercel 预览 URL 进了 sitemap 或 OG，被当正式页分享。模式：`metadataBase: new URL(process.env.NEXT_PUBLIC_SITE_URL)`，并在 CI 校验该变量在 production 必填。子域多品牌时，每个品牌应用自己的 base，不要共用一个根导致卡片串站。
title 模板：默认后缀、分段覆盖与禁止重复品牌名
根布局使用 `title: { default, template: '%s｜可上线' }` 一类模板，子路由只提供分段标题。禁止在子路由再手写完整「标题｜品牌」导致双重后缀。中英模板后缀本地化（｜ vs |，品牌译名是否出现）。长度按搜索展示约 50–60 字符心智预算裁剪，关键词靠前，品牌靠后。服务页与洞察页可用不同 template 分层（例如布局分组），但不要超过两层心智模型，否则编辑不知道改哪。
静态 metadata 与 generateMetadata：何时用哪一个
固定营销页（首页、服务总览、联系）用导出 `metadata` 对象，简单可审。CMS 驱动的洞察、案例、产品详情用 `generateMetadata`，在函数内拉取与页面相同的数据源，保证 title/description 与正文同源。失败策略写死：内容 404 则 `notFound()`，元数据也不要「成功返回默认首页 title」。列表分页把页码编进 title 仅当该页被索引；否则 noindex 且可用简单 title。生成时避免 N+1：与页面 query 合并缓存（`fetch` cache / React cache），防止元数据请求把 TTFB 打爆。
canonical、robots 与索引控制：元数据层的安全阀
每个可索引页声明 `alternates.canonical` 指向权威 URL（含 locale 前缀规则）。搜索页、过滤参数、预览、草稿、感谢页：`robots: { index: false, follow: false }` 或更细粒度。注意 metadata 的 robots 与 HTTP 头、中间件改写不要互相打架。分页与排序参数页默认 noindex，除非有明确 SEO 价值与独特正文。代理商站常见漏洞：客户端路由切换后看起来像新页，但 canonical 仍指父级——用路由级 generateMetadata 按 slug 生成，而不是布局一层写死。
多语言：alternates.languages 与真实路由一致
中文主站 + `/en` 是可上线常见结构：每个 locale 页输出 `alternates.languages`（含 `x-default` 策略）指向真实可 200 的 URL。缺失译稿时不要指到空壳——要么不输出该语言，要么指到回退页并在内容层标明。`generateMetadata` 必须读当前 locale 参数，描述与 OG locale 同步。hreflang 与 canonical 规则写进文档：例如中文根为权威中文，英文为 `/en/...`，禁止两边互相 canonical 到同一 URL。构建时可用集成测试抓几个样例页的 head 断言。
Open Graph 与 Twitter 卡片：同源字段，尺寸与降级
og:title / description 默认与 SEO title/description 同源，需要「更适合社交的短句」时在 CMS 单列 socialTitle，而不是在代码里截断出乱码。OG 图：固定比例（如 1200×630）、每文可覆写、缺省用品牌默认图；动态 OG 图（ImageResponse）要控制边缘运行时成本与字体子集。Twitter 卡片类型与 OG 对齐，避免只测微信/iMessage 一种预览。上线检查：用调试工具拉正式 URL，确认不是预览域、不是 HTTP、不是缺图。
与 CMS / 内容管线对齐：字段字典比组件更重要
编辑需要知道：seoTitle、seoDescription、ogImage、noIndex、canonicalOverride 各管什么、字符预算多少、空值如何回落（H1 → title → 站点 default）。校验在发布前做：描述长度、禁发词、缺图。洞察目录式站点（JSON 或 headless）应在合并脚本或 CMS webhook 后保证 metadata 字段完整，而不是运行时猜。可上线内容流水线是 drafts → validate → catalog；Metadata 的缺字段应在 validate 失败，而不是线上长出「Untitled」。
验收与协作：PR 检查、抽样抓取、上线后 GSC
PR 模板勾选：本路由是否新增/修改 metadata、canonical 是否正确、预览是否 noindex。CI 可对关键 path 做 head 快照对比。上线后 Search Console 看标题改写与索引；重大模板变更分批放量。设计不要在视觉稿里「画」浏览器标题——用真实字段表。需要可上线介入时，我们从路由表 + 字段字典 + 两个坏例 URL 开始修，而不是先重画首页。hi@keshangxian.com（上海）。
可执行清单
- 1production 的 metadataBase / SITE_URL 已固定为 https 正式域，预览域不进索引
- 2title 使用模板且子路由无双重品牌后缀；中英后缀已本地化
- 3CMS/动态页 generateMetadata 与正文同源，404 不回落错误 title
- 4canonical、robots、hreflang/languages 与真实路由表一致并可被测试断言
- 5OG 图尺寸与缺省图就绪；发布前字段校验（长度、noIndex、覆写）已接通
核心要点
- Metadata API 是路由对外契约：base、模板、失败策略比「会写 metadata 对象」更重要。
- 动态页必须与正文同源生成元数据，并明确 404/noindex，避免静默回落污染 SERP。
- 多语言与 OG 的正确性来自字段字典 + 测试，而不是上线后人工扫分享链接。
常见问题
- 还要不要用 next/head？
- App Router 项目以 Metadata API 为准；残留 Pages 路由才考虑 next/head。混用两套容易造成重复 title 与难以调试的覆盖顺序。
- generateMetadata 会拖慢 TTFB 吗？
- 会，如果额外打无缓存的远程请求。与页面数据共享 cache、减少瀑布、必要时静态生成可索引页，是正道。
- 客户端组件里能否改 metadata？
- SEO 关键元数据应在服务器 Metadata API 产出。客户端再改 title 对爬虫不可靠，只适合纯应用内 UI 状态，不适合营销收录页。