国际化 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 等)直接获取高信噪比结构化事实:
/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。
- 公开内容 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-txtLink响应头,以及带 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。
- 公开博客、商品、技术文档,以及任何绑定了主题
- 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 增长驾驶舱与高密度引语模型
- 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)与多语言翻译层同步。
- AI 爬虫访问监控(
- 面向 AI 引用的高密度内容模型(Citation-Ready Content)
- 商品与文章的
metaData(及多语言metaData.translations[locale])标准化支持:tldr:核心结论摘要,作为.md镜像与/llms-full.txt的首段高亮引语;keySpecs:核心参数键值对,自动渲染为 Markdown 对比表格并注入ProductJSON-LD 的additionalProperty(PropertyValue);faqs:常见问答对,自动注入FAQPageJSON-LD 并输出至.md镜像末尾;relatedLinks:商品 ↔ 博客/文档双向语义内链,在前台与.md语料中同步输出关联链接与价格。
- 商品与文章的
- GeoIP 地域智能转化 × 渠道交叉报表
/api/payments/info基于离线 GeoIP(resolveRequestGeo)对可用支付方式进行地域亲和度智能排序(sortPaymentMethodsByGeo),在不改变 Canonical URL 与currencySnapshot基础记账快照的前提下,在收银台将最契合当地习惯的支付方式置顶并标记推荐徽章(recommendedByGeo)。- 增长驾驶舱统一复用访客统计服务(
loadVisitorReport+buildVisitorGeoConversions)输出「国家/地区 × AI 渠道/自然搜索」交叉报表(geoConversions),转化率按去重付款访客计算(paidVisitors / totalVisitors、aiPaidVisitors / aiVisitors、searchPaidVisitors / searchVisitors),收入与客单价按记账币种分桶(revenueByCurrency、aovByCurrency),严禁跨币种直接相加。
- 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 路由清单与代码;本功能不涉及数据库迁移、支付回滚或生产数据改写。