@cogita/plugin-seo 在构建阶段为首页、文章页和其他已生成路由注入页面级 SEO 元数据,补齐站点地图之后的页面描述和社交分享能力。
第一期不增加客户端运行时组件,不修改文章正文渲染,只生成静态 HTML 的 head 标签。
没有 seo 配置时插件返回 null,不会改变已有 HTML。启用后,Rspress 原来的静态 description 由插件替换为页面级 description。
文章可以使用嵌套的 seo frontmatter 覆盖默认元数据:
文章已有的 title、description、excerpt、image、imageAlt、author 字段仍然有效。覆盖优先级为:seo 嵌套字段 → 文章普通字段 → 站点级默认值。
Rspress 1.45 提供了 config.head 的路由回调能力,因此插件可以按页面生成标签,不需要修改 HTML 文件,也不依赖运行时虚拟模块。
审核工具复用插件在 config 钩子中收集的文章元数据,构造首页和文章页的审核页面集合,检查以下规则:
imageAlt;审核默认只输出报告,不阻断构建。设置 audit.failOnError: true 后,缺少标题、描述或 canonical 会让构建失败。设置 audit.reportPath 后,报告会以 JSON 写入构建输出目录,便于 CI 或后续工具继续处理。
SEO 审核报告遵循统一质量报告 schema,除兼容保留的 pageCount 外,还包含 reportType: "seo-audit" 和通用的 itemCount、errors、warnings、issues 字段。它可以和 content-report.json 一起交给 scripts/check-quality-reports.mjs,由同一个门禁统计总错误和警告,并在 GitHub Actions 中生成逐条 annotation。
文章页包含:
description 和 robotscanonical、og:urlog:type、og:title、og:description、og:imagetwitter:card、twitter:title、twitter:description、twitter:imageauthor首页使用 WebSite JSON-LD,其他页面使用站点默认元数据。site.base 会参与绝对 URL 计算,外部图片地址不会被重复拼接。
SEO 插件通过 config 钩子注册页面 head,通过 beforeBuild 使用 core 提供的 ContentIndex 生成页面元数据;这样索引失效发生在 SEO 重新读取文章之前,不依赖 posts 插件的执行顺序。旧版 core 或插件单独使用时仍保留独立扫描兜底。
搜索功能暂不在 SEO 插件中重复实现:Rspress 已经生成本地搜索索引和搜索入口,未来只需在现有索引上扩展标签、合集和搜索权重。