@gscdump/analysis

中文文档
7.15.0发布于 2026/11/16MITTypeScriptES Module构建来源已验证近 30 天下载 9025

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

中文使用文档
文档目录10 节
  1. 安装
  2. 选择导出
  3. 分析行
  4. 来源
  5. 报告
  6. DuckDB 和浏览器使用
  7. 日期窗口
  8. 获取预算和产出限制
  9. 公共 API
  10. 许可证

@gscdump/ 分析

npm version npm downloads license

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

安装

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 拥有分析器、源和期合同. 分析根是共同合同的再出口. 默认的注册会导入每个分析器; 当您需要一个更小的浏览器捆绑时避免它 .

分析行

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 指南 一个完全惊人的例子.

来源

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

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 上,运行一个报告,由该来源支持:

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)

见 报告清单 输入和默认值. 如果可选步骤失败, meta.degraded 实值 true。 。 。 . 所需步骤失败拒绝报告.

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

DuckDB 和浏览器使用

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

对于浏览器, 使用 @gscdump/engine-duckdb-wasm 附加 Parquet 表格. analyzeInBrowser 使用 query(sql, params, signal?)、选项、分析参数和分析器登记册. 浏览器分析使用附件表格,如 ADR-0001 (韩语)。 。 。 .

用于 SQLite 和 D1, 使用 @gscdump/engine-sqlite。 。 。 . 分析器支持取决于源的SQL方言和能力.

日期窗口

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/ 属于私人性质,可能在没有公共移徙途径的情况下发生变化.

许可证

麻省理工学院

版本与发布记录

@gscdump/analysis 共发布 265 个版本,首次发布于 2026/04/27;过去 12 个月发布了 265 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
7.15.0latest2026/11/16今天
7.14.02026/11/16今天
7.13.22026/11/151 天前
7.13.12026/11/152 天前
7.13.02026/11/124 天前
7.12.12026/11/116 天前

关于 @gscdump/analysis 的常见问题

@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 和提交记录判断。