国际化 SEO 与结构化数据

APay 会为构建启用的前台语言在服务端渲染 SEO 元数据:英文(en)、简体中文(zh)、香港繁体中文(zh-HK)和俄语(ru)。部署可通过 APAY_LOCALES 只构建其中一部分。

可信站点 URL

单域名部署必须在“设置 → 站点 URL”(site_url)填写绝对 HTTP 或 HTTPS Origin,例如 https://store.example.com。带路径、查询参数、片段、用户信息或非 HTTP 协议的值都无效。APay 不会根据任意请求 Host 猜测公网地址。

启用 APAY_DOMAIN_LOCALES 后,当前 Host 必须精确命中构建期 allowlist。位于反向代理之后时建议设置 APAY_PUBLIC_PROTOCOL=https;代理与缓存要求见域名语言绑定。

无法取得可信 Origin 时,前台 HTML 会安全降级为 noindex,follow,不输出 canonical 和 JSON-LD,/sitemap.xml 返回 HTTP 503。robots.txt 仍可访问,但不会输出 Sitemap 地址。

多语言 URL

默认语言使用无前缀路径,其他构建语言使用语言前缀。以英文为默认语言时,同一商品对应:

  • 英文:/products/example
  • 简体中文:/zh/products/example
  • 香港繁体:/zh-HK/products/example
  • 俄语:/ru/products/example

每个可索引页面只输出一个 canonical,并为真实可达的构建语言输出 hreflang;x-default 指向默认语言的无前缀 URL,同时输出 og:url 和正确的 HTML 语言。查询参数和片段不会产生新的 canonical 页面。

设置 APAY_LOCALE_DOMAINS 后,语言归属域名成为唯一 URL 事实源:简体中文可使用 https://myshopark.com/products/example,英文使用 https://myshopark.com/products/example,俄文使用 https://myshopark.com/ru/products/example。canonical、og:url、JSON-LD 页面地址和双向 hreflang 使用这些归属 URL;x-default 统一指向构建默认语言。每个域名的 sitemap 只包含自己的 <loc>,alternates 可以跨域。配置、重定向排除范围和回滚方法见域名语言绑定。

结构化数据

所有结构化数据在 SSR 中合并为一个 <script type="application/ld+json"> Schema.org @graph:

页面节点
公开前台Organization、WebSite
激活商品详情Product、Offer、BreadcrumbList
激活博客详情BlogPosting、BreadcrumbList
Qingpu 下载页SoftwareApplication、BreadcrumbList
Shoply 应用详情SoftwareApplication、BreadcrumbList
Shoply 主题详情Product、有真实商品时的 Offer、BreadcrumbList

实体页直接提交本次 SSR 已获取的本地化数据。商品 Offer 使用与页面展示及结账相同的 useLocaleCurrency() 换算金额和 ISO 币种。APay 不伪造评分、评论、库存、作者、SKU/GTIN、站内搜索能力或社交账号;缺失的可选事实直接省略。

停用商品和文章返回或保持 404,并从索引中排除。NFT 主题中的模拟商品、人物、发售、库存和 Live 状态统一 noindex,不会输出误导性的 Product schema。

路由策略与 sitemap

app/core/seo.routes.json 和各主题的 seo.routes.json 是索引策略事实源。每个真实页面入口必须且只能分类为公开、私有或重定向;存在未分类页面、重复分类或不存在的清单路径时,SEO 守卫会失败。

Shoply 的 /about 分类为重定向,目标 /page/about 是公开页;旧解决方案路径也分类为重定向,不作为 sitemap 目标。已删除的 /page/case 不再收录,/cases/:slug 分类为公开详情路由。

sitemap 只包含:

  • 当前激活主题及未被抑制的 core 公开路由;
  • 当前可信 Origin;
  • 构建启用语言及 alternates;
  • 激活商品和激活博客;
  • 真实的 Shoply marketplace seed 路由。

文档首页会进入 sitemap;单篇 Nuxt Content 文档仍可通过 SSR 链接与 canonical 被发现,但当前 sitemap 生成器不会主动枚举全部文档路径。

它不会合并所有已打包主题。数据库查询失败或 URL 超过 50,000 条时会明确失败,不返回部分 XML。响应缓存五分钟并允许 stale revalidation;CDN 缓存键必须包含 Host。

私有 /admin、/api、/auth、/user、/payment、/callback、/app 路径会返回 X-Robots-Tag: noindex, nofollow。未知或未登记的前台页面使用 noindex,follow,让爬虫能够读取该指令。robots.txt 只阻断 API,刻意允许爬虫获取私有 HTML,以便读取 noindex 响应头。

生成式引擎优化(GEO)

APay 在宿主底层内置了与传统 SEO 同构的 GEO(Generative Engine Optimization)能力,供 AI 搜索引擎与检索 Agent(OAI-SearchBot、ChatGPT-User、PerplexityBot、Claude-SearchBot、ClaudeBot、Google-Extended、Applebot-Extended 等)直接获取高信噪比结构化事实:

  1. /llms.txt、/llms-full.txt 与 /rss.xml:
    • /llms.txt 按当前激活主题与可信 Origin 动态生成标准 Markdown 索引:包含站点定位、公开核心页面、在售商品(含基础币种价格)、符合域名语言归属的激活博客文章、文档目录,以及主题动态数据源(ThemeSitemapEntry 可选提供 title、description、section、markdown)。
    • /llms-full.txt 在索引基础上附加在售商品、文档(通过 minimarkToMarkdown 将 Nuxt Content Minimark AST 转为纯净 Markdown 并剔除 Shiki 样式)、博客与主题目录的清洗后完整 Markdown 正文语料。
    • /rss.xml 输出已发布博客的标准 RSS 2.0 订阅源;在单域名多语言模式下,/llms.txt、/llms-full.txt 与 /rss.xml 支持 ?locale=<code>(如 ?locale=zh)切换目标语言语料。
    • 所有端点均强制校验 classifySeoRoute(...) === 'public';未配置可信 Origin 时返回 HTTP 503。
  2. 公开内容 Markdown 镜像与内容协商:
    • 公开博客、商品、技术文档,以及任何绑定了主题 seoSources 的动态详情页均支持显式 .md 后缀(/blog/:slug.md、/products/:slug.md、/docs/**.md 与 /:group/:slug.md 及多语言前缀),同时支持通过 Accept: text/markdown 请求头进行内容协商。
    • 响应返回 Content-Type: text/markdown; charset=utf-8、Vary: Accept、canonical 与 llms-txt Link 响应头,以及带 YAML Frontmatter(title、canonical_url、type、locale、price/currency、published_at、updated_at)的纯净 Markdown。
    • 可索引 SSR 页面自动注入 <link rel="llms-txt">、<link rel="alternate" type="application/rss+xml">(当主题开放公开博客路由时),并在支持 Markdown 镜像的详情页注入 <link rel="alternate" type="text/markdown" href="...md">。
    • 若主题抑制或将路由标记为 private(如 nft 主题抑制 /products/**),Markdown 镜像会拒绝暴露并返回 404。
  3. AI 爬虫策略、后台设置与 JSON-LD 扩展:
    • /robots.txt 显式输出主流 AI 检索爬虫规则(可在 后台 → 设置 → SEO 中通过 geo_ai_bots_policy 控制:默认 allow,设为 disallow 时拦截 AI 爬虫),并追加 LLMs-Txt: <origin>/llms.txt 指引。
    • 后台 → 设置 → SEO 同时提供 Google、Bing、百度、Yandex 站长验证 Meta(google_site_verification、bing_site_verification、baidu_site_verification、yandex_site_verification)配置,自动注入公开可索引页面的 <head>。
    • useJsonLd.ts 在 useProductJsonLd、useBlogPostingJsonLd 之外提供 useFaqPageJsonLd(FAQPage)与 useSoftwareApplicationJsonLd(SoftwareApplication),严格遵守不伪造评分或评论数的约束。

站点图标

在 后台 → 设置 → 通用设置 上传站点图标后,点击 保存更改。上传只填写图标 URL,不会保存配置。全站 head 插件统一读取 site_favicon,覆盖所有主题、后台页面与 SSR,并在保存设置后更新当前浏览器标签页。其他已打开的标签页需要刷新以加载新配置。留空使用 /favicon.svg。

每次上传都会生成唯一文件 URL。本地 /uploads/*.ico 响应使用 Content-Type: image/vnd.microsoft.icon,并保留 X-Content-Type-Options: nosniff。

GEO & SEO 增长驾驶舱与高密度引语模型

  1. GEO & SEO 增长驾驶舱(后台 → 系统设置 → SEO)
    • AI 爬虫访问监控(GET /api/admin/settings/seo-telemetry):在数据库查询层直接筛选 OAI-SearchBot、GPTBot、PerplexityBot、ClaudeBot、Google-Extended 等 AI 搜索引擎 User-Agent 以及对 /llms.txt、/llms-full.txt、*.md 镜像的抓取请求(避免被普通访问日志截断),在后台展示 30 天 AI 引擎抓取频次排行与最受 AI 青睐的热门页面。
    • IndexNow 实时收录推送(POST /api/admin/settings/seo-indexnow):支持配置 indexnow_key 与 indexnow_auto_push,系统自动在根路径托管 /<indexnow_key>.txt 校验文件;当商品上架/改价或博客文章发布/更新时,自动异步将 HTML 与 .md 镜像 URL 推送至 IndexNow(Bing / Yandex / Naver),加速 ChatGPT Search 与 Copilot 收录。
    • 单页 GEO/SEO 体检器与 .md 实时预览:在商品编辑(/admin/products/[id])与文章编辑(/admin/posts/[id])右侧栏提供实时 GEO/SEO 评分(0–100 分、A–D 评级)、诊断清单、.md 语料镜像与 JSON-LD 图谱一键预览复制,以及单页 IndexNow 即时推送。
    • 全站主动巡检雷达与一键智能补齐(GET /api/admin/settings/seo-audit、POST /api/admin/settings/seo-autofill):自动扫描全站在售商品与已发布博客,输出主动诊断建议(缺失结构化引语、已被 AI 抓取但未挂载商品的热门文章、0 抓取孤岛页),支持在单页编辑器内或全站批量一键提炼生成 tldr、keySpecs、faqs,并自动建立商品 ↔ 博客双向语义内链(relatedLinks)与多语言翻译层同步。
  2. 面向 AI 引用的高密度内容模型(Citation-Ready Content)
    • 商品与文章的 metaData(及多语言 metaData.translations[locale])标准化支持:
      • tldr:核心结论摘要,作为 .md 镜像与 /llms-full.txt 的首段高亮引语;
      • keySpecs:核心参数键值对,自动渲染为 Markdown 对比表格并注入 Product JSON-LD 的 additionalProperty(PropertyValue);
      • faqs:常见问答对,自动注入 FAQPage JSON-LD 并输出至 .md 镜像末尾;
      • relatedLinks:商品 ↔ 博客/文档双向语义内链,在前台与 .md 语料中同步输出关联链接与价格。
  3. GeoIP 地域智能转化 × 渠道交叉报表
    • /api/payments/info 基于离线 GeoIP(resolveRequestGeo)对可用支付方式进行地域亲和度智能排序(sortPaymentMethodsByGeo),在不改变 Canonical URL 与 currencySnapshot 基础记账快照的前提下,在收银台将最契合当地习惯的支付方式置顶并标记推荐徽章(recommendedByGeo)。
    • 增长驾驶舱统一复用访客统计服务(loadVisitorReport + buildVisitorGeoConversions)输出「国家/地区 × AI 渠道/自然搜索」交叉报表(geoConversions),转化率按去重付款访客计算(paidVisitors / totalVisitors、aiPaidVisitors / aiVisitors、searchPaidVisitors / searchVisitors),收入与客单价按记账币种分桶(revenueByCurrency、aovByCurrency),严禁跨币种直接相加。
  4. MCP Server × 公开发现协议
    • /llms.txt 内置 ## AI Agent & MCP Protocol 章节,向支持工具调用的 AI Agent 声明 /api/mcp(JSON-RPC 2.0 Streamable HTTP)、/.well-known/oauth-protected-resource 与 /.well-known/oauth-authorization-server 授权发现入口。

验证

主题专属动态 Sitemap 数据源通过 theme.host.json 的 seoSources: { "source-name": "server/seo.ts" } 声明。模块导出 getSitemapEntries(source),返回 { path, lastmod? }。构建注册表只包含选中的 前台主题数据源,核心 Sitemap 不直接导入具体主题。数据源缺失或执行失败时返回 HTTP 503,不静默遗漏路由。

构建前运行专项守卫:

npm run check:seo
node --experimental-strip-types scripts/check-domain-locales.mjs
node --experimental-strip-types scripts/check-locale-domains.mjs

部署后应检查 SSR 源码,而不只是客户端 hydration 后的 DOM:确认 canonical、alternates、robots meta 和唯一 JSON-LD 图。逐项探测 /robots.txt、/sitemap.xml、每个配置 Host、每种语言、一个激活和停用商品、一个激活博客、404 与私有页面;再用结构化数据校验器检查样本实体页。富结果资格不等于排名保证。

回滚只需部署上一版本,或回退 SEO 路由清单与代码;本功能不涉及数据库迁移、支付回滚或生产数据改写。