> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 故障排除

> 解决集成 Helius 嵌入式钱包时最常见的问题 - 样式、登录、签名、发送和 API 密钥访问。

集成 [`helius-wallet-kit`](https://www.npmjs.com/package/helius-wallet-kit) SDK 的常见问题及解决方法。

## 设置

### 钱包模式未样式化或看起来损坏

SDK 的样式表未加载。在您的根布局中导入一次：

```tsx app/layout.tsx theme={"system"}
import "helius-wallet-kit/ui/styles.css";
```

### 钩子值从不改变（停留在 `loading`）

`useHeliusWallet()` 仅在 `HeliusWalletProvider` 内工作，并且提供者必须是**客户端**组件。确保提供者从顶部具有 `"use client"` 的文件包装您的组件树 — 请参阅 [设置](/docs/zh/waas/quickstart#设置)。

### 控制台中的 `[HeliusWalletKit] WaaS bootstrap failed (…)`

提供者无法从 API 密钥解析您的项目。请检查：

* `NEXT_PUBLIC_HELIUS_API_KEY` 是否设置并有效。
* 项目是否在启用了嵌入式钱包的**付费计划**中。
* 如果您对密钥进行了域限制，请确保您当前的来源在允许列表中 — 请参阅 [保护您的密钥](/docs/zh/waas/securing-your-key)。

## 登录

### 用户进入“升级”屏幕而不是钱包

嵌入钱包需要 **付费** Helius 计划。当解析的计划为免费时，提供者会渲染升级提示（并且后端也会在服务器端拒绝请求）。请在 [仪表板](https://dashboard.helius.dev) 中升级项目。

### 出现了错误的登录方法（例如，显示了 Google，外部钱包缺失）

登录方法来自您在 **WaaS → 配置**下的 [仪表板](https://dashboard.helius.dev) 中的项目配置。如果项目没有配置，则模式将回退到整个组织的默认设置。请在仪表板中设置所需的方法，或传递 `authMethods` 到提供者 `config` 去重写每个环境 — 请参阅 [配置登录方法](/docs/zh/waas/configuration#配置登录方法)。

### 通行密钥登录失败或显示通行密钥未注册

通行密钥绑定到它们创建的 **域和身份验证器**（这是 WebAuthn 限制，而不是 Helius 的）。在其他网站或设备上注册的通行密钥或安全密钥无法对您的应用进行身份验证。在您正在测试的域上创建通行密钥 — 请注意，在 `localhost` 上创建的通行密钥绑定到 `localhost`，并不会转移到您的已部署域。

## 签名和发送

### 签名时的 `No wallet available`

您在嵌入钱包完成配置之前调用了签名方法。在 `status === "authenticated"` **和** 非空的 `address` 上进行签名：

```tsx theme={"system"}
const { status, address, signMessage } = useHeliusWallet();
const ready = status === "authenticated" && address;
```

### `… failed (HTTP 404). Set secureRpcUrl …, or mount the Helius route handler`

您正在直接（安全 RPC）模式下运行，此调用（**发送**或**优先费**请求）需要服务器路由处理程序。将其安装在 `/api/helius/[...path]` 并设置 `HELIUS_API_KEY`：

```ts app/api/helius/[...path]/route.ts theme={"system"}
import { createHeliusRouteHandler } from "helius-wallet-kit/next";

export const { GET, POST } = createHeliusRouteHandler();
```

请参阅 [服务器路由处理程序](/docs/zh/waas/quickstart#设置)。

### `getTransactions needs the Helius route handler … it isn't available in direct/secure-URL mode`

交易历史仅通过路由处理程序可用。如上所示添加它。

### `getPriorityFeeEstimate is not available`

开发网不支持优先费估算 — 这是一项主网功能。在开发网上跳过查找；发送仍在没有优先费的情况下工作。

```tsx theme={"system"}
if (cluster === "mainnet-beta") {
  const fees = await getPriorityFeeLevels([address]);
}
```

### 交易未在主网上登陆

如果没有路由处理程序，发送将使用标准 RPC 而不是 [Helius Sender](/docs/zh/sending-transactions/sender)，因此他们会放弃 Sender 的优化着陆。安装路由处理程序以获得最佳主网着陆。如果发送完全失败，请刷新区块哈希 — 一个过期的 `recentBlockhash` 会很快过期。

## 密钥和访问

### 锁定密钥后 RPC 或 API 调用被拒绝（401 / 403）

您的域限制密钥不包括您调用的来源。从 **RPC 访问控制**中添加您使用的每个来源 — 生产、预发布、预览部署和用于开发的 `localhost`。请参阅 [保护您的密钥](/docs/zh/waas/securing-your-key)。

## 仍然卡住？

<CardGroup cols={2}>
  <Card title="Discord" icon="discord" href="https://discord.com/invite/6GXdee3gBj">
    向社区和 Helius 团队询问。
  </Card>

  <Card title="支持" icon="headset" href="/docs/zh/support">
    联系 Helius 支持。
  </Card>
</CardGroup>