# @poince/auth 中文文档

规范地址：https://npmcn.com/package/%40poince/auth/

版本：3\.9\.6
npm 元数据更新时间：2026-11-02T04:11:22.675Z
中文译文更新时间：2026-11-02T05:19:00.581Z
软件包许可：SEE LICENSE IN LICENSE

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

原始 npm 页面：https://www.npmjs.com/package/%40poince/auth
原文对照：https://npmcn.com/package/%40poince/auth/?lang=original
项目主页：https://poince.com/

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

- 包体积（解压后）：4.5 MB，100 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：39 个
- peer 依赖：viem ^2\.38\.6，react ^18 \|\| ^19，react-dom ^18 \|\| ^19
- 首次发布：2026-10-27T09:18:49.319Z
- 最新版本发布：2026-11-02T04:11:22.469Z
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

可负担得起的认证、钱包和支付模块。从登录到CRM。

## 安装

```sh
npm install @poince/auth
```

也可以使用：`pnpm add @poince/auth`、`yarn add @poince/auth`、`bun add @poince/auth`

## README

# @poince /身份验证

为React提供身份验证、嵌入式钱包和支付。

构建模块 **身份验证，钱包和支付-从登录到CRM**： 身份验证（密码，电子邮件/短信，社交/OAuth， SIWE， MFA），自我管理 嵌入式钱包 **EVM和索拉纳** 有了资金和支付流，以及 用户属性和事件用于您自己的后端。UI将在7分钟内发布 内置语言环境-英语，中文（简体和繁体），日语， 西班牙语，葡萄牙语和法语-所有这些都完全可以克服。

## 安装

```sh
npm install @poince/auth viem
# or
pnpm add @poince/auth viem
```

`react` （^18 || ^19） `react-dom` 和 `viem` （^2.38.6）是必需的对等依赖- viem是对等的，因为SDK的公共API向您提供了viem对象（客户端、链、帐户） 必须来自应用程序自己的视图。NPM 7+和PNPM自动安装对等体；在Yarn v1或with上 `auto-install-peers=false`，自己安装。Solana软件包会自动安装 (常规的依赖关系)。

### Pnpm：允许或跳过本地构建脚本

在 **规划10.4 +** 安装/构建脚本的一些可传递依赖关系 `@reown/appkit`， `bufferutil`， `keccak`， `utf-8-validate` (在Next.js应用中， `sharp`) -被 默认值：您将看到 `Ignored build scripts …`等等 **规划11** `pnpm install` （或任何命令） 首先自动安装，例如 `pnpm dev`)流产 `ERR_PNPM_IGNORED_BUILDS`． 没有一个 在运行时需要- `bufferutil`， `utf-8-validate` 和 `keccak` 有纯js的回退和 `@reown/appkit`的postinstall是不必要的-所以清除它一次，然后继续：

```sh
# review and approve (or skip) each script interactively — the simplest fix, any pnpm version
pnpm approve-builds
```

或者将选择声明为 `pnpm-workspace.yaml` 与 `allowBuilds` Map (pnpm 11；它被替换了 `ignoredBuiltDependencies`): `false` 跳过包的构建脚本（JS回退运行）， `true` 编译本机加速。

```yaml
# pnpm-workspace.yaml (pnpm 11)
allowBuilds:
  '@reown/appkit': false
  bufferutil: false
  keccak: false
  utf-8-validate: false
  sharp: false            # only if your app pulls sharp (e.g. a Next.js app)
```

npm和Yarn在没有提示的情况下运行这些脚本，所以这个步骤是pnpm-only。

## 快速启动

```tsx
// app/layout.tsx — a Server Component is fine: the SDK's entries are marked "use client".
import { PoinceProvider } from "@poince/auth";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <PoinceProvider appId="YOUR_APP_ID_25_CHARS_LONG">{children}</PoinceProvider>
      </body>
    </html>
  );
}
```

`appId` 是 **要求** -在你的 [Poince开发者门户](https://poince.com/) 获取（25个字符的id）。 **Solana自动支持负载** 在门户中启用时- 连接器由提供程序自动加载，无需额外导入。

从客户端组件触发登录 `useLogin`； `login()` 打开Poince登录UI，然后 `usePoince()` 公开授权状态。门上 `ready` 所以UI等待提供者初始化：

```tsx
"use client";
import { useLogin, usePoince } from "@poince/auth";

export function SignIn() {
  const { ready, authenticated, user } = usePoince();
  const { login } = useLogin();

  if (!ready) return <button disabled>Loading…</button>;
  return authenticated ? (
    <p>Signed in as {user?.id}</p>
  ) : (
    <button onClick={() => login()}>Sign in</button>
  );
}
```

其他挂钩(`useLoginWithEmail`， `useLogout`（钱包挂钩）遵循相同的形状。如果 `appId` 是缺失还是错误， `<PoinceProvider>` 在树的位置呈现诊断(使用 `onProviderError` / `providerErrorFallback`), `login()` 拒绝而不是吊死。

## 入口点

| 导入路径 | 它提供了什么 |
| --- | --- |
| `@poince/auth` | 核心: `PoinceProvider`，身份挂钩，钱包挂钩，代币，链 |
| `@poince/auth/solana` | 索拉纳签名&钱包挂钩；连接器自动加载——低级连接器导出也在这里（高级） |
| `@poince/auth/skin-contract` | 服务主题作者的主题标记词汇表（仅限数据） |
| `@poince/auth/internal` | ⚠️内部/不稳定-没有永久保证；不打算应用程序使用 |

## 框架和工具说明

-   **Next.js应用路由器/ RSC：** 已发布的条目被标记 `"use client"`，这样你就可以渲染 `<PoinceProvider>` 直接从服务器组件，如 `app/layout.tsx` -不需要包装。 调用Poince钩子的组件是客户端组件，就像任何React钩子一样。一个例外: 从服务器组件传入的props必须是可序列化的，所以如果你使用 `onProviderError` / `providerErrorFallback`，从一个小的 `"use client"` 文件。
-   **ESM-only:** 没有CommonJS构建。通过捆绑器(Next, Vite, Remix， webpack, Rollup, esbuild)。一个光秃秃的 `<script type="module">` 将不能自己工作- SDK有 绑定器（或导入映射）必须解析的许多裸说明符导入。
-   **Jest / CommonJS：** 因为这个方案是ESM， `require()` 抛出 `ERR_REQUIRE_ESM`． 在开玩笑, 让它通过你的变换(例如； `transformIgnorePatterns`)或使用ESM测试设置。
-   **打字稿:** 使用 `moduleResolution` `"bundler"`， `"node16"`，或者 `"nodenext"`． 类型发布为 `.d.mts` 背后的 `exports` 地图和不会解决下的遗产 `"node"` 模式。
-   **Content-Security-Policy:** SDK注入 `<style>` 标记(它的样式表和 `styled-components`）。 在严格的 `style-src 'nonce-…'` 策略，通过nonce - `<PoinceProvider nonce={nonce}>` - - - - - - 或者将其暴露为 `<meta property="csp-nonce" nonce="…">` (轻快地 `html.cspNonce` 就像这样) 或者 `__webpack_nonce__`;然后没有 `'unsafe-inline'` 需要样式。通过服务器端呈现， 为您自己的样式组件注册表提供相同的nonce。内联 `style=` 服务器呈现的属性 加价是新手无法企及的。你还需要 `connect-src` 获取Poince API和 `script-src`/`frame-src` 为captcha和WalletConnect提供程序。

## 配置

`appId` (和可选的 `clientId`)标识您的应用程序 `config` 道具套装 客户端 **机制** 键-例如，您的UI提供哪些登录方法。Server-authored设置 （主题/外观，可用链，验证码，法律链接，索拉纳RPC）是 **server-authoritative** 如果通过就会被忽略 `config`;在开发人员门户中配置它们。

## 错误与调试

SDK抛出或拒绝的所有东西都是a `PoinceError`:一个 `PoinceApiError` 当Poince API 回答错误(`status` 保存HTTP状态， `null` 对于网络故障),a `PoinceClientError` 当SDK在发送呼叫之前拒绝它时，或者 `PoinceConnectorError` 当一个 钱包连接失败。分支 `error.code` ——一个 `PoinceErrorCode` 值-绝不在消息文本上：

```tsx
import { isPoinceApiError, isPoinceError, PoinceErrorCode, useLoginWithEmail } from "@poince/auth";

const { sendCode } = useLoginWithEmail();
try {
  await sendCode({ email });
} catch (error) {
  if (isPoinceApiError(error) && error.code === PoinceErrorCode.TOO_MANY_REQUESTS) {
    // back off, then let the user retry
  } else if (isPoinceError(error)) {
    console.warn(error.code, error.message);
  } else {
    throw error;
  }
}
```

如果 `<PoinceProvider>` 在构建其配置时失败，则在适当位置呈现内置诊断 你的树；通过 `onProviderError` 来记录它 `providerErrorFallback` 渲染你自己的UI。 无效的道具—例如an `appId` 这不是确切的25个字符-扔一个 `PoinceClientError` 在 渲染，您自己的错误边界捕获。包裹运送 **没有源映射** -代码被设计混淆-所以 堆栈跟踪指向缩小的块：报告 `code`, `message` 和SDK版本，看看 [docs.poince.com](https://docs.poince.com/) 每个代码的含义。

## 更新日志

看到 [CHANGELOG.md](https://npmcn.com/package/%40poince/auth/CHANGELOG.md) 对于发行说明-它在这个包中发布。

## 许可证

商业、专有的。看到 [许可证](https://npmcn.com/package/%40poince/auth/LICENSE)． 使用需要一个有效的point 帐户和协议通过Poince开发人员门户。

## 常见问题

### @poince/auth 是什么？

可负担得起的认证、钱包和支付模块。从登录到CRM。

### 如何安装 @poince/auth？

在项目目录运行 npm install @poince/auth，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：viem（^2\.38\.6）、react（^18 \|\| ^19）、react-dom（^18 \|\| ^19）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @poince/auth 支持 TypeScript 吗？

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

### @poince/auth 支持 ESM 还是 CommonJS？

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

### @poince/auth 需要什么版本的 Node\.js？

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

### @poince/auth 可以商用吗？

@poince/auth 使用 SEE LICENSE IN LICENSE 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @poince/auth 还在维护吗？

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