# @elvix\.is/sdk 中文文档

规范地址：https://npmcn.com/package/%40elvix.is/sdk/

版本：0\.26\.2
npm 元数据更新时间：2026-11-13T13:26:34.964Z
中文译文更新时间：2026-11-13T15:52:12.299Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40elvix.is/sdk
原文对照：https://npmcn.com/package/%40elvix.is/sdk/?lang=original
项目主页：https://elvix.is/
源码仓库：https://github.com/021is/elvix-sdk

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

- 包体积（解压后）：1.7 MB，346 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：6 个
- peer 依赖：next \>=15，react \>=18，react-dom \>=18
- 首次发布：2026-05-24T12:51:06.692Z
- 最新版本发布：2026-11-13T13:26:34.566Z
- 近 30 天下载量：3801（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：94（近 12 个月 94 个）

## 中文简介

官方精灵SDK. Drop-in React 组件,服务器帮助器,以及一个MCP服务器,因此AI编码代理在第一次尝试中整合了elvix.

## 安装

```sh
npm install @elvix.is/sdk
```

也可以使用：`pnpm add @elvix.is/sdk`、`yarn add @elvix.is/sdk`、`bun add @elvix.is/sdk`

## README

![elvix](https://elvix.is/brand/elvix-icon-512.png)

# @elvix.is/sdk (英语)

**身份,保存在欧洲.**  
React + Next.js 的无密码认证 。 主办地为德国法框亚琛.

[![npm](https://img.shields.io/npm/v/@elvix.is/sdk.svg?color=5d4dff)](https://www.npmjs.com/package/@elvix.is/sdk) [![downloads](https://img.shields.io/npm/dm/@elvix.is/sdk.svg?color=8e7dff)](https://www.npmjs.com/package/@elvix.is/sdk) [![CI](https://img.shields.io/github/actions/workflow/status/021is/elvix-sdk/ci.yml?branch=main&label=CI)](https://github.com/021is/elvix-sdk/actions/workflows/ci.yml) [![MIT](https://img.shields.io/badge/license-MIT-black.svg)](https://github.com/021is/elvix-sdk/blob/main/LICENSE) [![docs](https://img.shields.io/badge/docs-elvix.is-5d4dff.svg)](https://elvix.is/docs) [![bundle size](https://img.shields.io/bundlephobia/minzip/@elvix.is/sdk?label=min%2Bgzip&color=black)](https://bundlephobia.com/package/@elvix.is/sdk)

* * *

## 为什么精灵

Auth是获得整合对错的最高杠杆地. 自己滚,你运送一个不安全的OAuth副本 未来你调试在2点。 使用一个美国供应商和您的德国用户 生活在美国的法律框架内。 埃尔维克斯是有观点的,所以第一个答案是安全的答案,而EU的居民,所以法律框架与你的客户匹配.

-   从第一天起就没有密码了——电子邮件OTP,密码,Google.
-   滴入反应组件 。 一个供应商,一个形式,没有锅炉板.
-   服务器侧校验单个呼叫中的会话符号 .
-   受持机所成相. 品牌颜色 允许登录方法和重定向在 elvix Console 中直播; SDK 在运行时读取它们,所以在您的应用中都没有硬码.
-   友好探员 飞船是一个MCP服务器,这样克洛德,克勒斯,克克克特斯和双子座可以将elvix整合而无需手持.

## 开始

**→ [elvix.is/docs/安装](https://elvix.is/docs/install)** 沿着整个集成,每个步骤都有可复制的代码.

它的形状: 在控制台上创建应用程序以获取一个 `clientId`,安装软件包,将您的应用程序包入提供者,并挂载登录格式。 其他一切——哪些方法出现,卡片的外观,使用者登陆的地方——都是Console配置而非道具.

入入入入入入入入同门. 没有单独的注册流程可以构建;一个新的用户被无声地提升.

## 包裹里有什么

| 导入 | 它给你什么 |
| --- | --- |
| `@elvix.is/sdk/react` | 这个 `<Elvix*>` 组件和钩 |
| `@elvix.is/sdk/server` | 会话磁盘验证、 Webhook 验证、设备登录 |
| `@elvix.is/sdk/types` | 共享类型脚本, 无运行时代码 |
| `@elvix.is/sdk/mcp` | MCP 服务器, 可以嵌入到您的主机中 |

**构成部分** - 登录(`<ElvixSignInForm>` 内部或elvix自己的模式或抽屉; `<ElvixSignInCard>`,没有容器的同一张卡片,用于您自己的工作表或对话框,所以您的工作表会更改而不释放精灵),紧凑的电子邮件编码签入(`<ElvixEmailCodeSignIn email>`,对于您已经拥有的地址,用户名、身份表、外观、横幅、区域、语言、地址簿、法律实体、法律实体取用者(`<ElvixLegalEntityPicker selectedId onPick>`,选择一家公司开具发票或增加一张发票,只询问发票需要什么),会话,数据导出,停用,请假. 法律实体组成部分为每个面板保持一高或随每个面板生长(`sizing="fixed" | "flexible"`,与 `maxHeight`) (中文(简体) ). 字段、行和图标从您设置在任何祖先上的 CSS 变量中查看( )`--elvix-field`, (中文(简体) ), `--elvix-row`, (中文(简体) ), `--elvix-picked`, (中文(简体) ), `--elvix-radius`, (中文(简体) ), `--elvix-icon`, (中文(简体) ), `--elvix-key-hints`(中文(简体) ). 包含活预览的完整目录 : **[elvix.is/文件/组件](https://elvix.is/docs/components)**。 。 。 .

**钩子** ——只读,不计票而现. 而不是给自己打电话:

-   `useElvixUser()` ——已签名的用户(带有倒计时名称、用户名、身份摘要、语言)和 `loading` 编号 : `signed-in` 编号 : `signed-out`每个 SDK 编辑器在保存后都会刷新; `useElvixRefresh()` 做它的要求.
-   `useElvixRoles()` 编号 : `useElvixScopes()` 编号 : `useElvixMemberships()` ——应用程序的管理员给予用户什么,名字; `has("admin")` 检查。 控制台的改变现场直播 没有设置:用户不能更改自己的访问权限.
-   重定向后( Google, GitHub), 挂载 `<ElvixOnboarding steps={["passkey"]} />` 一次布局:在服务器所要求步骤(添加密码,选择用户名)上打开并完成就位. `useElvixOnboarding()` 告诉自定义的 UI 步骤待定( 打开工作表) `<ElvixSignInCard>`,并称为 `dismiss()` 当他关闭它的时候 `<ElvixSignInForm>` 已经自行恢复.
-   `useElvixPronounsLabel(pronouns)`, (中文(简体) ), `useElvixLanguageNames()` 财务报告和审定财务报表 `useElvixLanguageLevelLabel(level)` ——在SDK的地块中即时投放标签,与编辑所显示的同名词.
-   你自己的话: `<ElvixProvider locale="de" messages={{ "buttons.signIn": "Rein da" }}>` 重写任意字符串, 或提供一种语言 elvix 不飞船。 全部十五个运出的地方翻译每个按钮;一个组件的 `label` 道克总是赢.
-   `useElvixUserMedia(userId?)` ——"这个用户是否有相片",取自阿凡达人使用的同一种缓存.

**服务器助手** ——对照每个被保护请求的elvix验证会话代号,并让现场用户,角色,范围以及成员返回. 因为它会重新检查每个呼叫,一个被禁用或签出用户会停止在一个请求内进行核查,所以禁令在不写任何东西的情况下生效服务器侧. 细节 : **[elvix.is/docs/验证后端](https://elvix.is/docs/verify-backend)**。 。 。 .

`getElvixLegalEntity({ apiKey, applicationId, userId, entityId, purpose? })` 读取用户为您的应用所选择的法律实体, 以 id 方式, 用于他们所准许的目的(`invoicing`,或 `payouts` 与该人保存的出生数据和手机,作为支付提供者的预填,以及Elvix自己的增值税检查和名字匹配:只取浏览器的ID. 预选实体在水龙头或您继续给予水龙头之前不共享(`useElvixLegalEntityGrant`) (中文(简体) ).

如果你不想给每个请求拨打Elvix, 就把会话代号换一次, 在一个短命的JWT上签字, 并用我们的JWKS在当地验证。 同一向导所盖.

**绑定到浏览器的会话( DPoP) .** 一个在 Console 中打开 DPOP 的应用程序将每个会话绑定在浏览器所保存且无法导出的一个密钥上,因此从页面复制出的一个令牌在其它任何地方都无用. 每一个SDK呼叫都证明了自己,一个会话会约束它创建的时刻. 你的后端有两通电话: `elvixProof(url, { method, token })` 在浏览器中为您的路由提供证明,并且 `verifyElvixToken({ token, proof, htm, htu })` 在服务器上传递. `exchangeElvixToken()` 给一个 DPOP 绑定的 JWT 用于本地核查。 同一向导.

## 在你上船前应该知道的两项规则

**交叉出处的密码必须回到启动的页面.** 如果你的应用程序在自己的域名上,一个密码仪式必须回到持有签名的页面,而不是最后目的地. 将用户直接送入仪表板和密码登记器正确无误,但会话从未建立,因此会弹回登录门. SDK默认做正确的事情;这只有在您超过返回的 URL 时才会被咬.

**存在是自动的.** 提供商自行报告注册用户在线. 你不需要挂起任何额外的, 安装存在组件“ 安全” 是常见的错误。 如果你不想用一个道具关掉它.

## 国 际

包裹载着一个 `elvix` 带有三个子命令的命令 : `doctor` 分析一个整合并打印出绿色/红色清单, `login` 通过 OAuth 2.0 设备流将无头工具签署为应用程序,以及 `mcp` 在stdio上发射MCP服务器.

## 对于 AI 编码代理

对准你的经纪人 **[elvix.is/docs/发展中国家](https://elvix.is/docs/developers)**,或者给它MCP服务器,以便它能够直接读取和管理你的精灵租户。 它只读取,除非你选择了突变,它需要来自控制台的API密钥.

每个MCP工具绑定在一个端点上. 呼叫者填写该端点路径的占位符;他们不能提供自己的路径,主机或方案,服务器拒绝跟踪重定向. 这很重要,因为代理商的上下文例行包含不信任的文本,服务器持有活的API密钥.

**如果您在 0. 10.1 或 更早 运行 MCP 服务器, 请更新和旋转该密钥** ——这些版本让一个工具参数重定向请求,取出关键. 见 [警卫](https://npmcn.com/package/%40elvix.is/sdk/SECURITY.md)。 。 。 .

## 兼容性

反应18+,Next.js 15+(可选),节点20+. 作为无害环境管理发布.

## 警卫

TLS 1.3全程运行. 会话 cookie 是 `Secure; HttpOnly; SameSite=Lax`,带有每套 TTL 和滑动更新,您在控制台中配置 。 API密钥携带每把密钥率限制. CSP, CORS, CSRF的保护和允许来源的执法都以 elvix.is为生.

有发现吗? 读取 [警卫](https://npmcn.com/package/%40elvix.is/sdk/SECURITY.md) 报告 [elvix.is/联系](https://elvix.is/contact) 以“安全报告”为主题。 表格自动确认收据和向维护者私人的路线。 过去的建议列于安全数据库.

## 品牌

深紫 purple: `#5d4dff` 光线, `#8e7dff` 黑暗时分 从 Console 覆盖每个应用程序, 或明确规定由提供者来赢得 Console 默认值 .

标记本身是 `<ElvixLogo size={14} />` (编) `withText` 以字号表示。 它的盾会取出你的文字颜色,因此它适合光和暗:用它来显示精灵在自己的UI中处理什么,例如打开精灵编辑器的设置行.

## 捐款

见 [捐款额](https://npmcn.com/package/%40elvix.is/sdk/CONTRIBUTING.md). CI在每次推力上运行,在合并前必须是绿色.

## 许可证

麻省理工学院. 见 [自由主义](https://npmcn.com/package/%40elvix.is/sdk/LICENSE)。 。 。 .

## 维护者

**[埃多内](https://edvone.dev/)** 德国亚琛。 elvix是一种edvone产品.

-   一般查询: [edvone.dev/ 联系人](https://edvone.dev/contact)
-   销售/整合: [edvone.dev/书](https://edvone.dev/book)
-   安全披露: [elvix.is/联系](https://elvix.is/contact) (主题"安全报告")

## 常见问题

### @elvix\.is/sdk 是什么？

官方精灵SDK\. Drop-in React 组件,服务器帮助器,以及一个MCP服务器,因此AI编码代理在第一次尝试中整合了elvix\.

### 如何安装 @elvix\.is/sdk？

在项目目录运行 npm install @elvix\.is/sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）、react-dom（\>=18）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 elvix、elvix-mcp，可以用 npx elvix 直接运行。

### @elvix\.is/sdk 支持 TypeScript 吗？

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

### @elvix\.is/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @elvix\.is/sdk 需要什么版本的 Node\.js？

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

### @elvix\.is/sdk 可以商用吗？

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

### @elvix\.is/sdk 的下载量有多少？

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

### @elvix\.is/sdk 还在维护吗？

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