# @fingerprint/vue 中文文档

规范地址：https://npmcn.com/package/%40fingerprint/vue/

版本：2\.1\.0
npm 元数据更新时间：2026-10-28T09:37:05.935Z
中文译文更新时间：2026-11-14T18:47:52.819Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：52.5 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：vue ^3\.1
- 首次发布：2026-04-16T13:09:42.271Z
- 最新版本发布：2026-10-28T09:37:05.318Z
- 近 30 天下载量：5407（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

指纹 Vue 3 SDK

## 安装

```sh
npm install @fingerprint/vue
```

也可以使用：`pnpm add @fingerprint/vue`、`yarn add @fingerprint/vue`、`bun add @fingerprint/vue`

## README

[![Fingerprint logo](https://fingerprintjs.github.io/home/resources/logo_dark.svg)](https://fingerprint.com/)

[![Build status](https://github.com/fingerprintjs/vue/actions/workflows/ci.yml/badge.svg)](https://github.com/fingerprintjs/vue/actions/workflows/ci.yml) [![Release status](https://github.com/fingerprintjs/vue/actions/workflows/release.yml/badge.svg)](https://github.com/fingerprintjs/vue/actions/workflows/release.yml) [![Current NPM version](https://img.shields.io/npm/v/@fingerprint/vue.svg)](https://www.npmjs.com/package/@fingerprint/vue) [![Monthly downloads from NPM](https://img.shields.io/npm/dm/@fingerprint/vue.svg)](https://www.npmjs.com/package/@fingerprint/vue) [![MIT license](https://img.shields.io/:license-mit-blue.svg)](https://opensource.org/licenses/MIT) [![Discord server](https://img.shields.io/discord/852099967190433792?style=logo&label=Discord&logo=Discord&logoColor=white)](https://discord.gg/39EpE2neBg)

# 指纹 Vue 3 SDK

[指纹](https://fingerprint.com/) 是一个能提供行业领导精确度的设备智能平台.

指纹 Vue SDK 是方便的整合方式 [指纹](https://fingerprint.com/) 输入您的 Vue 3 应用程序。 它支持指纹JavaScript代理的所有能力.

## 所需资源

-   对于打字机用户:打字机4.5或以上
-   Vue 3.1级或以上
-   对于 Nuxt 用户: Nuxt 3.0 以上

这个软件包是商业的 [指纹平台](https://fingerprint.com/)。它与可用源不相容 [指纹JS库](https://github.com/fingerprintjs/fingerprintjs)。学习更多关于 [指纹和指纹之间的区别](https://fingerprint.com/github/)。 。 。 .

## 安装

要安装插件运行 :

```shell
yarn add @fingerprint/vue
```

或者说:

```shell
npm install @fingerprint/vue
```

```shell
pnpm add @fingerprint/vue
```

## 开始

为了识别访客,你需要一个指纹账户(你) 能够 [免费报名](https://dashboard.fingerprint.com/signup/)) (中文(简体) ). 获取您的 API 密钥并启动 [指纹文件](https://docs.fingerprint.com/docs/quick-start-guide)。 。 。 .

在您的 Vue 应用程序中注册插件 .

-   设置 a [区域](https://docs.fingerprint.com/docs/regions) 如果您在注册时选择了非全球区域.
-   设定 `endpoints` 如果你使用我们的代理集成 [提高准确性和有效性](https://docs.fingerprint.com/docs/protecting-the-javascript-agent-from-adblockers) 游客身份证明.

```typescript
import { createApp } from 'vue';
import App from './App.vue';
import { FingerprintPlugin } from '@fingerprint/vue';

const app = createApp(App);

app
  .use(FingerprintPlugin, {
    apiKey: '<your-public-api-key>',
    endpoints: "https://metrics.yourwebsite.com",
    region: 'eu',
  })
  .mount('#app');
```

您可以使用配置 API 、 选项 API 或 Mixins 的插件, 无论是否 Nuxt 。 见下文使用实例.

## 组成 API

插件提供了一个 `useVisitorData` 用于识别访客的可混杂性 :

```vue
<script setup>
import { useVisitorData } from '@fingerprint/vue';
import { watch } from 'vue';

const { data, error, isLoading, isFetched, getData } = useVisitorData(
  // Set to false to prevent fetching data on mount
  { immediate: false }
);

watch(data, (currentData) => {
  if (currentData) {
    // Do something with the data
    console.log(currentData.visitor_id);
  }
});
</script>

<template>
  <button @click='getData()'>Get visitor data</button>
</template>
```

这个 `getData()` 函数丢入出错。 您可以使用尝试/ 捕获或检查 `error` 参考:

```vue
<script setup>
import { useVisitorData } from '@fingerprint/vue';

const { data, error, isLoading, isFetched, getData } = useVisitorData();

async function handleClick() {
  try {
    const result = await getData();
    console.log(result.visitor_id);
  } catch (err) {
    console.error('Identification failed:', err);
  }
}
</script>
```

## 选项 API

插件注入 a `$fingerprint` 用于识别访客的组件中的对象 :

```vue
<script lang='ts'>
import { defineComponent } from 'vue';

export default defineComponent({
  methods: {
    async getVisitorData() {
      const result = await this.$fingerprint.getVisitorData();
      // Do something with result
      console.log(result.visitor_id);
    }
  }
});
</script>

<template>
  <button @click='getVisitorData'>Get visitor data</button>
</template>
```

### 混合

为方便起见,我们还提供一种组合,处理所有查询状态:

```vue
<script lang='ts'>
import { defineComponent } from 'vue';
import { fingerprintGetVisitorDataMixin } from '@fingerprint/vue';

export default defineComponent({
  mixins: [fingerprintGetVisitorDataMixin],
  async mounted() {
    // You can also fetch data on mount
    // await this.$getVisitorData();
  }
});
</script>

<template>
  <div>
    <button @click='$getVisitorData'>
      Get visitor data
    </button>
    <span v-if='visitorData.isLoading'>
      Loading...
    </span>
    <span v-else-if='visitorData.error'>
      Error: {{ visitorData.error }}
    </span>
    <span v-else-if='visitorData.isFetched'>
      Visitor ID: {{ visitorData.data.visitor_id }}
    </span>
  </div>
</template>
```

## 坚果

插件与 Nuxt 在框外工作, 然而, 您只需要在客户端注册它 .

```typescript
// plugins/fingerprint.client.ts
import { defineNuxtPlugin, useRuntimeConfig } from '#app';
import { FingerprintPlugin } from '@fingerprint/vue';

export default defineNuxtPlugin((nuxtApp) => {
  const config = useRuntimeConfig();

  nuxtApp.vueApp.use(FingerprintPlugin, {
    apiKey: config.public.API_KEY,
    endpoints: "https://metrics.yourwebsite.com",
    region: 'eu',
  });
});
```

```typescript
// nuxt.config.ts
import { defineNuxtConfig } from 'nuxt';

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      // Inject Fingerprint API key
      API_KEY: process.env.API_KEY,
    },
  }
});
```

见 [实例 Nuxt 应用程序](https://npmcn.com/package/%40fingerprint/vue/examples/nuxt-v3-example) 更多细节.

## 链接和标记信息

这个 `visitor_id` 由指纹识别提供,与您已经了解的用户信息相结合,例如账户ID,订单ID等,尤其有用. 更多地了解《公约》的各种应用 `linkedId` 财务报告和审定财务报表 `tags`,参见 [链接和标记信息](https://docs.fingerprint.com/docs/tagging-information)。 。 。 .

将你的数据与访问者身份相连接 `linkedId` 或者说 `tags` 参数 `useVisitorData()` 可堆叠或 `getData()` 函数 :

```vue
<script setup>
import { useVisitorData } from '@fingerprint/vue';

const { data, error, isLoading, getData } = useVisitorData({
  linkedId: 'user_1234',
  tags: {
    userAction: 'login',
    analyticsId: 'UA-5555-1111-1',
  },
})
</script>

<template>
<!--...-->
</template>
```

> \[注\] 这个 `tag` 选项为偏好 `tags`。 。 。 . `tag` 仍然有效,但如果两者都提供, `tags` 以优先为准.

## 直接代理准入

对于高级用户,您可以访问全部 `@fingerprint/agent` 使用 `Fingerprint` 名称空间导出 :

```typescript
import { Fingerprint } from '@fingerprint/vue';

// Use agent types
type Result = Fingerprint.GetResult;
type Options = Fingerprint.GetOptions;

// Or call start() directly
const agent = Fingerprint.start({ apiKey: '...' });
const result = await agent.get();
```

## 缓存

指纹使用费按API呼叫计费. 为了避免不必要的API呼叫 [缓存识别结果](https://docs.fingerprint.com/docs/caching-visitor-information)。 。 。 .

缓存默认已禁用, 与基础对齐 [JavaScript 代理 v4 默认](https://docs.fingerprint.com/reference/js-agent-v4-start-function#cache)。为了允许缓存,通过 [`cache` 开始选项](https://docs.fingerprint.com/reference/js-agent-v4-start-function#cacheconfig)数字 :

```typescript
app.use(FingerprintPlugin, {
  apiKey: '<your-public-api-key>',
  cache: {
    storage: 'sessionStorage', // or 'localStorage' or 'agent'
    duration: 'optimize-cost', // or 'aggressive' or a number in seconds
  },
});
```

## V1.x的迁移

2.0版本将基础指纹代理从v3升级到v4,并引入了多处断裂变化. 见 [移徙指南](https://npmcn.com/package/%40fingerprint/vue/docs/migration-v1-to-v2.md) 详细指示和 [JavaScript 代理 v3 到 v4 迁移指南](https://docs.fingerprint.com/docs/migrating-from-v3-to-v4) 基础剂改变.

## 文档

详细文档可在 [API 参考](https://fingerprintjs.github.io/vue)。 。 。 .

## 版本支持

| SDK 主要版本 | JS代理版本 | 状态 | 支持结束 |
| --- | --- | --- | --- |
| v2.x (当前) | [页:1](https://docs.fingerprint.com/reference/js-agent) | 支助 | \- 说吧 |
| v1.x (韩语) | [页:1](https://docs.fingerprint.com/reference/v3/javascript-agent) | 已折旧(仅限安全处理)。 见 [移徙指南](https://docs.fingerprint.com/docs/vuejs#migration-guide-for-vue-sdk-v2-0-0)。 。 。 . | 待定 |

## 支助和反馈

提问或提供反馈,使用 [问题](https://github.com/fingerprintjs/vue/issues)如果您需要私人支援,请发电子邮件至 `oss-support@fingerprint.com`如果你想有一个类似的 Vue 包装器 [来源可用指纹JS](https://github.com/fingerprintjs/fingerprintjs),考虑在主要方面创建一个问题 [指纹JS仓库](https://github.com/fingerprintjs/fingerprintjs/issues)。 。 。 .

## 实例

您可以在 [实例](https://npmcn.com/package/%40fingerprint/vue/examples) 目录 :

-   [SPA 应用程序](https://npmcn.com/package/%40fingerprint/vue/examples/spa-v3-example)
-   [Nuxt 应用程序](https://npmcn.com/package/%40fingerprint/vue/examples/nuxt-v3-example)

## 许可证

本项目根据以下规定获得许可证: [麻省理工学院许可证](https://github.com/fingerprintjs/vue/blob/main/LICENSE)。 。 。 .

## 常见问题

### @fingerprint/vue 是什么？

指纹 Vue 3 SDK

### 如何安装 @fingerprint/vue？

在项目目录运行 npm install @fingerprint/vue，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fingerprint/vue 支持 TypeScript 吗？

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

### @fingerprint/vue 支持 ESM 还是 CommonJS？

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

### @fingerprint/vue 可以商用吗？

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

### @fingerprint/vue 的下载量有多少？

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

### @fingerprint/vue 还在维护吗？

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