# @capgo/seo-checker 中文文档

规范地址：https://npmcn.com/package/%40capgo/seo-checker/

版本：0\.0\.13
npm 元数据更新时间：2026-08-19T10:41:33.097Z
中文译文更新时间：2026-11-09T17:14:46.869Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40capgo/seo-checker
原文对照：https://npmcn.com/package/%40capgo/seo-checker/?lang=original
项目主页：https://github.com/Cap-go/seo-checker#readme
源码仓库：https://github.com/Cap-go/seo-checker

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，47 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：3 个
- 首次发布：2026-01-04T03:58:31.350Z
- 最新版本发布：2026-01-06T15:14:04.615Z
- 近 30 天下载量：2169（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

在 Dist 文件夹中分析已建 HTML 文件的静态 SIO 检查器

## 安装

```sh
npm install @capgo/seo-checker
```

也可以使用：`pnpm add @capgo/seo-checker`、`yarn add @capgo/seo-checker`、`bun add @capgo/seo-checker`

## README

# @ capgo/ seo检查器

静态 SEO 检查器,用于分析 Dist 文件夹中已建的 HTML 文件 。 以1000+规则进行综合的SEO分析,涵盖元数据、内容质量、可访问性、结构化数据等.

受Ahrefs SEO审计和灯塔SEO审计的启发,但专注于用Astro,Next.js,SvelteKit等框架所建的静态站点.

## 安装

```bash
npm install @capgo/seo-checker
# or
bun add @capgo/seo-checker
```

## CLI 使用量

```bash
# Run with default settings (scans ./dist)
npx @capgo/seo-checker

# Specify dist path
npx @capgo/seo-checker --dist ./build

# Output as JSON
npx @capgo/seo-checker --output json

# Generate a sample config file
npx @capgo/seo-checker --generate-config
```

### CLI 选项

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `--dist <path>` | Dist 文件夹的路径 | `./dist` |
| `--config <path>` | 配置文件的路径 | `seo-checker.config.json` |
| `--output <format>` | 输出格式:控制台、json、sarif、github | `console` |
| `--report <path>` | 写入报表文件的路径 | \- 说吧 |
| `--fail-on <level>` | 失败: 错误、 警告、 通知 | `error` |
| `--max-issues <n>` | 停止前的最大问题 | `0` (无限制) |
| `--generate-config` | 生成一个样本配置文件 | \- 说吧 |

## 配置

创建一个 `seo-checker.config.json` 文件 :

```json
{
  "distPath": "./dist",
  "baseUrl": "https://example.com",
  "languages": ["en", "es", "fr"],
  "defaultLanguage": "en",
  "rules": {
    "disabled": ["SEO00186", "SEO00189"],
    "severityOverrides": {
      "SEO00135": "notice"
    }
  },
  "exclusions": [
    {
      "ruleId": "SEO00147",
      "filePath": "404.html",
      "reason": "404 page intentionally has broken link examples"
    }
  ],
  "failOn": ["error"],
  "maxIssues": 0,
  "outputFormat": "console"
}
```

## 程序用途

```typescript
import {
  checkDuplicates,
  printReport,
  runPageChecks,
  scanDistFolder
} from '@capgo/seo-checker'

const config = {
  distPath: './dist',
  baseUrl: 'https://example.com',
  languages: ['en'],
  defaultLanguage: 'en',
}

// Scan the dist folder
const siteData = await scanDistFolder(config)

// Run checks on each page
const issues = []
for (const page of siteData.pages.values()) {
  issues.push(...runPageChecks(page, config, siteData))
}

// Check for duplicates
issues.push(...checkDuplicates(siteData, config))

console.log(`Found ${issues.length} SEO issues`)
```

## 规则类别

检查器包含1000+规则,跨越这些类别:

-   **元数据**: 标题,描述,词条,字符集,朗语
-   **内容长度**: 标题/说明/标题长度限制
-   **内容格式**: 白空间,编码,盖子,平分
-   **标题**: H1 存在,分级,重复
-   **指数**:机器人指令、犬类问题
-   **链接**: 断开链接、 锁定文本、 无后续使用
-   **图像**: 备选案文文本、文件大小、已损坏的引用
-   **社会标记**: OpenGraph, 推特卡
-   **国际机会均等组织**: Hreflang, lang 属性
-   **结构数据**: JSON- LD 验证
-   **无障碍**: 地标,跳过链接, ARIA
-   **机器人.txt & Siteap**: 审定和一致性

## 输出格式

### 控制台( 默认)

按类别和严重程度指标分类的有色终端产出.

### 贾森

机器可读 JSON 与所有的问题和统计.

### 沙特阿拉伯

用于CI/CD整合的静态分析结果互换格式.

### GitHub 图像

GitHub 动作工作流程命令格式. 问题作为说明列入公关/承诺.

```bash
# Use in GitHub Actions
npx @capgo/seo-checker --output github
```

工作流程示例:

```yaml
- name: SEO Check
  run: npx @capgo/seo-checker --output github --fail-on error,warning
```

## 许可证

麻省理工学院

## 常见问题

### @capgo/seo-checker 是什么？

在 Dist 文件夹中分析已建 HTML 文件的静态 SIO 检查器

### 如何安装 @capgo/seo-checker？

在项目目录运行 npm install @capgo/seo-checker，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 seo-checker，可以用 npx seo-checker 直接运行。

### @capgo/seo-checker 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @capgo/seo-checker 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @capgo/seo-checker 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @capgo/seo-checker 可以商用吗？

@capgo/seo-checker 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @capgo/seo-checker 的下载量有多少？

根据 npm 官方下载统计，@capgo/seo-checker 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,169 次，日均约 72 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @capgo/seo-checker 还在维护吗？

最新版本 0\.0\.13 发布于 2026/01/06（10 个月前）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/01/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。