# @fusionauth/react-sdk 中文文档 规范地址：https://npmcn.com/package/%40fusionauth/react-sdk/ 版本：2\.7\.0 npm 元数据更新时间：2026-08-05T19:13:51.088Z 中文译文更新时间：2026-11-15T18:39:58.774Z 软件包许可：Apache 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40fusionauth/react-sdk 原文对照：https://npmcn.com/package/%40fusionauth/react-sdk/?lang=original 项目主页：https://github.com/FusionAuth/fusionauth-javascript-sdk/tree/main/packages/sdk-react#readme 源码仓库：https://github.com/FusionAuth/fusionauth-javascript-sdk ## 关键信息（来自 npm 元数据） - 包体积（解压后）：173 kB，7 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - Node.js 要求：\>=18\.0\.0 - 运行依赖：1 个 - peer 依赖：react \>=18\.2\.0，react-dom \>=18\.2\.0 - 首次发布：2023-01-18T22:12:39.256Z - 最新版本发布：2026-08-05T19:13:50.717Z - 近 30 天下载量：61276（2026-10-16 至 2026-11-14，npm 官方下载统计） - 已发布版本数：25（近 12 个月 3 个） ## 中文简介 FusionAuth 在不增加风险或分散对您主要应用的注意力的情况下解决了建设基本安全的问题 ## 安装 ```sh npm install @fusionauth/react-sdk ``` 也可以使用：`pnpm add @fusionauth/react-sdk`、`yarn add @fusionauth/react-sdk`、`bun add @fusionauth/react-sdk` ## README 用于在反应应用程序中使用 FusionAuth 的 SDK . # 目录 - [概览](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-overview) - [开始](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-getting-started) - [快速启动](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-quickstart) - [安装](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-installation) - [配置](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-configuration) - [配置下一个 JS](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-configuration-with-nextjs) - [使用量](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-usage) - [使用FusionAuth系统](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-usefusionauth) - [状态参数](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-state-parameter) - [保护内容](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-protecting-content) - [UI 组件](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-ui-components) - [DPOP 模式](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-dpop-mode) - [已知问题](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-known-issues) - [文档](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-documentation) - [格式化](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-formatting) - [释放](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-releases) - [升级政策](https://npmcn.com/package/%40fusionauth/react-sdk/#readme-upgrade-policy) # 概览 此 SDK 管理您 React app 的认证状态, 并提供登录、 注册和登录用户的功能 。 它可以很容易的配置来自动管理您的刷新令牌并获取用户信息. 您的用户将被发送到 FusionAuth 的主题主机登录页面和 然后登录。 之后,它们会被送回你的反动应用程序. 认证成功后, 以下安全, 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 版本 符合要求的身份服务器 . ## 开始 如果您是新建的 React 开发, 您可能想要从快速启动指南开始 。 如果您已经熟悉 React 开发, 请跳到安装区 . ### 快速启动 见 [FusionAuth 反应快速启动](https://fusionauth.io/docs/quickstarts/quickstart-javascript-react-web) 用于使用 FusionAuth 和 React 的完整教程. ### 安装 国家预防机制: ```bash npm install @fusionauth/react-sdk ``` 亚伦: ```bash yarn add @fusionauth/react-sdk ``` ### 配置 包装您的应用程序 `FusionAuthProvider`。 。 。 . ```jsx import ReactDOM from 'react-dom/client'; import { FusionAuthProviderConfig, FusionAuthProvider } from '@fusionauth/react-sdk'; const config: FusionAuthProviderConfig = { clientId: "", // Your app's FusionAuth client id redirectUri: "", // The URI that the user is directed to after the login/register/logout action serverUrl: "", // The url of the server that performs the token exchange 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. }; ReactDOM.createRoot(document.getElementById("my-app")).render( ) ``` #### 配置为 [下一个 JS](https://nextjs.org/) 用下个配置 SDK, 安装 [`next-client-cookies`](https://github.com/moshest/next-client-cookies?tab=readme-ov-file#install) 通过 `useCookies` 输入配置对象为 `nextCookieAdapter`。 。 。 . ```jsx 'use client' import { useCookies } from 'next-client-cookies'; export default function Providers({ children }) { return ( {children} ); } ``` 记得将您的布局包入 `` 从 `next-client-cookies/server`。 。 。 . Vercel出版了一本指南,用于 [在服务器组件中提供第三方上下文提供者](https://vercel.com/guides/react-context-state-management-nextjs#rendering-third-party-context-providers-in-server-components)。 。 。 . ## 使用量 ### 使用FusionAuth系统 一旦你的应用被包裹 `FusionAuthProvider`,您可以使用 `useFusionAuth`。 。 。 . ```jsx import { useFusionAuth } from '@fusionauth/react-sdk'; function MyComponent() { const { isLoggedIn, isFetchingUserInfo, startLogin, startRegister, userInfo } = useFusionAuth() if (isFetchingUserInfo) { return

Loading...

} if (!isLoggedIn) { return (

or

); } if (userInfo?.given_name) { return

Welcome {userInfo.given_name}!

} } ``` 或者,您可以使用 SDK 与 SDK 交互 `withFusionAuth` 更高级的组件. #### 状态参数 这个 `startLogin` 财务报告和审定财务报表 `startRegister` 函数接受可选字符串参数: `state`中输入的值将转给 `onRedirect` 调用您的 `FusionAuthProviderConfig`。虽然您可以传递您想要的状态参数的值,但它通常用于在重新定向到登录或注册之前显示用户在哪个页面,这样用户可以在成功认证后返回该位置. ### 保护内容 这个 `RequireAuth` 组件可以用来保护信息不受未经授权的用户的影响。 需要可选道具 `withRole` 用于确保用户发挥特定作用。 如果一系列角色被传递,用户必须拥有至少一个需要授权的角色. 这个 `Unauthenticated` 组件提供反向功能. ```jsx import { RequireAuth, useFusionAuth } from '@fusionauth/react-sdk'; const UserNameDisplay = () => { const { userInfo } = useFusionAuth(); return ( <>

User: {userInfo.given_name}

// Only displays if user is authenticated

Please log in to view this page

 ); }; const AdminPanel = () => ( // Only displays if user is authenticated and has 'admin' role ); ``` ### UI 组件 这个SDK提供3个预建的UI组件. ```jsx import { FusionAuthLoginButton, FusionAuthLogoutButton, FusionAuthRegisterButton } from '@fusionauth/react-sdk'; export const LoginPage = () => ( <>

Welcome, please log in or register

); export const AccountPage = () => ( <>

Hello, user!

); ``` ### DPOP 模式 默认情况下,SDK会调用HttpOnly cookie中存储符号的Hosted后端(`useDpop: false`,默认值). 在 DPoP 模式中, SDK 转而直接调用 FusionAuth 端点,并将符号绑定在浏览器生成的私人密钥上, per [RFC 9449 (韩语)](https://datatracker.ietf.org/doc/html/rfc9449)设置时启用 `useDpop: true` 打开 `FusionAuthProviderConfig`数字 : ```jsx const config: FusionAuthProviderConfig = { 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` 或未设. ```jsx const { dpopFetch, generateProof, getAccessToken } = useFusionAuth(); // Recommended — handles attaching DPoP headers (and nonce retries) automatically. const response = await dpopFetch('https://api.example.com/data', { method: 'GET' }); // Advanced — for axios or other HTTP libraries that can't use dpopFetch. 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 } // }); ``` ### 已知问题 无. ## 文档 [完整的图书馆文件](https://github.com/FusionAuth/fusionauth-javascript-sdk/tree/main/packages/sdk-react/docs) 这些文件是用 [类型doc](https://typedoc.org/) 并配置为 [类型doc- 插件- 标记下](https://www.npmjs.com/package/typedoc-plugin-markdown)。 。 。 . ## 格式化 推到分行时,有多个林丁包运行. 一个是 `prettier`如果失败,您可以从命令行中修正文件 : - npm 运行安装 - npm 运行更美 - -w / path/ to/ file 这样做会覆盖您的文件, 但纠正更漂亮的反对意见. ## 释放 此软件包通过 GitHub 动作发布 . ## 升级政策 此库可定期接收带有错误修正、安全补丁、测试、代码样本或文档更改的更新. 这些版本也可能更新依赖性,语言引擎和操作系统,因为我们将遵循图书馆使用的基本技术的贬值和日出政策. 这意味着在依赖性(如语言,框架,或操作系统)被其维护者贬值后,这个库也会被我们贬值,最终可能会被更新以使用更新的版本. ## 常见问题 ### @fusionauth/react-sdk 是什么？ FusionAuth 在不增加风险或分散对您主要应用的注意力的情况下解决了建设基本安全的问题 ### 如何安装 @fusionauth/react-sdk？ 在项目目录运行 npm install @fusionauth/react-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.2\.0）、react-dom（\>=18\.2\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @fusionauth/react-sdk 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @fusionauth/react-sdk 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @fusionauth/react-sdk 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @fusionauth/react-sdk 可以商用吗？ @fusionauth/react-sdk 使用 Apache 许可。声明的许可为 Apache，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。 ### @fusionauth/react-sdk 的下载量有多少？ 根据 npm 官方下载统计，@fusionauth/react-sdk 在 2026/10/16 – 2026/11/14 这 30 天内被下载 61,276 次，日均约 2,043 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @fusionauth/react-sdk 还在维护吗？ 最新版本 2\.7\.0 发布于 2026/08/06（3 个月前）；至今共发布 25 个版本，其中过去 12 个月发布了 3 个；首次发布于 2023/01/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。