# @fusionauth/vue-sdk 中文文档

规范地址：https://npmcn.com/package/%40fusionauth/vue-sdk/

版本：1\.4\.0
npm 元数据更新时间：2026-08-05T19:13:35.757Z
中文译文更新时间：2026-11-15T21:54:21.802Z
软件包许可：Apache

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

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

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

- 包体积（解压后）：154 kB，27 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：vue \>=3\.5\.0
- 首次发布：2023-08-30T21:06:26.962Z
- 最新版本发布：2026-08-05T19:13:35.350Z
- 近 30 天下载量：2231（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 2 个）

## 中文简介

FusionAuth 在不增加风险或分散对您主要应用的注意力的情况下解决了建设基本安全的问题

## 安装

```sh
npm install @fusionauth/vue-sdk
```

也可以使用：`pnpm add @fusionauth/vue-sdk`、`yarn add @fusionauth/vue-sdk`、`bun add @fusionauth/vue-sdk`

## README

Vue 应用程序中使用 FusionAuth 的 SDK .

# 目录

-   [概览](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-overview)
-   [开始](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-getting-started)
    -   [快速启动](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-quickstart)
    -   [安装](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-installation)
-   [使用量](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-usage)
    -   [配置 SDK](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-configuring-the-sdk)
        -   [配置 Nuxt](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-configuring-with-nuxt)
    -   [使用FusionAuth 可编译](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-usefusionauth-composable)
        -   [状态参数](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-state-parameter)
        -   [DPOP 模式](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-dpop-mode)
    -   [UI 组件](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-ui-components)
        -   [保护内容](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-protecting-content)
        -   [预建按钮](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-pre-built-buttons)
-   [文档](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-documentation)
-   [已知问题](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-known-issues)
-   [释放](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-releases)
-   [升级政策](https://npmcn.com/package/%40fusionauth/vue-sdk/#readme-upgrade-policy)

# 概览

此 SDK 提供了与 FusionAuth 集成的有用方法和反应值来帮助自动管理您 Vue app 中的认证状态.

您的用户将被发送到 FusionAuth 的主题主机登录页面和 然后登录。 之后,他们被送回你的Vue申请.

认证成功后, 以下安全, HTTP 唯一的 cookie 将设置 :

-   `app.at` - 一个奥奥特人 [访问 脚本](https://fusionauth.io/docs/v1/tech/oauth/tokens#access-token)
    
-   `app.rt` - 一个 [刷新 脚本](https://fusionauth.io/docs/v1/tech/oauth/tokens#refresh-token) 用于获得新的 `app.at`。只有在 在您的 FusionAuth 实例中启用了刷新符号 .
    

访问令牌可以提交API,以授权请求和 刷新符可以用来获取新的访问符.

与这个SDK有两种互动方式:

1.  通过托管执行 OAuth 令牌交换并满足 [fusionAuth Web SDKs的服务器代码要求](https://github.com/FusionAuth/fusionauth-javascript-sdk-express#server-code-requirements)。 。 。 .
2.  通过使用您 FusionAuth 实例中托管的服务器, 即不写入您的服务器代码 .

如果您正在托管自己的服务器, 请查看 [服务器代码要求](https://github.com/FusionAuth/fusionauth-javascript-sdk-express#server-code-requirements)。 。 。 .

您可以使用此库对抗 FusionAuth 或任何 OIDC 版本 符合要求的身份服务器 .

## 开始

如果您是新到 Vue 开发, 您可能想要从快速启动指南开始 。 如果您已经熟悉 Vue 开发, 请跳到安装区域 .

### 快速启动

见 [FusionAuth Vue 快速启动](https://fusionauth.io/docs/quickstarts/quickstart-javascript-vue-web) 用于使用 FusionAuth 和 Vue 的完整教程.

### 安装

国家预防机制:

```bash
npm install @fusionauth/vue-sdk
```

亚伦:

```bash
yarn add @fusionauth/vue-sdk
```

## 使用量

### 配置 SDK

配置并初始化 `FusionAuthVuePlugin` 当你创建您的 Vue 应用程序时 :

```typescript
import { createApp } from 'vue';
import FusionAuthVuePlugin, { type FusionAuthConfig } from '@fusionauth/vue-sdk';

const config: FusionAuthConfig = {
  clientId: "", // Your app's FusionAuth client id
  serverUrl: "", // The url of the server that performs the token exchange
  redirectUri: "", // The URI that the user is directed to after the login/register/logout action
  shouldAutoFetchUserInfo: true, // Automatically fetch userInfo when logged in. Defaults to false.
  shouldAutoRefresh: true, // Enables automatic token refresh. Defaults to false.
  onRedirect: (state?: string) => { }, // Optional callback invoked upon redirect back from login or register.
  // useDpop: true, // Opt-in to DPoP mode. See "DPoP Mode" below. Defaults to false.
}

const app = createApp(App);

app.use(FusionAuthVuePlugin, config);
app.mount('#app')
```

如果您想要使用前置的按钮, 请不要忘记导入 cs 文件 :

```typescript
import '@fusionauth/vue-sdk/dist/style.css';
```

#### 配置为 [坚果](https://nuxt.com/)

如果你在Nuxt应用软件中使用SDK,请通过 [`useCookie`](https://nuxt.com/docs/api/composables/use-cookie) 在您的插件定义中可堆入配置对象.

```typescript
import { useCookie } from "#app";

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.use(FusionAuthVuePlugin, {
    ...config
    nuxtUseCookie: useCookie,
  });
});
```

##### 定义您 nuxt 插件的其他方式

使用 `createFusionAuth`,SDK可以更灵活地配置.

```typescript
export default defineNuxtPlugin({
  setup(nuxtApp) {
    const fusionauth = createFusionAuth(config);   
    nuxtApp.vueApp.use(FusionAuthVuePlugin, { instance: fusionauth })
    return {
      provide: { fusionauth }
    };
  },
})
```

### `useFusionAuth` 可堆叠

您可以使用 SDK 与 SDK 交互 `useFusionAuth`,该杠杆 [Vue 组成 API](https://vuejs.org/guide/reusability/composables)。 。 。 . 查看 [aPI 完整文档](https://github.com/FusionAuth/fusionauth-javascript-sdk/tree/main/packages/sdk-vue/docs/modules/composables_useFusionAuth.md)

```html
<script setup lang="ts">
import { computed } from 'vue';
import { useFusionAuth } from "@fusionauth/vue-sdk";

const {
  isLoggedIn,
  userInfo,
  isFetchingUserInfo,
  login,
  register,
  logout
} = useFusionAuth();

const welcomeMessage = computed(() => {
  const name = userInfo.value?.given_name
  return name 
    ? 'Welcome!'
    : `Welcome ${userInfo.value.given_name}!`;
});
</script>

<template>
  <p>{{ welcomeMessage }}</p>

  <div v-if="isLoggedIn">
    <p v-if="isFetchingUserInfo">
      Loading...
    </p>
    <button @click="logout()">Logout</button>
  </div>

  <div v-if="!isLoggedIn">
    <button @click="login()">Login</button>
    <p>or</p>
    <button @click="register()">Register</button>
  </div>
</template>
```

#### 状态参数

这个 `login` 财务报告和审定财务报表 `register` 函数接受可选字符串参数: `state`,将返回到可选 `onRedirect` 指定您的回调 `FusionAuthConfig`。虽然您可以传递您想要的状态参数的值,但它通常用于在重新定向到登录或注册之前显示用户在哪个页面,这样用户可以在成功认证后返回该位置.

#### DPOP 模式

默认情况下,SDK会调用HttpOnly cookie中存储符号的Hosted后端(`useDpop: false`,默认值). 在DPoP模式下,SDK转而直接调用FusionAuth端点,并绑定到浏览器中生成的私人密钥上. 通过设置启用 `useDpop: true` 打开 `FusionAuthConfig`数字 :

```typescript
const config: FusionAuthConfig = {
  clientId: "",
  redirectUri: "",
  serverUrl: "",
  useDpop: true, // Opt-in to DPoP mode.
  dpopTokenStorage: 'localStorage', // 'localStorage' (default, persists across reloads) or 'memory'.
}
```

何时 `useDpop: true`, (中文(简体) ), `useFusionAuth()` 额外返回 `dpopFetch`, (中文(简体) ), `generateProof`,以及 `getAccessToken`这些是: `undefined` 何时 `useDpop` 实值 `false` 或未设.

```html
<script setup lang="ts">
import { useFusionAuth } from "@fusionauth/vue-sdk";

const { dpopFetch, generateProof, getAccessToken } = useFusionAuth();

const response = await dpopFetch('https://api.example.com/data', { method: 'GET' });

const accessToken = getAccessToken();
const proof = await generateProof('https://api.example.com/data', 'GET', accessToken);
// axios.get('https://api.example.com/data', {
//   headers: { Authorization: `DPoP ${accessToken}`, DPoP: proof }
// });
</script>
```

在DPoP模式下,登入/注册回转的回回程会同步完成(在应用程序重新装入之前没有Hosted后端设置 cookie). `onRedirect` 仅在 `isLoggedIn` 并充分更新了信使,所以它是在后登录导航中勾通的可靠地:

```typescript
const config: FusionAuthConfig = {
  // ...
  useDpop: true,
  onRedirect: () => router.push('/account'),
}
```

### UI 组件

#### 保护内容

这个 `RequireAuth` 财务报告和审定财务报表 `RequireAnonymous` 可用于基于认证和授权限制内容.

```html
<template>
  <RequireAuth :with-role="['ADMIN', 'SUPER-ADMIN']">
    <!-- only displays for users with specifed role -->
    <button>Delete user</button>
  </RequireAuth>
</template>

<template>
  <RequireAnonymous>
    <!-- content for unauthenticated users -->
  </RequireAnonymous>
</template>
```

#### 预建按钮

有三个预设的按钮被配置用于执行 登录/登录/登记。 它们可以放在你的应用程序的任何地方 没错.

```html
<template>
  <FusionAuthLoginButton />
  <FusionAuthLogoutButton />
  <FusionAuthRegisterButton />
</template>

<style>
  :root {
    --fusionauth-button-background-color: #096324;
    --fusionauth-button-text-color: #fff;
  }
</style>
```

使用 CSS 变量,您可以自定义按钮来匹配您的应用程序样式 .

## 文档

[完整的图书馆文件](https://github.com/FusionAuth/fusionauth-javascript-sdk/tree/main/packages/sdk-vue/docs)

这些文件是用 [类型doc](https://typedoc.org/) 并配置为 [类型doc- 插件- 标记下](https://www.npmjs.com/package/typedoc-plugin-markdown)。 。 。 .

在此读取中使用回击代码 。 这个readme包含在FusionAuth网站中,回击者以那里最好的光来显示代码.

## 已知问题

使用 `shouldAutoRefresh` 如果插件实例在服务器上被即时显示, Nuxt 可能会导致第一次刷新尝试以 403 失败 。 这可能是因为FusionAuth的授权令牌是httpOnly而未出现在服务器发送的请求中. 随后由 SDK 自动刷新排队的刷新请求应该成功 .

你可能更喜欢引用 `initAutoRefresh` 从 [`app:beforeMount` 钩子](https://nuxt.com/docs/api/advanced/hooks),它只运行客户端.

```typescript
defineNuxtPlugin({
  setup: (nuxtApp) => {
    const fusionauth = createFusionAuth({
      ...config,
      shouldAutoRefresh: false, // is false by default
    });   
    nuxtApp.vueApp.use(FusionAuthVuePlugin, { instance: fusionauth })
    return {
      provide: { fusionauth }
    };
  },
  hooks: {
    "app:beforeMount"() {
      const { $fusionauth } = useNuxtApp();
      $fusionauth.initAutoRefresh();
    },
  }
})
```

## 释放

此软件包通过 GitHub 动作发布 .

## 升级政策

此库可定期接收带有错误修正、安全补丁、测试、代码样本或文档更改的更新.

这些版本也可能更新依赖性,语言引擎和操作系统,因为我们将遵循图书馆使用的基本技术的贬值和日出政策.

这意味着在依赖性(如语言,框架,或操作系统)被其维护者贬值后,这个库也会被我们贬值,最终可能会被更新以使用更新的版本.

## 常见问题

### @fusionauth/vue-sdk 是什么？

FusionAuth 在不增加风险或分散对您主要应用的注意力的情况下解决了建设基本安全的问题

### 如何安装 @fusionauth/vue-sdk？

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

### @fusionauth/vue-sdk 支持 TypeScript 吗？

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

### @fusionauth/vue-sdk 支持 ESM 还是 CommonJS？

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

### @fusionauth/vue-sdk 可以商用吗？

@fusionauth/vue-sdk 使用 Apache 许可。声明的许可为 Apache，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @fusionauth/vue-sdk 的下载量有多少？

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

### @fusionauth/vue-sdk 还在维护吗？

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