helius-wallet-kit và cách khắc phục.
Thiết lập
Hộp thoại ví không có kiểu dáng hoặc hiển thị không chính xác
Bảng định kiểu của SDK chưa được tải. Hãy nhập bảng định kiểu một lần trong bố cục gốc:app/layout.tsx
Các giá trị hook không bao giờ thay đổi (bị kẹt ở loading)
useHeliusWallet() chỉ hoạt động bên trong HeliusWalletProvider và trình cung cấp phải là một thành phần client. Đảm bảo trình cung cấp bao bọc cây thành phần của bạn từ một tệp có "use client" ở đầu — xem Thiết lập.
[HeliusWalletKit] WaaS bootstrap failed (…) trong bảng điều khiển
Trình cung cấp không thể xác định dự án từ khóa API của bạn. Hãy kiểm tra rằng:
NEXT_PUBLIC_HELIUS_API_KEYđã được thiết lập và hợp lệ.- Dự án sử dụng gói trả phí đã bật ví nhúng.
- Nếu bạn đã giới hạn khóa theo miền, nguồn hiện tại phải nằm trong danh sách được phép — xem Bảo mật khóa của bạn.
Đăng nhập
Người dùng được chuyển đến màn hình “nâng cấp” thay vì ví
Ví nhúng yêu cầu một gói Helius trả phí. Khi gói được xác định là miễn phí, trình cung cấp sẽ hiển thị lời nhắc nâng cấp (và backend cũng từ chối yêu cầu ở phía máy chủ). Hãy nâng cấp dự án trong bảng điều khiển.Các phương thức đăng nhập không chính xác xuất hiện (ví dụ: có Google nhưng thiếu ví bên ngoài)
Các phương thức đăng nhập được lấy từ cấu hình dự án trong bảng điều khiển, tại WaaS → Configuration. Nếu dự án chưa cấu hình phương thức nào, hộp thoại sẽ dùng cấu hình mặc định của toàn tổ chức. Hãy thiết lập các phương thức mong muốn trong bảng điều khiển hoặc truyềnauthMethods vào config của trình cung cấp để ghi đè theo từng môi trường — xem Cấu hình phương thức đăng nhập.
Đăng nhập bằng passkey không thành công hoặc thông báo passkey chưa được đăng ký
Passkey được liên kết với miền và trình xác thực nơi chúng được tạo (đây là một ràng buộc của WebAuthn, không phải của Helius). Passkey hoặc khóa bảo mật được đăng ký trên trang web hay thiết bị khác sẽ không thể xác thực ứng dụng của bạn. Hãy tạo passkey trên miền bạn đang kiểm thử — lưu ý rằng passkey được tạo trênlocalhost sẽ được liên kết với localhost và không thể chuyển sang miền đã triển khai của bạn.
Ký và gửi
No wallet available khi ký
Bạn đã gọi một phương thức ký trước khi ví nhúng hoàn tất quá trình cấp phát. Chỉ cho phép ký khi cả status === "authenticated" và address khác null:
… failed (HTTP 404). Set secureRpcUrl …, or mount the Helius route handler
Yêu cầu gửi hoặc phí ưu tiên này không có đích xử lý: trình cung cấp không xác định được URL Secure RPC khi khởi động (các gói trả phí thường tự động nhận được một URL) và không có trình xử lý tuyến máy chủ nào được gắn. Hãy gắn trình xử lý tuyến tại /api/helius/[...path] và thiết lập HELIUS_API_KEY:
app/api/helius/[...path]/route.ts
getTransactions needs the Helius route handler … it isn't available in direct/secure-URL mode
Lịch sử giao dịch chỉ khả dụng thông qua trình xử lý tuyến. Hãy thêm trình xử lý này như hướng dẫn ở trên.
getPriorityFeeEstimate is not available
Devnet không hỗ trợ ước tính phí ưu tiên — đây là một tính năng của mainnet. Hãy bỏ qua bước tra cứu trên devnet; thao tác gửi vẫn hoạt động mà không cần phí ưu tiên.
Giao dịch không được ghi nhận trên mainnet
Nếu không có trình xử lý tuyến, thao tác gửi sẽ sử dụng RPC tiêu chuẩn thay vì Helius Sender, do đó không tận dụng được khả năng ghi nhận tối ưu của Sender. Hãy gắn trình xử lý tuyến để giao dịch được ghi nhận trên mainnet hiệu quả nhất. Nếu thao tác gửi thất bại hoàn toàn, hãy làm mới blockhash —recentBlockhash cũ sẽ hết hạn nhanh chóng.
Khóa và quyền truy cập
Lệnh gọi RPC hoặc API bị từ chối (401 / 403) sau khi khóa khóa của bạn
Khóa bị giới hạn theo miền của bạn không bao gồm nguồn đang thực hiện lệnh gọi. Hãy thêm mọi nguồn bạn sử dụng — môi trường production, staging, bản triển khai preview vàlocalhost để phát triển — trong RPC Access Control. Xem Bảo mật khóa của bạn.
Vẫn chưa giải quyết được?
Discord
Hãy hỏi cộng đồng và đội ngũ Helius.
Support
Liên hệ với bộ phận hỗ trợ Helius.