# @cardog/corgi 中文文档

规范地址：https://npmcn.com/package/%40cardog/corgi/

版本：2\.0\.4
npm 元数据更新时间：2026-04-15T03:22:54.444Z
中文译文更新时间：2026-11-09T04:49:30.627Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：26.8 MB，25 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16\.0\.0
- 运行依赖：2 个
- peer 依赖：sql\.js ^1\.8\.0
- 首次发布：2025-05-27T21:00:03.847Z
- 最新版本发布：2026-04-15T03:22:54.338Z
- 近 30 天下载量：12616（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 10 个）

## 中文简介

快速,离线的VIN为Node.js,浏览器,和Cloudflare Workers进行解码. 由NHTSA VPIC数据库提供动力.

## 安装

```sh
npm install @cardog/corgi
```

也可以使用：`pnpm add @cardog/corgi`、`yarn add @cardog/corgi`、`bun add @cardog/corgi`

## README

# Corgi VIN 解码器

![Cardog](https://npmcn.com/package/%40cardog/corgi/cardog-icon.png)      ![Corgi - Fast VIN Decoder](https://npmcn.com/package/%40cardog/corgi/corgi.png)

**快速,离线的VIN为Node.js,浏览器,和Cloudflare Workers进行解码.**  
由NHTSA VPIC数据库提供动力.

  

[![npm version](https://badge.fury.io/js/%40cardog%2Fcorgi.svg)](https://www.npmjs.com/package/@cardog/corgi) [![Downloads](https://img.shields.io/npm/dm/@cardog/corgi.svg)](https://www.npmjs.com/package/@cardog/corgi) [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/) [![License: ISC](https://img.shields.io/badge/License-ISC-yellow.svg)](https://opensource.org/licenses/ISC) [![Cardog API](https://img.shields.io/badge/Cardog-API-orange.svg)](https://docs.cardog.app/)

> **需要的不只是基本的VIN解码吗?** 看看这个 [车狗 API](https://docs.cardog.app/) 用于综合车辆数据,包括市场价值、安全回顾、所有者费用等.

## 安装

```bash
npm install @cardog/corgi
```

## 快速启动

```typescript
import { createDecoder } from "@cardog/corgi";

const decoder = await createDecoder();
const result = await decoder.decode("KM8K2CAB4PU001140");

console.log(result.components.vehicle);
// { make: 'Hyundai', model: 'Kona', year: 2023, ... }

await decoder.close();
```

## 平台支持

### 节点.js

```typescript
import { createDecoder } from "@cardog/corgi";

const decoder = await createDecoder();
const result = await decoder.decode("1HGCM82633A123456");

// Custom database path
const decoder = await createDecoder({
  databasePath: "/path/to/vpic.lite.db",
});
```

### 浏览器

```typescript
import { createDecoder } from "@cardog/corgi/browser";

const decoder = await createDecoder({
  databasePath: "https://corgi.cardog.io/vpic.lite.db.gz",
  runtime: "browser",
});
```

### 云花板工人(D1)

```typescript
import { createDecoder, initD1Adapter } from "@cardog/corgi";

initD1Adapter(env.D1_DATABASE);

const decoder = await createDecoder({
  databasePath: "D1",
  runtime: "cloudflare",
});
```

## 配置

```typescript
const decoder = await createDecoder({
  databasePath: "./custom/path.db",
  forceFresh: true,
  defaultOptions: {
    includePatternDetails: true,
    includeRawData: false,
    confidenceThreshold: 0.8,
    includeDiagnostics: true,
  },
});

// Per-decode options
const result = await decoder.decode("VIN12345678901234", {
  modelYear: 2024,
  includePatternDetails: true,
});
```

## 反应结构

```typescript
interface DecodeResult {
  vin: string;
  valid: boolean;

  components: {
    vehicle?: {
      make: string;
      model: string;
      year: number;
      series?: string;
      bodyStyle?: string;
      driveType?: string;
      fuelType?: string;
      doors?: string;
    };
    wmi?: {
      manufacturer: string;
      make: string;
      country: string;
      region: string;
    };
    plant?: {
      country: string;
      city?: string;
      code: string;
    };
    engine?: {
      model?: string;
      cylinders?: string;
      displacement?: string;
      fuel?: string;
    };
    modelYear?: {
      year: number;
      source: string;
      confidence: number;
    };
    checkDigit?: {
      isValid: boolean;
      expected?: string;
      actual: string;
    };
  };

  errors: DecodeError[];
  metadata?: DiagnosticInfo;
  patterns?: PatternMatch[];
}
```

## 处理错误

```typescript
import { ErrorCode } from "@cardog/corgi";

const result = await decoder.decode("INVALID_VIN");

if (!result.valid) {
  result.errors.forEach((error) => {
    switch (error.code) {
      case ErrorCode.INVALID_CHECK_DIGIT:
      case ErrorCode.INVALID_LENGTH:
      case ErrorCode.WMI_NOT_FOUND:
        console.log(error.message);
    }
  });
}
```

## 国 际

```bash
npx @cardog/corgi decode 1HGCM82633A123456
npx @cardog/corgi decode 1HGCM82633A123456 --patterns --format json
npx @cardog/corgi --help
```

* * *

## 建筑

### VIN 结构

车辆识别号码(VIN)是分配给每辆为道路用途而制造的车辆的17个特征标识。 该结构由ISO 3779定义,并遵循此格式:

```
Position:  1-3    4-8      9       10      11      12-17
           WMI    VDS      Check   Year    Plant   VIS
           │      │        │       │       │       │
           │      │        │       │       │       └─ Sequential production number
           │      │        │       │       └───────── Assembly plant code
           │      │        │       └─────────────── Model year (A-Y, 1-9, excluding I,O,Q,U,Z,0)
           │      │        └─────────────────────── Check digit (0-9, X)
           │      └──────────────────────────────── Vehicle attributes (model, body, engine, etc.)
           └─────────────────────────────────────── World Manufacturer Identifier
```

**WMI( 方案 1-3)**: 确定制造商。 第一个字符表示国家/地区,第二个表示制造商,第三个表示车辆类型或制造部门.

**VDS(提案4-8)**:车辆说明科. 制造商定义的属性包括型号,车体样式,发动机类型,和约束系统等.

**检查 Digit( 选项 9)**:使用加权算法验证VIN完整性. 在北美出售的所有车辆均需购买.

**示范年份(方案10)**:编码了模型年份. 使用字母A-Y(不包括I,O,Q,U,Z)和数字1-9在一个30年周期中.

**植物代码(11号)**:确定组装厂. 制造商专用编码.

**VIS(提案12-17)**:车辆识别仪科. 系列生产编号在模型年份和厂内独有.

### 检查数字算法

支票数字(位置9)的计算方法是:

1.  指定每个字符一个值(A=1,B=2,.,N=5,P=7,.,0-9=面值)
2.  以重量乘以每个位置: `[8,7,6,5,4,3,2,10,0,9,8,7,6,5,4,3,2]`
3.  总结所有产品和取用modulo 11
4.  结果10="X",否则数字本身

### 模拟年份解码

每49 CFR 565.15, 每30年示范年代码周期:

| 代码 | 年份 |
| --- | --- |
| A 类 | 1980, 2010 (英语) |
| 页:1 | 1981, 2011 (英语) |
| . | . |
| 页:1 | 1999年,第2029页 |
| Y | 2000, 2030 (英语) |
| 1个 | 2001, 2031 (英语) |
| . | . |
| 第9条 | 2009, 2039 (英语) |

字符一,O,Q被排除在所有VIN职位之外. U,Z,和0被另外排除在10号位置之外.

* * *

## 数据库

### VPIC 列表

Corgi使用NHTSA vPIC(汽车产品信息目录)数据库的优化子集. 数据库被压缩并被捆绑,用于离线操作.

**规格:**

-   资料来源:NHTSA VPIC
-   格式: SQLite (优化)
-   压缩:~20MB (gzip)
-   未压缩 :~40MB
-   最新情况:每月通过自动化管道

### 托管数据库

Cardog维持一个公共CDN

**基础 URL :** `https://corgi.cardog.io`

| 文件 | 说明 |
| --- | --- |
| `vpic.lite.db.gz` | 数据库(gzip) |
| `vpic.lite.db.bz2` | 数据库(bzip2) |
| `vpic.lite.db.xz` | 数据库 (xz) |
| `vpic.lite.db.zst` | 数据库 (zstd) |
| `vpic.lite.json` | 元数据(版本、校验和数、记录计数) |
| `vpic.lite.sha256` | SHA256 检查和 |

还提供日期档案: `vpic_lite_YYYYMMDD.db.gz`

### 本地缓存

-   **节点.js**数字 : `~/.corgi-cache/vpic.lite.db`
-   **浏览器**: 从提供的 URL 装入
-   **云雾花**由D1管理

```typescript
import { getDatabasePath } from "@cardog/corgi";

const dbPath = await getDatabasePath();
const decoder = await createDecoder({ forceFresh: true }); // Force refresh
```

* * *

## 出口

```typescript
// Core
import { createDecoder, quickDecode, getDatabasePath } from "@cardog/corgi";

// Types
import type { DecodeResult, DecodeOptions, DecoderConfig } from "@cardog/corgi";

// Enums
import { ErrorCode, ErrorCategory, BodyStyle } from "@cardog/corgi";

// Adapters
import { initD1Adapter } from "@cardog/corgi/d1-adapter";
import { createDecoder } from "@cardog/corgi/browser";
```

* * *

## 车狗 API

**Corgi 提供快速的离线VIN解码** - 但是,如果你需要全面的车辆情报 [车狗 API](https://docs.cardog.app/) 提供更多的:

-   **丰富VIN解码** - Corgi 解码加详细变异数据、规格和特征
-   **市场分析** - 定价见解、市场趋势和可比车辆清单
-   **安全回顾** - NHTSA和Transport Canada召回由VIN检索或制作/模型的数据
-   **车辆清单** - 以过滤器搜索活动列表,以了解制作、模型、价格、位置
-   **EV 数据** - 充电站、效率评级和范围估计

```bash
# Decode a VIN with full vehicle data
curl "https://api.cardog.io/v1/vin/1HGCM82633A123456" \
  -H "x-api-key: your-api-key"
```

[在 docs.cardog.app 开始](https://docs.cardog.app/)

* * *

## 许可证

ISC 许可证 - 见 [自由主义](https://npmcn.com/package/%40cardog/corgi/LICENSE) 详细情况.

## 常见问题

### @cardog/corgi 是什么？

快速,离线的VIN为Node\.js,浏览器,和Cloudflare Workers进行解码\. 由NHTSA VPIC数据库提供动力\.

### 如何安装 @cardog/corgi？

在项目目录运行 npm install @cardog/corgi，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：sql\.js（^1\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 corgi，可以用 npx corgi 直接运行。

### @cardog/corgi 支持 TypeScript 吗？

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

### @cardog/corgi 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cardog/corgi 需要什么版本的 Node\.js？

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

### @cardog/corgi 可以商用吗？

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

### @cardog/corgi 的下载量有多少？

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

### @cardog/corgi 还在维护吗？

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