博客 SEO 自我体检：27 个页面里揪出四个系统性毛病

毛病一：文章标题根本不是 h1#

打开文章页源码，标题长这样：

<div id="post-title" class="...text-3xl...">
    <span>博客 SEO 自我体检</span>
</div>

主题作者把标题当成”一段排版好的文字”来写，视觉上完全没问题 —— 字号、粗细、左侧那条主题色竖线都对。但语义上它只是一个 div，搜索引擎读到的文章页没有主标题。

修法是把 div 换成 h1，id 和 class 一个都不动：

-<div id="post-title" class="...">
+<h1 id="post-title" class="...">
     <span>{entry.data.title}</span>
-</div>
+</h1>

这里有个细节值得记：#post-title 被两个脚本按 id 依赖着（行内 diff 高亮、Pagefind 的搜索权重标记），所以只换标签、不换 id，改完这两处逻辑毫发无损。

首页、/2/、/archive/ 是另一类情况：它们本来就没有可见标题（只有文章卡片列表）。硬塞一个大标题会破坏设计，我的做法是给布局加一个 heading 属性，在 <main> 里输出一个 sr-only 的 h1：

{heading && <h1 class="sr-only">{heading}</h1>}

然后首页传「站点名 · 副标题」、分页页传「站点名 · 第 N 页」、归档页传「文章归档」。屏幕阅读器和爬虫都能读到，视觉上零变化。

毛病二：28 个页面都没有分享图#

Layout.astro 里原本是这么写的：

{ogImage && <meta property="og:image" content={new URL(ogImage, Astro.site).toString()} />}

逻辑本身没错，问题在于文章 frontmatter 里普遍没有 image 字段 —— 于是 ogImage 永远是 undefined，这行永远不输出。分享到群里，卡片就是纯文字。

修法是给站点做一张默认图，然后无条件输出：

const resolvedOgImage = new URL(ogImage || "/og-default.png", Astro.site).toString();

这张图是用 Python + Pillow 画的（1200×630，竖版渐变 + 主题色光晕 + 微软雅黑），35 KB。只有用默认图时才补 og:image:width/height，文章自带封面时就不写死尺寸 —— 免得声明了 1200×630 实际是别的比例。

毛病三：十几个页面共用同一段描述#

体检表里那些 34 特别扎眼：所有不传 description 的页面都落到了 siteConfig.description。对搜索引擎来说，这十几个页面的摘要是一模一样的 —— 摘要本该是”这一页讲什么”，不是”这个站讲什么”。

修法很土但有效：给每个页面单独写。14 个页面，全部控制在 60~72 字（中文的 SERP 摘要大约展示 78 字，60 是个安全值）：

<MainGridLayout
    title="工具"
    description="peroe 的博客在线工具箱：封面生成、图片画廊、幻影坦克、零宽短链等小工具，全部在浏览器本地运行，不上传数据、不需要登录。"
>

因为文件多，这类机械改动我用 Python 批量做，每处替换都断言「命中数 == 1」：

n = text.count(old)
assert n == 1, f"{rel}: 期望命中 1 处，实际 {n} 处"

没有这条断言，replace 静默不命中时你根本不会发现 —— 这项检查在本次改 23 处时救了我两次（有两处字符串写错了一个空格）。

毛病四：404 页输出了两份 head#

体检表里 /404 那一行 description 是 34 字，可我明明给它写了描述。翻构建产物才发现页面里有两份 <head>：

<html><head>...<title>页面未找到 - peroe 的博客</title>
       <meta name="description" content="（站点默认描述）">
...<!----><html><head><title>页面不存在 - peroe 的博客</title>...

原因是 404 页这么写的：

<Layout title="页面未找到">          <!-- 外层已经套了一个 Layout -->
    <MainGridLayout title="页面不存在">  <!-- 这里面又包含一个 Layout -->

MainGridLayout 内部本身就包了 Layout，再套一层就成了「Layout 里套 Layout」——整份文档被渲染两遍，浏览器能容错，爬虫只会困惑。删掉外层那层就干净了。

警告

这类错误不会报错、不会白屏，只有把产物当文本看才会暴露。所以体检脚本必须扫 dist/，而不是看浏览器里”页面能用”。

附带发现：薄内容工具页#

体检表还标了两行字数：/tools/gallery/ 只有 105 字、/tools/files/ 只有 166 字。这两页的功能都是脚本渲染的（画廊靠 JS 拉图、文件列表靠 JS 渲染），爬虫来的时候看到一个空壳。

处理方式不是 noindex（这些页是有用的入口），而是补服务端渲染的正文：讲清楚这些图/文件从哪来、为什么不放第三方图床、下载前要注意什么。