# @gscdump/analysis 中文文档

规范地址：https://npmcn.com/package/%40gscdump/analysis/

版本：7\.15\.0
npm 元数据更新时间：2026-11-16T15:40:00.317Z
中文译文更新时间：2026-11-17T02:51:14.481Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gscdump/analysis
原文对照：https://npmcn.com/package/%40gscdump/analysis/?lang=original
项目主页：https://github.com/harlan-zw/gscdump/tree/main/packages/analysis#readme
源码仓库：https://github.com/harlan-zw/gscdump

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

- 包体积（解压后）：293 kB，99 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.13\.0
- 运行依赖：4 个
- 首次发布：2026-04-27T04:54:51.429Z
- 最新版本发布：2026-11-16T15:39:59.924Z
- 近 30 天下载量：9025（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：265（近 12 个月 265 个）

## 中文简介

GSC分析器——出击-距离,机会,出动者,衰变,品牌,集群,集中,季节性. 纯以行为主+ DuckDB-native.

## 安装

```sh
npm install @gscdump/analysis
```

也可以使用：`pnpm add @gscdump/analysis`、`yarn add @gscdump/analysis`、`bun add @gscdump/analysis`

## README

# @gscdump/ 分析

[![npm version](https://img.shields.io/npm/v/@gscdump/analysis?color=yellow)](https://npmjs.com/package/@gscdump/analysis) [![npm downloads](https://img.shields.io/npm/dm/@gscdump/analysis?color=yellow)](https://npm.chart.dev/@gscdump/analysis) [![license](https://img.shields.io/github/license/harlan-zw/gscdump?color=yellow)](https://github.com/harlan-zw/gscdump/blob/main/LICENSE)

为Google搜索控制台数据提供SEO分析器和报告. 对已有的行使用纯函数,或对照源运行分析器.

## 安装

```bash
npm install @gscdump/analysis
```

节点(Node.js 22)或更新的节点消费者需要.

## 选择导出

| 子路径 | 目的 |
| --- | --- |
| `@gscdump/analysis` | 纯分析器、浏览器发送和共享分析器合同 |
| `@gscdump/analysis/registry` | 所有30个注册分析器,包括SQL执行 |
| `@gscdump/analysis/report` | 报告登记册, `runReport`和格式化 |
| `@gscdump/analysis/source` | 复合和内燃工厂 |
| `@gscdump/analysis/sitemap-health` | 无进口品的Sitemp保健三角洲和站点地图倒塌检查 |
| `@gscdump/analysis/errors` | 输入分析错误和渲染帮助 |

`@gscdump/engine` 拥有分析器、源和期合同. 分析根是共同合同的再出口. 默认的注册会导入每个分析器; 当您需要一个更小的浏览器捆绑时避免它 .

## 分析行

```ts
import { analyzeDecay, analyzeMovers } from '@gscdump/analysis'

const current = [{
  query: 'example query',
  page: 'https://example.com/docs',
  clicks: 40,
  impressions: 1000,
  ctr: 0.04,
  position: 8,
}]
const previous = [{
  query: 'example query',
  page: 'https://example.com/docs',
  clicks: 100,
  impressions: 1000,
  ctr: 0.1,
  position: 4,
}]

const movers = analyzeMovers({ current, previous })
const decay = analyzeDecay({ current, previous })
console.log(movers.declining, decay)
```

比较函数需要一个 `{ current, previous }` 输入对象. 选项是单独的第二个参数. 见 [SEO 指南](https://npmcn.com/package/docs/gscdump-cli/guides/5.seo-analysis.md) 一个完全惊人的例子.

## 来源

使用 `runAnalyzerFromSource` 选择分析器的行或 SQL 计划:

```ts
import { defaultAnalyzerRegistry } from '@gscdump/analysis/registry'
import { createGscApiQuerySource } from '@gscdump/engine-gsc-api'
import { runAnalyzerFromSource } from '@gscdump/engine/analyzer'
import { googleSearchConsole } from 'gscdump'

const client = googleSearchConsole({ accessToken: process.env.GSC_ACCESS_TOKEN! })
const source = createGscApiQuerySource({ client, siteUrl: 'sc-domain:example.com' })
const result = await runAnalyzerFromSource(source, {
  type: 'striking-distance',
  startDate: '2026-08-01',
  endDate: '2026-08-28',
  minImpressions: 100,
}, defaultAnalyzerRegistry)

console.log(result.results)
```

安装 `@gscdump/engine`, (中文(简体) ), `@gscdump/engine-gsc-api`,以及 `gscdump` 以此为例.

十三岁 分析器有行图:

-   `brand`, (中文(简体) ), `cannibalization`, (中文(简体) ), `clustering`, (中文(简体) ), `concentration`
-   `data-detail`, (中文(简体) ), `data-query`, (中文(简体) ), `decay`, (中文(简体) ), `movers`
-   `opportunity`, (中文(简体) ), `seasonality`, (中文(简体) ), `striking-distance`, (中文(简体) ), `trajectory`, (中文(简体) ), `zero-click`

所有30个分析器都有SQL计划. SQL-只分析器需要一个支持其所需能力的源.

| 工厂 | 导入路径 | 投入 |
| --- | --- | --- |
| `createGscApiQuerySource` | `@gscdump/engine-gsc-api` | `{ client, siteUrl }` |
| `createLiveGscSource` | `@gscdump/engine-gsc-api` | `{ siteUrl, getAccessToken }` |
| `createEngineQuerySource` | `@gscdump/engine/source` | `{ engine, ctx }` |
| `createSqliteQuerySource` | `@gscdump/engine-sqlite` | `{ executor, siteId, regex? }` |
| `createInMemoryQuerySource` | `@gscdump/analysis/source` | `{ queryRows }` |
| `createCompositeSource` | `@gscdump/analysis/source` | `{ engine, live, site }` |

综合资料来源, `site` 包含 `oldestDateSynced`, (中文(简体) ), `newestDateSynced`选择 `coveredSpans`。 。 。 . 它在存储覆盖缺失或存储维度无法回答查询时会向Google传送支持的查询. SQL执行总是使用"引擎".

## 报告

报告将分析器合并为受约束的区段. 创建后 `source` 上,运行一个报告,由该来源支持:

```ts
import { defaultReportRegistry, runReport } from '@gscdump/analysis/report'
import { resolveWindow } from '@gscdump/engine/period'
import { getLatestGscDate } from 'gscdump/dates'

const report = defaultReportRegistry.getReport('movers')!
const window = resolveWindow({ preset: 'last-28d', anchor: getLatestGscDate(), comparison: 'prev-period' })
const result = await runReport(report, {
  source,
  analyzers: defaultAnalyzerRegistry,
  ctx: {
    site: 'sc-domain:example.com',
    window,
    params: {},
    registryVersion: defaultReportRegistry.version,
  },
})

console.log(result.sections, result.meta.degraded)
```

见 [报告清单](https://npmcn.com/package/docs/gscdump-cli/api/7.reports.md) 输入和默认值. 如果可选步骤失败, `meta.degraded` 实值 `true`。 。 。 . 所需步骤失败拒绝报告.

使用 `defineReport` 从 `@gscdump/engine/report` 定义您自己的报告.

## DuckDB 和浏览器使用

对于节点,创建引擎源 `createEngineQuerySource({ engine, ctx })` 从 `@gscdump/engine/source`。 。 。 . 上下文供应 `userId` 财务报告和审定财务报表 `siteId`。 。 。 . 节点附件帮助者居住在 `@gscdump/engine/node`。 。 。 .

对于浏览器, 使用 [`@gscdump/engine-duckdb-wasm`](https://npmcn.com/package/%40gscdump/engine-duckdb-wasm/README.md) 附加 Parquet 表格. `analyzeInBrowser` 使用 `query(sql, params, signal?)`、选项、分析参数和分析器登记册. 浏览器分析使用附件表格,如 [ADR-0001 (韩语)](https://npmcn.com/package/docs/adr/0001-browser-engine-uses-attached-tables.md)。 。 。 .

用于 SQLite 和 D1, 使用 [`@gscdump/engine-sqlite`](https://npmcn.com/package/%40gscdump/engine-sqlite/README.md)。 。 。 . 分析器支持取决于源的SQL方言和能力.

## 日期窗口

```ts
import { resolveWindow } from '@gscdump/analysis'

const window = resolveWindow({ preset: 'last-30d', anchor: '2026-08-28', comparison: 'yoy' })
console.log(window.start, window.end, window.comparison)
```

每个预设 `custom` 需要一个 `anchor`: 窗口包括的最后日期. 传递您数据中最新的完整日期, 如 Store 最新的同步日或 `getLatestGscDate()` 从 `gscdump/dates`。 。 。 . `resolveWindow` 从来没有读过钟.

预设 : `last-7d`, (中文(简体) ), `last-28d`, (中文(简体) ), `last-30d`, (中文(简体) ), `last-90d`, (中文(简体) ), `last-180d`, (中文(简体) ), `last-365d`, (中文(简体) ), `mtd`, (中文(简体) ), `qtd`, (中文(简体) ), `ytd`, (中文(简体) ), `last-quarter`,以及 `custom`。 。 。 . 比较: `none`, (中文(简体) ), `prev-period`,以及 `yoy`。 。 。 . `yoy` 将窗口往后移364天,因此每天与同一天的同一天相比.

## 获取预算和产出限制

`limit` 为行盖上一个分析器返回。 它从来不会封住它读的行. 最多读取行计划 `fetchBudget` 每个查询行:默认情况下为2.5万行(1个GSC页),最高可达10万行. `meta.total` 计算每个分析器的每个匹配数, 不只是返回的行. SQL 唯一的分析器是例外. 他们还在报到 `meta.total` 之后 `limit`数字 : `bayesian-ctr`, (中文(简体) ), `bipartite-pagerank`, (中文(简体) ), `change-point`, (中文(简体) ), `ctr-anomaly`, (中文(简体) ), `intent-atlas`, (中文(简体) ), `long-tail`, (中文(简体) ), `query-migration`, (中文(简体) ), `stl-decompose`,以及 `trends`。 。 。 . `meta.coverage` 实值 `{ kind: 'complete' }`,或 `{ kind: 'truncated', fetched }` 当查询到达其获取预算时. 短跑会错过行,因此将其总数和排名视为部分.

## 公共 API

使用上面列出的套件导出 . 下方的文件 `src/` 属于私人性质,可能在没有公共移徙途径的情况下发生变化.

## 许可证

[麻省理工学院](https://npmcn.com/package/LICENSE)

## 常见问题

### @gscdump/analysis 是什么？

GSC分析器——出击-距离,机会,出动者,衰变,品牌,集群,集中,季节性\. 纯以行为主\+ DuckDB-native\.

### 如何安装 @gscdump/analysis？

在项目目录运行 npm install @gscdump/analysis，或使用 pnpm add / yarn add / bun add。

### @gscdump/analysis 支持 TypeScript 吗？

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

### @gscdump/analysis 支持 ESM 还是 CommonJS？

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

### @gscdump/analysis 需要什么版本的 Node\.js？

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

### @gscdump/analysis 可以商用吗？

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

### @gscdump/analysis 的下载量有多少？

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

### @gscdump/analysis 还在维护吗？

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

