从“分数”到“证据链”我开源了一个把SEO检查依据全部摊开来的命令行工具先说点实在的。做了这么多年站点我越来越觉得市面上的SEO检查工具都沾着同一个毛病给你一个总分然后列几个红色感叹号告诉你“标题标签太长”“图片缺少alt”。你看着那个78分既不知道这分怎么算出来的也不知道扣分扣在哪一行代码上更不知道改了之后到底能不能涨分。工具变成了一个黑盒SEO优化就变成了一场盲人摸象。所以我花了两周多时间写了一个开源的网页SEO检查工具。它不追求做一个华丽丽的评分大屏核心思路就一句每个扣分项必须附上“证据”——具体是哪个标签、哪段HTML、哪个URL触发了这条规则以及官方文档或行业惯例里为什么说这是问题。分数和依据并列输出你要改哪里、为什么改、改完会怎样一条链路清清楚楚。目前项目已经放到了GitHub上支持命令行运行输出Markdown或JSON格式报告也方便直接接进CI/CD流程里做自动化巡检。这篇文章就把这个工具从设计思路、检查规则、核心代码到踩坑实录完整拆一遍。如果你正在做独立站、内容站或者想给团队搭一套廉价的SEO巡检体系这篇应该能帮你省不少事。哪怕你不写代码光看检查规则的设计逻辑也能对“SEO工具到底在测什么”有个更清醒的判断。1. 项目背景与整体设计思路1.1 为什么我不想要一个“打分器”先讲个我自己的真实经历。有一次朋友拉我去看他们公司刚上线的营销站技术负责人很自豪地说“我们用某专业工具测过SEO得分92分”。我当场用另一款工具跑了一下得分只有61。两款差的工具算法不同可以理解但问题在于那个92分的报告里只显示“内容相关性强”“链接结构良好”没有任何一项能回答“强在哪、良好在哪里”。这就是SEO工具的经典陷阱评分本身是个压缩过程它把几十个维度的诊断结果压成一个数字丢掉了所有上下文。而SEO恰恰是一个极其依赖上下文的领域。标题长度不是非黑即白的规则一个新闻页和一个产品详情页对description的要求完全不同canonical标签缺不缺、nocanonical了没有要分页面类型判断。把这一切抹平成“3分、-2分”只会误导决策。所以我在设计这个工具时定了三原则每条规则必须声明触发条件和判定依据不能只有结论。报告必须展示“命中的原文片段”或“关联URL”而不是只显示规则名。分数只作为排序和关注的辅助不作为优化是否完成的唯一标准。换句话说我把工具从“打分器”改成了“证据记录仪”。打分仍然有但真正的交付物是那套可以追溯、可以复核的证据清单。1.2 技术选型为什么用Python为什么不做成浏览器插件技术选型上我几乎没有犹豫就选了Python。原因有几点requests加BeautifulSoup的解析链路成熟稳定生态里关于HTML解析、URL处理的库非常齐全CLI工具用Python写方便跨平台团队里做站长的同学即使不是专业程序员也能看懂代码后续想接异步抓取、接入Playwright做动态渲染Python都有现成的方案。有人问我为什么不直接做成Chrome浏览器插件。坦白说浏览器插件在拿document对象、模拟用户行为方面确实有天然优势但它的致命限制是“一次只能看一个页面”。你无法脱离Chrome做批量巡检也无法在服务器上定时跑任务。而做SEO巡检批量抓取整站和有规律的周更、月更才是硬需求。我倾向于把这个工具定位成“可编程的SEO巡检底座”而不是一个顺手点一下的小插件。选型时还考虑过直接拿Lighthouse改但看了API文档后放弃了。Lighthouse定位是性能与体验审计它有一套自己的规则体系扩展自定义SEO检查项的API文档写得不算友好而且它跑一次要起Chrome太重了。做纯静态HTML的SEO体检挂这一套东西严重浪费资源。整个工具架构拆成三层采集层抓取页面内容、robots.txt、sitemap处理重定向和超时。规则引擎层定义每个检查项的数据结构、触发条件、命中证据提取方式。报告生成层把检查结果渲染成Markdown或JSON输出到终端和文件。1.3 检查项设计原则先定规则再写代码写代码前先把检查项清单列了一遍。这个清单是跟几个做搜索优化的朋友反复对过的最后分为五大类基础标签title、meta description、keywords、lang、charset。内容结构H1唯一性、图片alt、内链、外链、内容长度。可抓取性robots.txt、sitemap、canonical、noindex、404页面。结构化数据JSON-LD有效性、必填字段。移动与性能基础viewport、页面体积、响应时间。每个检查项不是“有就加分、没有就减分”那么粗。我先为每条规则写清楚了“为什么检查它”的依据比如描述标签我引用了搜索中心对摘要撰写的建议canonical标签则参考了搜索中心关于规范地址的说明文档。这样后续无论是自己调整规则还是社区提PR都有据可依不会凭感觉乱改。2. 核心功能与检查规则拆解2.1 基础标签检查标题、描述、关键词不能只看“有没有”标题标签和meta description可能是最老生常谈的SEO话题但真正做到位的站点寥寥无几。工具在这块的检查逻辑不只是“存不存在”而是拆成多个维度。标题标签的规则设计是这样先判断是否唯一如果全站多个页面共用同一个标题搜索引擎就会很难判断页面主体。然后看长度我按60字符来作为截断参考线因为大多数搜索引擎结果页的标题展示宽度大约在这个范围。接着检查是否出现了关键词这只是一个参考维度权重很低防止有人为了凑分做关键词堆砌。meta description的部分我参考了比较常见的建议区间80到160字符。太短说明信息量不够太长则可能被搜索结果截断。但这里有个值得注意的点Google在2022年前后开始模糊化描述标签的作用很多页面它根本不用你写的description而是从正文里摘录。所以工具会额外判断如果description缺失但是正文前160字符里包含核心关键词提示等级就降为建议而不是严重。关键词标签keywords meta这个是在很多“SEO工具”里都消失了的老古董。因为Google在2009年就公开声明不把它作为排名因素百度也没有官方依据说它有效。但既然做开源工具考虑到可能有国内用户和传统建站用户我保留了这项检查但把权重设为零。它纯粹作为信息提示“写了也不扣分不写也不扣分”避免误导站长去堆砌关键词。下面是描述检查的具体判定逻辑在代码里是这样的抓取meta标签列表找到name属性等于description的那一项如果不存在就直接记录缺失并抓取正文前200个可见字符作为“替代摘要证据”。如果存在就检查长度和是否包含页面主要关键词。2.2 内容结构检查H1、alt、链接密度这些“硬指标”其实很软内容结构这块最能体现“评分工具容易误伤”的地方。先说H1很多工具把“每页只有一个H1”列为一票否决项但我见过不少特殊页面比如活动页、专题聚合页它们本身有多个视觉上等价的标题区块强行合并成一个反而不自然。所以工具的判断是H1大于1个时会列出所有H1标签的原文让用户自己去判断是不是设计需要而不是直接扣到不及格。图片alt检查是最基础也最必要的。搜索引擎无法理解图片内容alt文本是它的最主要语义来源。工具会找出所有没有alt属性、以及alt属性为空的img标签并且把src的原样输出。如果一张图片既是懒加载又没有alt基本上可以确定这个站点的图片SEO没有任何规划。内链检查这部分有些工具会做链接数量统计但数字本身没有任何意义。一个写了300个内链的导航页不见得比一个只挂了5个相关内容链接的文章页更好。所以我只做两件事统计页面internal链接和external链接的数量然后把external链接的列表完整输出方便站长度量外链风险。为什么要把外链列出来因为很多站长的网站被挂了一堆垃圾外链而不自知外链质量是搜索引擎判断站点的信用依据之一定期检查很有必要。处理链接相对地址的时候有一个坑代码里必须用urljoin来做拼接否则http://example.com/a/b这个页面里的href/contact会被解析成http://example.com/a/contact实际应该是http://example.com/contact。这种细节错误在后端程序里很常见但对SEO来说影响是实打实的。2.3 可抓取性与索引规则robots、sitemap、canonical、noindex一个都不能少可抓取性检查是技术上最能体现工具价值的部分因为这个层面普通站长用浏览器根本看不见必须靠程序去模拟搜索引擎的爬虫行为。robots.txt的检查逻辑是这样的先请求网站的robots.txt如果返回200但文件内容是空白的提示“文件存在但没有内容”这通常说明网站没有主动配置抓取策略。如果返回404那才是真正的问题默认情况下爬虫会抓取所有公开页面包括后台目录和参数URL。如果返回308或者301重定向就要看目标地址是不是同域的https版本如果是就视为正常否则可能带着爬虫跳到别的域名上去了。工具还会主动检查robots.txt里是否声明了Sitemap路径这是很多站长容易忽略的。在robots里声明sitemap位置可以帮搜索引擎更快发现更新的页面。另外凡是robots里明确Disallow的路径工具会在抓取阶段就跳过避免重复抓取已禁止访问的内容这是对线上站点的一种礼貌。sitemap.xml检查是另一块。这里我没有用严格的XML Schema校验——太严了容易误报——我只看三个点返回状态码是否200URL数量是否为零以及所有URL是否都在同一域名下。如果sitemap里混入了别的域名URL搜索引擎大概率会忽略整份文件而不是部分忽略这是一个很容易踩但改起来极快的坑。canonical标签的检查我采用了这样的逻辑如果页面本身没有被noindex并且没有连向自己URL的canonical标签就提示“建议添加”。但如果是首页或者短小的落地页这个提示降为“建议”。为什么这么做因为canonical对于内容高度重复的站点和电商聚合页是必需品但对于一个内容完全孤立的页面加不加影响有限不值得为了过工具的检查而加。2.4 结构化数据与移动端基础JSON-LD的有效性是硬门槛结构化数据检查是这套规则里第二个硬核模块。工具会从页面中提取所有application/ldjson类型的script标签逐个尝试用json.loads解析。解析失败的直接报错并输出该段脚本的前200个字符作为证据。解析成功后会检查context和type是否存在。这里不深究Schema.org的每一个具体类型——不同行业的必填字段千差万别逐项校验规则太重了——但一个连合法JSON都不是的结构化数据块Google Search Console里百分之百会给你报错这个基本门槛还是得守住。viewport检查对于移动端适配是基础中的基础。没有viewport声明的页面在移动端浏览器会用默认宽度渲染文字小到需要双指缩放才能看清这种站点在移动搜索里的体验分基本是负的。这个检查项虽然简单效果却非常直接。页面体积和响应时间这两项放在一组检查里它们不直接影响排名但会影响爬虫抓取效率和用户跳出率。工具会记录HTML源码大小、页面响应时间以及页面是否启用了gzip压缩。说实话“页面体积超过2MB就扣分”这种一刀切规则我不太认同——一个电商详情页带了大量内联JSON数据2MB是很正常的。所以这一项只做记录不参与评分让站长度量自己站点的实际情况。3. 实操过程与核心代码实现3.1 环境准备与项目结构工具在Python 3.9及以上版本运行依赖只有三个requests、beautifulsoup4、lxml。没有搞poetry、pipenv那套复杂的东西就一个requirements.txt干净省心。安装命令是pip install -r requirements.txtrequirements.txt内容如下requests2.25.0 beautifulsoup44.9.0 lxml4.6.0 colorama0.4.4colorama主要是终端输出带颜色用的严重问题时标红、警告标黄、建议标蓝看结果的时候视觉层级会更舒服。如果你在CI环境里跑可以把TERM设置成dumb或者加个--no-color参数禁用颜色输出。项目目录结构是这样安排的seo-checker/ ├── seo_checker.py # 入口文件CLI解析 ├── core/ │ ├── crawler.py # 采集层负责抓取页面与资源 │ ├── rules.py # 规则引擎所有检查项的注册与执行 │ ├── reporter.py # 报告层输出Markdown/JSON │ └── utils.py # 公共工具URL解析、HTML清洗 ├── rules/ # 按分类存放的检查项定义 │ ├── base_tags.py │ ├── content.py │ ├── crawlability.py │ ├── structured_data.py │ └── performance.py ├── tests/ # 单元测试与快照测试 ├── requirements.txt └── README.md入口命令设计得很简单python seo_checker.py https://example.com --format markdown --output report.md不加--format时默认在终端直接打印结果适合快速预览。加了--output就同时写入文件。3.2 核心检查模块一条规则的完整实现所有检查项都遵循同一种数据结构这是我做这套工具时最得意的一个设计因为它在保证灵活性的同时强制让每条规则都必须写清楚“为什么检查”“命中证据怎么提取”“怎么修复”。用代码说话dataclass class CheckResult: rule_id: str # 规则唯一ID如 BASE_TAGS_002 name: str # 规则名称如 meta description 长度 level: str # 严重程度: error / warning / info passed: bool # 是否通过 evidence: list[str] # 命中证据原始HTML片段或URL列表 message: str # 检查结论 suggestion: str # 修复建议以meta description长度检查为例完整的规则实现如下def check_description_length(soup, page_url, keyword_hint): result CheckResult( rule_idBASE_TAGS_002, namemeta description 长度与内容, levelwarning, passedTrue, evidence[], message, suggestion ) desc_tag soup.find(meta, attrs{name: lambda x: x and x.lower() description}) if not desc_tag or not desc_tag.get(content, ).strip(): result.passed False result.level error result.message 页面缺失 meta description result.evidence.append(未检测到 meta name\description\ 标签) result.suggestion 建议在 head 中添加 description 标签80-160字符包含页面核心关键词。 return result content desc_tag[content].strip() result.evidence.append(fmeta namedescription content{content[:120]}{... if len(content) 120 else }) if len(content) 80: result.passed False result.level warning result.message fdescription 长度偏短 ({len(content)} 字符) result.suggestion 当前描述信息量过少建议扩充到80-160字符。 elif len(content) 160: result.passed False result.level warning result.message fdescription 长度偏长 ({len(content)} 字符) result.suggestion 超长描述在搜索结果中可能被截断建议精简到160字符以内。 return result看到没有关键不是那个长度判断而是evidence这个字段。不管检查通过还是不通过我都把页面上真实存在的标签片段原样抓下来。这样用户看报告的时候不需要再打开浏览器去对照源码一眼就能看到工具是在对哪一段HTML说话。规则引擎的设计我借鉴了ESLint的思路每条规则独立注册、独立运行、互不干扰新增一条规则只需要在rules目录下建一个文件实现一个接收soup和页面上下文的小函数然后在规则注册表里登记一下。这种插件式结构后续交给社区维护起来会非常轻松。3.3 评分计算加权平均不是拍脑袋而是分层次评分这块我设计了三个层次基础分、内容分、技术分每一项满分100分最后的总分是三个分数的加权平均权重分别对应0.4、0.3、0.3。基础标签权重最高是因为它对所有类型的页面都有普适意义。内容结构和可抓取性各占三成这两块对内容站和技术站的重要性因人而异。单类内部的计算逻辑非常直接该类下所有检查项的通过数量除以总检查项数量再乘以100。比如基础标签类共10个检查项通过了7个基础分就是70分。最终总分通过一个简单的函数计算def calculate_score(results): base_rules [r for r in results if r.rule_id.startswith(BASE_)] content_rules [r for r in results if r.rule_id.startswith(CONTENT_)] tech_rules [r for r in results if r.rule_id.startswith(TECH_)] def avg_score(rules): if not rules: return 100.0 passed sum(1 for r in rules if r.passed) return round(passed / len(rules) * 100, 1) base_score avg_score(base_rules) content_score avg_score(content_rules) tech_score avg_score(tech_rules) total round(base_score * 0.4 content_score * 0.3 tech_score * 0.3, 1) return base_score, content_score, tech_score, total这个权重值目前是代码里写死的。如果你想调整某个分类的权重直接改这三个系数就行。需要特别说明的是info级别的检查项不参与评分它们更像是工具给你的体检报告里“医生备注”那一栏。比如“页面启用了gzip压缩”这类的记录项你看着就会比较安心不必担心不加分就心慌。3.4 用真实URL跑一次完整扫描写个真实例子。我本地搭了一个测试站点包含一个比较标准的文章页故意埋了几个问题标题超过了60字符缺失meta description有两张图片没有alt没有声明canonicalJSON-LD里有一段非法JSON。把URL喂给工具后终端输出大概长这样$ python seo_checker.py http://localhost:8000/article.html [ERROR] BASE_TAGS_002: meta description 长度与内容 页面缺失 meta description 证据: 未检测到 meta namedescription 标签 建议: 在 head 中添加 description 标签80-160字符。 [ERROR] TECH_INDEX_003: canonical 标签缺失 页面未声明 canonical如果存在重复内容可能影响索引判断 证据: link relcanonical 未在 head 中找到 [WARNING] BASE_TAGS_001: 标题长度超限 当前标题 76 字符超过建议 60 字符 证据: title这是一篇测试文章标题故意写得很长用来测试标题长度检查功能是否正常工作/title 建议: 精简标题保留核心关键词长度控制在60字符以内。 [WARNING] CONTENT_ALT_001: 图片缺失 alt 属性 共 2 张图片未设置 alt 证据: img src/images/banner-1.jpg img src/images/banner-2.jpg [INFO] PERF_SIZE_001: 页面体积 HTML 源码 12.3KB未超出常见建议值。 基础分 | 内容分 | 技术分 | 总分 60.0 | 75.0 | 66.7 | 66.3发现没有最重要的不是那个66.3分而是每一个错误事项下面都跟着证据和具体建议。这就是我在1.1节里说的“证据链”排查问题的时候完全不需要再另外打开什么工具照着建议逐条改就行。3.5 输出格式说明对接CI/CD和文档系统工具默认在终端打印报告但为了对接CI流程和自动化巡检我实现了两种结构化输出格式。Markdown格式适合直接提交到代码仓库的docs目录或者发送给非技术背景的同事。每个检查项会渲染成一段二级标题加列表的形式末尾自动生成一份分数汇总表。如果你想在项目的README里放一个“SEO巡检状态”的徽章只需要在CI里跑一次然后生成这张表就行。JSON格式是为程序消费准备的每个检查项的结果都包含完整的rule_id、level、evidence数组和suggestion字段方便下游任务做智能化处理。比如我后续准备写一个自动化的工单系统——当某条规则连续三次失败时自动在GitHub Issues里提交一个任务分配给负责对应页面的同事。这种场景下分数没什么用但精确到规则ID和证据的JSON就非常有价值了。{ url: http://localhost:8000/article.html, scores: {base: 60.0, content: 75.0, tech: 66.7, total: 66.3}, checks: [ { rule_id: BASE_TAGS_001, level: warning, passed: false, evidence: [title这是一篇测试文章标题故意写得很长用来测试标题长度检查功能是否正常工作/title], suggestion: 精简标题保留核心关键词长度控制在60字符以内。 } ] }4. 常见问题与排查技巧实录4.1 误报场景SPA页面分数暴跌怎么办工具早期版本有一个让我特别头疼的误报来源单页应用SPA。一个用Vue或React开发的页面首屏HTML里往往只有一个空壳内容全靠JavaScript渲染。如果工具直接抓取原始HTML会发现页面没有H1、没有meta描述、正文空洞直接打出20分。可实际上这个页面在真实浏览器里完美展现了所有内容。这个问题的根源在于我的工具定位是“轻量级的快速巡检”默认不做JavaScript渲染。搜索引擎的爬虫虽然现在能渲染JS但成本极高不是所有页面都会被执行完整的浏览器渲染流程。所以SPA站点本身就是一个SEO风险比较大的存在这个分数暴跌其实并不完全算误报。不过为了减少困惑我在工具里增加了一个检测机制如果抓取到的HTML中body标签的可见文本少于200个字符就自动在报告顶部给出一条警告提示“页面正文过短疑似JavaScript渲染页面”并建议该页面采用预渲染或SSR方案。这样用户看到低分时至少知道原因而且这个提示本身就是一条有价值的SEO建议。如果你确实需要对SPA页面做完整检查可以在外部配合Playwright或Puppeteer生成预渲染HTML再喂给工具。脚本逻辑不复杂就是启动浏览器、打开URL、等待几秒、把document.documentElement.outerHTML保存成文件然后跑工具分析这个文件。后续我打算在项目里增加一个--render参数本质就是内置一条调用Playwright的路径但这需要引入无头浏览器依赖目前还在权衡。4.2 内链判定urljoin的坑和路径规范化内链和外链的判定看着简单实则暗藏不少坑。早期版本我直接拿href属性是否以http开头来区分内链外链结果出了个经典bug站内存在类似https://cdn.example.com/asset.js的资源被误判为外链。后来改成拿页面URL的域名来比对确实解决了跨子域的资源误判但内链URL带不带www、是不是https又会产生新问题。我最终的方案是做两层判断。第一层把页面URL解析出netloc域名加端口比如example.com:8080。第二层把链接的netloc拿来和页面netloc做比对如果完全一致判为内链如果不一致再看去掉www前缀后是否相等。这里没有走同站site级别的模糊匹配因为对于SEO诊断来说站内和跨子域的链接在权重传递逻辑上是有差异的混在一起不利于报告判断。这个逻辑在utils.py里封装成了一个函数def is_internal_link(link_url, page_url): from urllib.parse import urlparse link_netloc urlparse(link_url).netloc page_netloc urlparse(page_url).netloc if not link_netloc: return True if link_netloc page_netloc: return True if link_netloc.replace(www., ) page_netloc.replace(www., ): return True return False这段代码还有一个好处URL链接不写域名、以斜杠开头的相对路径会被直接判为内链因为link_netloc是空的。很多新手写爬虫在这里经常出问题因为一个页面里的相对链接实在太常见了。4.3 抓取稳定性robots.txt 的 302 重定向不要随便跟robots.txt检查的代码有一个需要特别注意的点重定向处理不能太激进。举个例子http://example.com/robots.txt如果返回302跳转到https://example.com/robots.txt这是正常的HTTP到HTTPS的升级跟随跳转没问题。但如果跳转到另一个域名就说明当前站点配置有问题搜索引擎爬虫很可能抓不到你这个域名的有效robots文件。但有些工具偷懒对重定向一律跟随最后检测的是跳转后的robots内容从而漏掉配置问题。所以我的实现是先检查重定向URL的域名是否和原URL一致一致才跟随不一致就按缺失处理并给出警告。另一方面抓取sitemap.xml时要给足超时时间。很多站点的sitemap是动态生成的动辄几MB网络状况差的时候响应很慢。我之前默认设了10秒超时结果在一台海外VPS上跑国内站点的检查时频繁超时。后来改成允许通过命令行参数--timeout自定义默认仍为15秒但用户调大或者调小都方便。4.4 评分校准权重设计如何应付“你以为的SEO”和“实际有用的SEO”我自己的一个原则是工具的评分权重不能脱离“搜索引擎官方文档和一线实操经验”来拍脑袋。下面是三个很有代表性的坑。第一个是keywords标签的权重调整。工具最初版本把keywords标签缺失标为warning扣分还不少。后来我在详细调研中确认主流搜索引擎不会参考这一项之后把它的等级下调为info。这就是一个典型的“工具过于传统反而误导用户”的案例。第二个是canonical缺失要不要作为error。刚写这个检查逻辑时我几乎对所有内容页都要求有canonical结果在一批博客站点上跑出了大面积的低分排查后发现是误伤。博客文章的URL结构本身没有重复内容风险比如不带跟踪参数、不带排序变量、没有amp版本这种页面加不加canonical意义很小。我后来加了一个判断条件在页面没有检测到参数URL、没有分页链接、没有amphtml标记的前提下canonical缺失只降为suggestion。这个调整让工具的准确率明显提升不再对独立博客文章页一棍子打死。第三个经验是关于“内容长度”的检查。我见过一些工具把页面正文少于300字判为内容单薄扣分很狠。但实际上一个FAQ页、一个联系方式页面、一个下载链接页300字可能都是多的。所以工具里内容长度检查只做info记录——输出正文统计字数不参与评分。这样既给用户提供了量化信息又不会因为规则和页面类型不匹配而误判。4.5 实测排错一次与证书和超时有关的排查记录分享一次我调工具时遇到的实际排查过程。某个客户的网站配置了CDN但源站在回源时证书过期了导致工具每次抓取都报SSL错误。那时候工具还没做证书异常捕获requests直接抛了SSLError整个检查流程就中断了。后续修复时我加了一层异常处理遇到SSL相关的错误会在报告里单列一条“抓取失败”的error并提示“可能是证书过期或不被信任”。还有一个场景是CDN限流。有些站点对单个IP的并发请求有限制工具抓完HTML紧接着抓robots.txt和sitemap三个请求间隔太短触发了限流返回了403。我花了些时间排查最终在crawler里加了一个每请求之间的短暂延迟默认0.5秒可通过--delay参数调整。这个延迟不会让单页面检查变慢太多但对线上站点比较友好不至于因为我们的排查把别人的日志搞得乱七八糟。5. 开源发布与后续维护计划5.1 开源许可证与仓库整理别让好项目被license劝退开源项目如果不选许可证别人是不敢合法使用的。我最后选了MIT License。原因很实际这是一个工具类项目不是底层库我希望大家拿来就用甚至改进后闭源也没关系。MIT在商业友好度上是最宽松的一档。如果你在做一个对社区影响更大的基础组件我建议考虑Apache 2.0它额外包含了明确的专利授权条款对大公司来说更安心。但SEO检查工具这个场景MIT就够了。仓库的README我写得很详细包括工具定位、安装方式、快速上手、检查项清单、报告示例、常见问题六个部分。尤其检查项清单我做了个完整的表格每一个规则都附带文档链接这样任何用户都能在五分钟内搞明白这个工具能做什么、不能做什么避免盲目期待。项目里还给每条规则维护了一份单独的技术文档写在rules/docs目录下。这份文档不只写给使用者更是写给未来的贡献者。如果有人想新增一个“检查Hreflang标签是否成对”的规则照着现有文档的结构填就行。贡献门槛低了社区活起来的可能性才大。5.2 规则可配置化下一阶段的关键任务目前工具的检查项在代码里写死想增删必须改Python。这显然不够灵活。我计划把规则配置改成JSON或YAML驱动的形式这样即便不会写Python的SEO小伙伴也能通过配置一键启用或关闭某条规则、调整权重、设置阈值。举个例子默认规则里description长度设为80到160字符但某些特殊行业比如新闻站的描述天然就短一条新闻的description可能只有20个字符。有了配置文件站长可以轻松改成40到120而不用fork代码去手动改阈值。这个改动还会让报告的维护性大幅提升。每一条自定义规则都能有自己的evidence字段定义让报告完美贴合业务场景。虽然这会增加不少开发工作量但我认为这是工具走向成熟的关键一步。5.3 持续维护与社区协作从单一工具到巡检平台开源最忌讳把代码丢上去就不管了。我给自己设了一个不算严格但有效的工作流每两周跑一次全量检查把工具自身官网和几个示例站点作为测试集发现问题就修复并发布新版本。所有已知问题都放在Issues里标注“good first issue”标签的留给第一次参与开源贡献的新手。目前项目里Pull Request的模板也准备好了要求提交者说明新增规则或修改规则的依据最好附上参考文档链接。这样每一次规则变动都有迹可循不会出现“我拍脑袋改了规则”的情况。再往后我打算增加两个方向一是批量抓取单个站点整站做深度巡检每个页面生成一条记录汇总成站点级SEO报告二是增加历史趋势存储——比如用SQLite保存每次检查结果跑一周、一月之后能看到分数变化曲线这样SEO优化效果就能被量化追踪了。第二个方向对团队管理尤其有用SEO不再是“月底拉个报告看看”而是变成持续集成的一部分。写在最后这个工具现在还不够完美离“开箱即用”还有距离但它的核心思路已经跑通了SEO诊断最重要的从来不是一个漂亮的分数而是能让线上问题被看见、被理解、被修复的那条证据链。我做开源也有一部分私心想借社区的力量持续完善这套规则库。你有兴趣的话可以clone下来跑一下自己的站点如果发现某个检查项的判断逻辑有问题或者期待哪些新规则欢迎提Issue或者直接提PR。这个项目离了真实站点的检验是长不大的。最后说一个小技巧。拿到工具报告后请不要只盯着总分先按error级别过滤出一条条过一遍把每个error对应的evidence和suggestion对照着看。等你把所有error都修掉再回去看分数你会感受到那种“每条扣分都心中有数”的踏实感。这是我做这个工具最想传递的东西。 从“分数”到“证据链”：开源命令行SEO检查工具全解析
从“分数”到“证据链”我开源了一个把SEO检查依据全部摊开来的命令行工具先说点实在的。做了这么多年站点我越来越觉得市面上的SEO检查工具都沾着同一个毛病给你一个总分然后列几个红色感叹号告诉你“标题标签太长”“图片缺少alt”。你看着那个78分既不知道这分怎么算出来的也不知道扣分扣在哪一行代码上更不知道改了之后到底能不能涨分。工具变成了一个黑盒SEO优化就变成了一场盲人摸象。所以我花了两周多时间写了一个开源的网页SEO检查工具。它不追求做一个华丽丽的评分大屏核心思路就一句每个扣分项必须附上“证据”——具体是哪个标签、哪段HTML、哪个URL触发了这条规则以及官方文档或行业惯例里为什么说这是问题。分数和依据并列输出你要改哪里、为什么改、改完会怎样一条链路清清楚楚。目前项目已经放到了GitHub上支持命令行运行输出Markdown或JSON格式报告也方便直接接进CI/CD流程里做自动化巡检。这篇文章就把这个工具从设计思路、检查规则、核心代码到踩坑实录完整拆一遍。如果你正在做独立站、内容站或者想给团队搭一套廉价的SEO巡检体系这篇应该能帮你省不少事。哪怕你不写代码光看检查规则的设计逻辑也能对“SEO工具到底在测什么”有个更清醒的判断。1. 项目背景与整体设计思路1.1 为什么我不想要一个“打分器”先讲个我自己的真实经历。有一次朋友拉我去看他们公司刚上线的营销站技术负责人很自豪地说“我们用某专业工具测过SEO得分92分”。我当场用另一款工具跑了一下得分只有61。两款差的工具算法不同可以理解但问题在于那个92分的报告里只显示“内容相关性强”“链接结构良好”没有任何一项能回答“强在哪、良好在哪里”。这就是SEO工具的经典陷阱评分本身是个压缩过程它把几十个维度的诊断结果压成一个数字丢掉了所有上下文。而SEO恰恰是一个极其依赖上下文的领域。标题长度不是非黑即白的规则一个新闻页和一个产品详情页对description的要求完全不同canonical标签缺不缺、nocanonical了没有要分页面类型判断。把这一切抹平成“3分、-2分”只会误导决策。所以我在设计这个工具时定了三原则每条规则必须声明触发条件和判定依据不能只有结论。报告必须展示“命中的原文片段”或“关联URL”而不是只显示规则名。分数只作为排序和关注的辅助不作为优化是否完成的唯一标准。换句话说我把工具从“打分器”改成了“证据记录仪”。打分仍然有但真正的交付物是那套可以追溯、可以复核的证据清单。1.2 技术选型为什么用Python为什么不做成浏览器插件技术选型上我几乎没有犹豫就选了Python。原因有几点requests加BeautifulSoup的解析链路成熟稳定生态里关于HTML解析、URL处理的库非常齐全CLI工具用Python写方便跨平台团队里做站长的同学即使不是专业程序员也能看懂代码后续想接异步抓取、接入Playwright做动态渲染Python都有现成的方案。有人问我为什么不直接做成Chrome浏览器插件。坦白说浏览器插件在拿document对象、模拟用户行为方面确实有天然优势但它的致命限制是“一次只能看一个页面”。你无法脱离Chrome做批量巡检也无法在服务器上定时跑任务。而做SEO巡检批量抓取整站和有规律的周更、月更才是硬需求。我倾向于把这个工具定位成“可编程的SEO巡检底座”而不是一个顺手点一下的小插件。选型时还考虑过直接拿Lighthouse改但看了API文档后放弃了。Lighthouse定位是性能与体验审计它有一套自己的规则体系扩展自定义SEO检查项的API文档写得不算友好而且它跑一次要起Chrome太重了。做纯静态HTML的SEO体检挂这一套东西严重浪费资源。整个工具架构拆成三层采集层抓取页面内容、robots.txt、sitemap处理重定向和超时。规则引擎层定义每个检查项的数据结构、触发条件、命中证据提取方式。报告生成层把检查结果渲染成Markdown或JSON输出到终端和文件。1.3 检查项设计原则先定规则再写代码写代码前先把检查项清单列了一遍。这个清单是跟几个做搜索优化的朋友反复对过的最后分为五大类基础标签title、meta description、keywords、lang、charset。内容结构H1唯一性、图片alt、内链、外链、内容长度。可抓取性robots.txt、sitemap、canonical、noindex、404页面。结构化数据JSON-LD有效性、必填字段。移动与性能基础viewport、页面体积、响应时间。每个检查项不是“有就加分、没有就减分”那么粗。我先为每条规则写清楚了“为什么检查它”的依据比如描述标签我引用了搜索中心对摘要撰写的建议canonical标签则参考了搜索中心关于规范地址的说明文档。这样后续无论是自己调整规则还是社区提PR都有据可依不会凭感觉乱改。2. 核心功能与检查规则拆解2.1 基础标签检查标题、描述、关键词不能只看“有没有”标题标签和meta description可能是最老生常谈的SEO话题但真正做到位的站点寥寥无几。工具在这块的检查逻辑不只是“存不存在”而是拆成多个维度。标题标签的规则设计是这样先判断是否唯一如果全站多个页面共用同一个标题搜索引擎就会很难判断页面主体。然后看长度我按60字符来作为截断参考线因为大多数搜索引擎结果页的标题展示宽度大约在这个范围。接着检查是否出现了关键词这只是一个参考维度权重很低防止有人为了凑分做关键词堆砌。meta description的部分我参考了比较常见的建议区间80到160字符。太短说明信息量不够太长则可能被搜索结果截断。但这里有个值得注意的点Google在2022年前后开始模糊化描述标签的作用很多页面它根本不用你写的description而是从正文里摘录。所以工具会额外判断如果description缺失但是正文前160字符里包含核心关键词提示等级就降为建议而不是严重。关键词标签keywords meta这个是在很多“SEO工具”里都消失了的老古董。因为Google在2009年就公开声明不把它作为排名因素百度也没有官方依据说它有效。但既然做开源工具考虑到可能有国内用户和传统建站用户我保留了这项检查但把权重设为零。它纯粹作为信息提示“写了也不扣分不写也不扣分”避免误导站长去堆砌关键词。下面是描述检查的具体判定逻辑在代码里是这样的抓取meta标签列表找到name属性等于description的那一项如果不存在就直接记录缺失并抓取正文前200个可见字符作为“替代摘要证据”。如果存在就检查长度和是否包含页面主要关键词。2.2 内容结构检查H1、alt、链接密度这些“硬指标”其实很软内容结构这块最能体现“评分工具容易误伤”的地方。先说H1很多工具把“每页只有一个H1”列为一票否决项但我见过不少特殊页面比如活动页、专题聚合页它们本身有多个视觉上等价的标题区块强行合并成一个反而不自然。所以工具的判断是H1大于1个时会列出所有H1标签的原文让用户自己去判断是不是设计需要而不是直接扣到不及格。图片alt检查是最基础也最必要的。搜索引擎无法理解图片内容alt文本是它的最主要语义来源。工具会找出所有没有alt属性、以及alt属性为空的img标签并且把src的原样输出。如果一张图片既是懒加载又没有alt基本上可以确定这个站点的图片SEO没有任何规划。内链检查这部分有些工具会做链接数量统计但数字本身没有任何意义。一个写了300个内链的导航页不见得比一个只挂了5个相关内容链接的文章页更好。所以我只做两件事统计页面internal链接和external链接的数量然后把external链接的列表完整输出方便站长度量外链风险。为什么要把外链列出来因为很多站长的网站被挂了一堆垃圾外链而不自知外链质量是搜索引擎判断站点的信用依据之一定期检查很有必要。处理链接相对地址的时候有一个坑代码里必须用urljoin来做拼接否则http://example.com/a/b这个页面里的href/contact会被解析成http://example.com/a/contact实际应该是http://example.com/contact。这种细节错误在后端程序里很常见但对SEO来说影响是实打实的。2.3 可抓取性与索引规则robots、sitemap、canonical、noindex一个都不能少可抓取性检查是技术上最能体现工具价值的部分因为这个层面普通站长用浏览器根本看不见必须靠程序去模拟搜索引擎的爬虫行为。robots.txt的检查逻辑是这样的先请求网站的robots.txt如果返回200但文件内容是空白的提示“文件存在但没有内容”这通常说明网站没有主动配置抓取策略。如果返回404那才是真正的问题默认情况下爬虫会抓取所有公开页面包括后台目录和参数URL。如果返回308或者301重定向就要看目标地址是不是同域的https版本如果是就视为正常否则可能带着爬虫跳到别的域名上去了。工具还会主动检查robots.txt里是否声明了Sitemap路径这是很多站长容易忽略的。在robots里声明sitemap位置可以帮搜索引擎更快发现更新的页面。另外凡是robots里明确Disallow的路径工具会在抓取阶段就跳过避免重复抓取已禁止访问的内容这是对线上站点的一种礼貌。sitemap.xml检查是另一块。这里我没有用严格的XML Schema校验——太严了容易误报——我只看三个点返回状态码是否200URL数量是否为零以及所有URL是否都在同一域名下。如果sitemap里混入了别的域名URL搜索引擎大概率会忽略整份文件而不是部分忽略这是一个很容易踩但改起来极快的坑。canonical标签的检查我采用了这样的逻辑如果页面本身没有被noindex并且没有连向自己URL的canonical标签就提示“建议添加”。但如果是首页或者短小的落地页这个提示降为“建议”。为什么这么做因为canonical对于内容高度重复的站点和电商聚合页是必需品但对于一个内容完全孤立的页面加不加影响有限不值得为了过工具的检查而加。2.4 结构化数据与移动端基础JSON-LD的有效性是硬门槛结构化数据检查是这套规则里第二个硬核模块。工具会从页面中提取所有application/ldjson类型的script标签逐个尝试用json.loads解析。解析失败的直接报错并输出该段脚本的前200个字符作为证据。解析成功后会检查context和type是否存在。这里不深究Schema.org的每一个具体类型——不同行业的必填字段千差万别逐项校验规则太重了——但一个连合法JSON都不是的结构化数据块Google Search Console里百分之百会给你报错这个基本门槛还是得守住。viewport检查对于移动端适配是基础中的基础。没有viewport声明的页面在移动端浏览器会用默认宽度渲染文字小到需要双指缩放才能看清这种站点在移动搜索里的体验分基本是负的。这个检查项虽然简单效果却非常直接。页面体积和响应时间这两项放在一组检查里它们不直接影响排名但会影响爬虫抓取效率和用户跳出率。工具会记录HTML源码大小、页面响应时间以及页面是否启用了gzip压缩。说实话“页面体积超过2MB就扣分”这种一刀切规则我不太认同——一个电商详情页带了大量内联JSON数据2MB是很正常的。所以这一项只做记录不参与评分让站长度量自己站点的实际情况。3. 实操过程与核心代码实现3.1 环境准备与项目结构工具在Python 3.9及以上版本运行依赖只有三个requests、beautifulsoup4、lxml。没有搞poetry、pipenv那套复杂的东西就一个requirements.txt干净省心。安装命令是pip install -r requirements.txtrequirements.txt内容如下requests2.25.0 beautifulsoup44.9.0 lxml4.6.0 colorama0.4.4colorama主要是终端输出带颜色用的严重问题时标红、警告标黄、建议标蓝看结果的时候视觉层级会更舒服。如果你在CI环境里跑可以把TERM设置成dumb或者加个--no-color参数禁用颜色输出。项目目录结构是这样安排的seo-checker/ ├── seo_checker.py # 入口文件CLI解析 ├── core/ │ ├── crawler.py # 采集层负责抓取页面与资源 │ ├── rules.py # 规则引擎所有检查项的注册与执行 │ ├── reporter.py # 报告层输出Markdown/JSON │ └── utils.py # 公共工具URL解析、HTML清洗 ├── rules/ # 按分类存放的检查项定义 │ ├── base_tags.py │ ├── content.py │ ├── crawlability.py │ ├── structured_data.py │ └── performance.py ├── tests/ # 单元测试与快照测试 ├── requirements.txt └── README.md入口命令设计得很简单python seo_checker.py https://example.com --format markdown --output report.md不加--format时默认在终端直接打印结果适合快速预览。加了--output就同时写入文件。3.2 核心检查模块一条规则的完整实现所有检查项都遵循同一种数据结构这是我做这套工具时最得意的一个设计因为它在保证灵活性的同时强制让每条规则都必须写清楚“为什么检查”“命中证据怎么提取”“怎么修复”。用代码说话dataclass class CheckResult: rule_id: str # 规则唯一ID如 BASE_TAGS_002 name: str # 规则名称如 meta description 长度 level: str # 严重程度: error / warning / info passed: bool # 是否通过 evidence: list[str] # 命中证据原始HTML片段或URL列表 message: str # 检查结论 suggestion: str # 修复建议以meta description长度检查为例完整的规则实现如下def check_description_length(soup, page_url, keyword_hint): result CheckResult( rule_idBASE_TAGS_002, namemeta description 长度与内容, levelwarning, passedTrue, evidence[], message, suggestion ) desc_tag soup.find(meta, attrs{name: lambda x: x and x.lower() description}) if not desc_tag or not desc_tag.get(content, ).strip(): result.passed False result.level error result.message 页面缺失 meta description result.evidence.append(未检测到 meta name\description\ 标签) result.suggestion 建议在 head 中添加 description 标签80-160字符包含页面核心关键词。 return result content desc_tag[content].strip() result.evidence.append(fmeta namedescription content{content[:120]}{... if len(content) 120 else }) if len(content) 80: result.passed False result.level warning result.message fdescription 长度偏短 ({len(content)} 字符) result.suggestion 当前描述信息量过少建议扩充到80-160字符。 elif len(content) 160: result.passed False result.level warning result.message fdescription 长度偏长 ({len(content)} 字符) result.suggestion 超长描述在搜索结果中可能被截断建议精简到160字符以内。 return result看到没有关键不是那个长度判断而是evidence这个字段。不管检查通过还是不通过我都把页面上真实存在的标签片段原样抓下来。这样用户看报告的时候不需要再打开浏览器去对照源码一眼就能看到工具是在对哪一段HTML说话。规则引擎的设计我借鉴了ESLint的思路每条规则独立注册、独立运行、互不干扰新增一条规则只需要在rules目录下建一个文件实现一个接收soup和页面上下文的小函数然后在规则注册表里登记一下。这种插件式结构后续交给社区维护起来会非常轻松。3.3 评分计算加权平均不是拍脑袋而是分层次评分这块我设计了三个层次基础分、内容分、技术分每一项满分100分最后的总分是三个分数的加权平均权重分别对应0.4、0.3、0.3。基础标签权重最高是因为它对所有类型的页面都有普适意义。内容结构和可抓取性各占三成这两块对内容站和技术站的重要性因人而异。单类内部的计算逻辑非常直接该类下所有检查项的通过数量除以总检查项数量再乘以100。比如基础标签类共10个检查项通过了7个基础分就是70分。最终总分通过一个简单的函数计算def calculate_score(results): base_rules [r for r in results if r.rule_id.startswith(BASE_)] content_rules [r for r in results if r.rule_id.startswith(CONTENT_)] tech_rules [r for r in results if r.rule_id.startswith(TECH_)] def avg_score(rules): if not rules: return 100.0 passed sum(1 for r in rules if r.passed) return round(passed / len(rules) * 100, 1) base_score avg_score(base_rules) content_score avg_score(content_rules) tech_score avg_score(tech_rules) total round(base_score * 0.4 content_score * 0.3 tech_score * 0.3, 1) return base_score, content_score, tech_score, total这个权重值目前是代码里写死的。如果你想调整某个分类的权重直接改这三个系数就行。需要特别说明的是info级别的检查项不参与评分它们更像是工具给你的体检报告里“医生备注”那一栏。比如“页面启用了gzip压缩”这类的记录项你看着就会比较安心不必担心不加分就心慌。3.4 用真实URL跑一次完整扫描写个真实例子。我本地搭了一个测试站点包含一个比较标准的文章页故意埋了几个问题标题超过了60字符缺失meta description有两张图片没有alt没有声明canonicalJSON-LD里有一段非法JSON。把URL喂给工具后终端输出大概长这样$ python seo_checker.py http://localhost:8000/article.html [ERROR] BASE_TAGS_002: meta description 长度与内容 页面缺失 meta description 证据: 未检测到 meta namedescription 标签 建议: 在 head 中添加 description 标签80-160字符。 [ERROR] TECH_INDEX_003: canonical 标签缺失 页面未声明 canonical如果存在重复内容可能影响索引判断 证据: link relcanonical 未在 head 中找到 [WARNING] BASE_TAGS_001: 标题长度超限 当前标题 76 字符超过建议 60 字符 证据: title这是一篇测试文章标题故意写得很长用来测试标题长度检查功能是否正常工作/title 建议: 精简标题保留核心关键词长度控制在60字符以内。 [WARNING] CONTENT_ALT_001: 图片缺失 alt 属性 共 2 张图片未设置 alt 证据: img src/images/banner-1.jpg img src/images/banner-2.jpg [INFO] PERF_SIZE_001: 页面体积 HTML 源码 12.3KB未超出常见建议值。 基础分 | 内容分 | 技术分 | 总分 60.0 | 75.0 | 66.7 | 66.3发现没有最重要的不是那个66.3分而是每一个错误事项下面都跟着证据和具体建议。这就是我在1.1节里说的“证据链”排查问题的时候完全不需要再另外打开什么工具照着建议逐条改就行。3.5 输出格式说明对接CI/CD和文档系统工具默认在终端打印报告但为了对接CI流程和自动化巡检我实现了两种结构化输出格式。Markdown格式适合直接提交到代码仓库的docs目录或者发送给非技术背景的同事。每个检查项会渲染成一段二级标题加列表的形式末尾自动生成一份分数汇总表。如果你想在项目的README里放一个“SEO巡检状态”的徽章只需要在CI里跑一次然后生成这张表就行。JSON格式是为程序消费准备的每个检查项的结果都包含完整的rule_id、level、evidence数组和suggestion字段方便下游任务做智能化处理。比如我后续准备写一个自动化的工单系统——当某条规则连续三次失败时自动在GitHub Issues里提交一个任务分配给负责对应页面的同事。这种场景下分数没什么用但精确到规则ID和证据的JSON就非常有价值了。{ url: http://localhost:8000/article.html, scores: {base: 60.0, content: 75.0, tech: 66.7, total: 66.3}, checks: [ { rule_id: BASE_TAGS_001, level: warning, passed: false, evidence: [title这是一篇测试文章标题故意写得很长用来测试标题长度检查功能是否正常工作/title], suggestion: 精简标题保留核心关键词长度控制在60字符以内。 } ] }4. 常见问题与排查技巧实录4.1 误报场景SPA页面分数暴跌怎么办工具早期版本有一个让我特别头疼的误报来源单页应用SPA。一个用Vue或React开发的页面首屏HTML里往往只有一个空壳内容全靠JavaScript渲染。如果工具直接抓取原始HTML会发现页面没有H1、没有meta描述、正文空洞直接打出20分。可实际上这个页面在真实浏览器里完美展现了所有内容。这个问题的根源在于我的工具定位是“轻量级的快速巡检”默认不做JavaScript渲染。搜索引擎的爬虫虽然现在能渲染JS但成本极高不是所有页面都会被执行完整的浏览器渲染流程。所以SPA站点本身就是一个SEO风险比较大的存在这个分数暴跌其实并不完全算误报。不过为了减少困惑我在工具里增加了一个检测机制如果抓取到的HTML中body标签的可见文本少于200个字符就自动在报告顶部给出一条警告提示“页面正文过短疑似JavaScript渲染页面”并建议该页面采用预渲染或SSR方案。这样用户看到低分时至少知道原因而且这个提示本身就是一条有价值的SEO建议。如果你确实需要对SPA页面做完整检查可以在外部配合Playwright或Puppeteer生成预渲染HTML再喂给工具。脚本逻辑不复杂就是启动浏览器、打开URL、等待几秒、把document.documentElement.outerHTML保存成文件然后跑工具分析这个文件。后续我打算在项目里增加一个--render参数本质就是内置一条调用Playwright的路径但这需要引入无头浏览器依赖目前还在权衡。4.2 内链判定urljoin的坑和路径规范化内链和外链的判定看着简单实则暗藏不少坑。早期版本我直接拿href属性是否以http开头来区分内链外链结果出了个经典bug站内存在类似https://cdn.example.com/asset.js的资源被误判为外链。后来改成拿页面URL的域名来比对确实解决了跨子域的资源误判但内链URL带不带www、是不是https又会产生新问题。我最终的方案是做两层判断。第一层把页面URL解析出netloc域名加端口比如example.com:8080。第二层把链接的netloc拿来和页面netloc做比对如果完全一致判为内链如果不一致再看去掉www前缀后是否相等。这里没有走同站site级别的模糊匹配因为对于SEO诊断来说站内和跨子域的链接在权重传递逻辑上是有差异的混在一起不利于报告判断。这个逻辑在utils.py里封装成了一个函数def is_internal_link(link_url, page_url): from urllib.parse import urlparse link_netloc urlparse(link_url).netloc page_netloc urlparse(page_url).netloc if not link_netloc: return True if link_netloc page_netloc: return True if link_netloc.replace(www., ) page_netloc.replace(www., ): return True return False这段代码还有一个好处URL链接不写域名、以斜杠开头的相对路径会被直接判为内链因为link_netloc是空的。很多新手写爬虫在这里经常出问题因为一个页面里的相对链接实在太常见了。4.3 抓取稳定性robots.txt 的 302 重定向不要随便跟robots.txt检查的代码有一个需要特别注意的点重定向处理不能太激进。举个例子http://example.com/robots.txt如果返回302跳转到https://example.com/robots.txt这是正常的HTTP到HTTPS的升级跟随跳转没问题。但如果跳转到另一个域名就说明当前站点配置有问题搜索引擎爬虫很可能抓不到你这个域名的有效robots文件。但有些工具偷懒对重定向一律跟随最后检测的是跳转后的robots内容从而漏掉配置问题。所以我的实现是先检查重定向URL的域名是否和原URL一致一致才跟随不一致就按缺失处理并给出警告。另一方面抓取sitemap.xml时要给足超时时间。很多站点的sitemap是动态生成的动辄几MB网络状况差的时候响应很慢。我之前默认设了10秒超时结果在一台海外VPS上跑国内站点的检查时频繁超时。后来改成允许通过命令行参数--timeout自定义默认仍为15秒但用户调大或者调小都方便。4.4 评分校准权重设计如何应付“你以为的SEO”和“实际有用的SEO”我自己的一个原则是工具的评分权重不能脱离“搜索引擎官方文档和一线实操经验”来拍脑袋。下面是三个很有代表性的坑。第一个是keywords标签的权重调整。工具最初版本把keywords标签缺失标为warning扣分还不少。后来我在详细调研中确认主流搜索引擎不会参考这一项之后把它的等级下调为info。这就是一个典型的“工具过于传统反而误导用户”的案例。第二个是canonical缺失要不要作为error。刚写这个检查逻辑时我几乎对所有内容页都要求有canonical结果在一批博客站点上跑出了大面积的低分排查后发现是误伤。博客文章的URL结构本身没有重复内容风险比如不带跟踪参数、不带排序变量、没有amp版本这种页面加不加canonical意义很小。我后来加了一个判断条件在页面没有检测到参数URL、没有分页链接、没有amphtml标记的前提下canonical缺失只降为suggestion。这个调整让工具的准确率明显提升不再对独立博客文章页一棍子打死。第三个经验是关于“内容长度”的检查。我见过一些工具把页面正文少于300字判为内容单薄扣分很狠。但实际上一个FAQ页、一个联系方式页面、一个下载链接页300字可能都是多的。所以工具里内容长度检查只做info记录——输出正文统计字数不参与评分。这样既给用户提供了量化信息又不会因为规则和页面类型不匹配而误判。4.5 实测排错一次与证书和超时有关的排查记录分享一次我调工具时遇到的实际排查过程。某个客户的网站配置了CDN但源站在回源时证书过期了导致工具每次抓取都报SSL错误。那时候工具还没做证书异常捕获requests直接抛了SSLError整个检查流程就中断了。后续修复时我加了一层异常处理遇到SSL相关的错误会在报告里单列一条“抓取失败”的error并提示“可能是证书过期或不被信任”。还有一个场景是CDN限流。有些站点对单个IP的并发请求有限制工具抓完HTML紧接着抓robots.txt和sitemap三个请求间隔太短触发了限流返回了403。我花了些时间排查最终在crawler里加了一个每请求之间的短暂延迟默认0.5秒可通过--delay参数调整。这个延迟不会让单页面检查变慢太多但对线上站点比较友好不至于因为我们的排查把别人的日志搞得乱七八糟。5. 开源发布与后续维护计划5.1 开源许可证与仓库整理别让好项目被license劝退开源项目如果不选许可证别人是不敢合法使用的。我最后选了MIT License。原因很实际这是一个工具类项目不是底层库我希望大家拿来就用甚至改进后闭源也没关系。MIT在商业友好度上是最宽松的一档。如果你在做一个对社区影响更大的基础组件我建议考虑Apache 2.0它额外包含了明确的专利授权条款对大公司来说更安心。但SEO检查工具这个场景MIT就够了。仓库的README我写得很详细包括工具定位、安装方式、快速上手、检查项清单、报告示例、常见问题六个部分。尤其检查项清单我做了个完整的表格每一个规则都附带文档链接这样任何用户都能在五分钟内搞明白这个工具能做什么、不能做什么避免盲目期待。项目里还给每条规则维护了一份单独的技术文档写在rules/docs目录下。这份文档不只写给使用者更是写给未来的贡献者。如果有人想新增一个“检查Hreflang标签是否成对”的规则照着现有文档的结构填就行。贡献门槛低了社区活起来的可能性才大。5.2 规则可配置化下一阶段的关键任务目前工具的检查项在代码里写死想增删必须改Python。这显然不够灵活。我计划把规则配置改成JSON或YAML驱动的形式这样即便不会写Python的SEO小伙伴也能通过配置一键启用或关闭某条规则、调整权重、设置阈值。举个例子默认规则里description长度设为80到160字符但某些特殊行业比如新闻站的描述天然就短一条新闻的description可能只有20个字符。有了配置文件站长可以轻松改成40到120而不用fork代码去手动改阈值。这个改动还会让报告的维护性大幅提升。每一条自定义规则都能有自己的evidence字段定义让报告完美贴合业务场景。虽然这会增加不少开发工作量但我认为这是工具走向成熟的关键一步。5.3 持续维护与社区协作从单一工具到巡检平台开源最忌讳把代码丢上去就不管了。我给自己设了一个不算严格但有效的工作流每两周跑一次全量检查把工具自身官网和几个示例站点作为测试集发现问题就修复并发布新版本。所有已知问题都放在Issues里标注“good first issue”标签的留给第一次参与开源贡献的新手。目前项目里Pull Request的模板也准备好了要求提交者说明新增规则或修改规则的依据最好附上参考文档链接。这样每一次规则变动都有迹可循不会出现“我拍脑袋改了规则”的情况。再往后我打算增加两个方向一是批量抓取单个站点整站做深度巡检每个页面生成一条记录汇总成站点级SEO报告二是增加历史趋势存储——比如用SQLite保存每次检查结果跑一周、一月之后能看到分数变化曲线这样SEO优化效果就能被量化追踪了。第二个方向对团队管理尤其有用SEO不再是“月底拉个报告看看”而是变成持续集成的一部分。写在最后这个工具现在还不够完美离“开箱即用”还有距离但它的核心思路已经跑通了SEO诊断最重要的从来不是一个漂亮的分数而是能让线上问题被看见、被理解、被修复的那条证据链。我做开源也有一部分私心想借社区的力量持续完善这套规则库。你有兴趣的话可以clone下来跑一下自己的站点如果发现某个检查项的判断逻辑有问题或者期待哪些新规则欢迎提Issue或者直接提PR。这个项目离了真实站点的检验是长不大的。最后说一个小技巧。拿到工具报告后请不要只盯着总分先按error级别过滤出一条条过一遍把每个error对应的evidence和suggestion对照着看。等你把所有error都修掉再回去看分数你会感受到那种“每条扣分都心中有数”的踏实感。这是我做这个工具最想传递的东西。