Google 搜你的品牌，sitelinks search box 不出现，或者 knowledge panel 显示的站名跟你期望的略有不同。view-source 首页，看到 WebSite JSON-LD 块里的值跟可见站点对不上：name 写 “My AI Site”，但 logo 和页脚写的是 “AI Productivity Guide”。potentialAction.target.urlTemplate 指向 /?q={search_term_string}，但你的搜索端点其实是 /search?query=。Google 把 WebSite JSON-LD 当作判断 sitelinks search、站名、品牌身份的高信任信号——但只在值跟实际一致时才用。
常见原因
按命中率从高到低。
1. name 用了旧 / 占位品牌
starter template 自带 name: "My Site" 你没改。或者改了品牌但没更新 JSON-LD 生成器。
怎么判断：
curl -s https://yoursite.com/ | grep -oP '"@type":"WebSite"[\s\S]+?</script>' | grep -oP '"name":"\K[^"]+'跟可见 logo / 页脚名不一样就是这条。
2. url 与 canonical 的尾斜杠不一致
JSON-LD："url": "https://yoursite.com"。Canonical："https://yoursite.com/"。Google 看到两个略不同的 URL 都声称是站点根。
怎么判断：对比 WebSite.url 跟首页 canonical。必须字节级一致。
3. potentialAction URL 模板指向不存在的端点
"potentialAction": {
"@type": "SearchAction",
"target": "https://yoursite.com/?q={search_term_string}"
}但你的真实搜索 URL 是 /search/?query=foo。Google 用样本搜索测模板；返回 404 或不是搜索结果就忽略 SearchAction。
怎么判断：
curl -sI "https://yoursite.com/?q=test" # 应返回 200 + 搜索结果404 就是模板错。
4. inLanguage 与 <html lang> 不一致
JSON-LD："inLanguage": "en"。HTML：<html lang="en-US">。要对齐。
怎么判断：
curl -s https://yoursite.com/ | grep -oE '<html[^>]+lang="[^"]+"|"inLanguage":"[^"]+"'5. 同页多个 WebSite 块
有些模板从 layout 文件和单独的站级 schema 组件都吐 WebSite。Google 看到同一个 WebSite 有 2 个块——混乱。
怎么判断：
curl -s https://yoursite.com/ | grep -c '"@type":"WebSite"'1 = 重复。选一个源，删另一个。
6. 每页都加 WebSite JSON-LD（不只是首页）
严格说不算”错”，但浪费。最佳实践是只在首页发；站内其他页面不需要。
怎么判断：检查非首页文章的 JSON-LD。有 WebSite 就是冗余。
7. @id 与 URL 不同
"@id": "https://yoursite.com#website" 没问题。"@id": "https://oldsite.com/#website" 不行——老域名引用。
怎么判断：看 @id 有没有遗留域名或格式错。
最短修复路径
第 1 步：定义单一可信源
在 site.config.mjs 或类似：
export const SITE = {
name: "AI Productivity Guide",
url: "https://yoursite.com",
searchUrlTemplate: "https://yoursite.com/search?query={search_term_string}",
inLanguage: "en", // 或 "en-US"，匹配 <html lang>
};第 2 步：从中生成 WebSite JSON-LD
只在首页：
---
import { SITE } from '../site.config.mjs';
const isHomepage = Astro.url.pathname === '/' || Astro.url.pathname === '/en/';
---
{isHomepage && (
<script type="application/ld+json" set:html={JSON.stringify({
"@context": "https://schema.org",
"@type": "WebSite",
"@id": `${SITE.url}#website`,
"url": SITE.url,
"name": SITE.name,
"inLanguage": SITE.inLanguage,
"potentialAction": {
"@type": "SearchAction",
"target": {
"@type": "EntryPoint",
"urlTemplate": SITE.searchUrlTemplate,
},
"query-input": "required name=search_term_string",
},
})}></script>
)}第 3 步：验证搜索端点能用
curl -sI "https://yoursite.com/search?query=test" | head -1必须 200。页面必须真的根据 query 参数显示搜索结果。
第 4 步：可见元素对齐
首页 <title>、logo alt 文字、页脚站名、schema.org name——四个完全一致。
第 5 步：删重复 WebSite 块
grep -rn 'WebSite' src/layouts src/components留一个源，其余删。
第 6 步：Rich Results Test 校验
部署后，Rich Results Test 打开首页。应该检测到 WebSite 类型带 SearchAction。
第 7 步：等并观察
sitelinks search box 是否出现由 Google 决定。修后可能几周到几个月才出现（也可能永远不出现——Google 已经减少这些功能）。别期待一夜出现。
哪些情况可能不是你操作错了
即使完美的 WebSite JSON-LD，sitelinks search box 近年也被 Google 默默削减，对大多数非主流站点都不显示。哪怕标记完美，小站也不应期待这些富功能。
容易误判的情况
每页都加 WebSite JSON-LD（不只是首页）——没必要且增加 payload。Google 只从首页读它。
预防建议
- 站名 / URL / 搜索端点都来自单一
SITE配置。 - WebSite JSON-LD 只在首页发（双语站只在该 locale 首页）。
- 改 URL 路由后验证搜索端点真的对
?q=test返回 200 + 结果。 - CI 断言：首页有且只有一个 WebSite 块。
- 改品牌或改搜索端点 URL 时同步更新 WebSite JSON-LD。
FAQ
- 能声明多个 WebSite 块吗？ 一页一个；其余被忽略或合并。
- SearchAction 一定显示吗？ 不一定——Google 按 query 和站点权威度决定。