鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

btc-connect

实现比特币钱包在多框架项目的无缝集成,支持 React、Vue 及其 SSR 应用的客户端适配,提供统一接口进行钱包连接、网络切换与状态同步,兼容 UniSat 与 OKX 钱包并优化延迟注入检测,确保类型安全与构建性能。

区块链
访问 GitHub
文档Skills.MD
name
btc-connect
description
专业的比特币钱包连接技能,支持btc-connect core、react、vue包在React、Vue、Next.js、Nuxt 3项目中的完整集成,包含UniSat和OKX钱包适配、网络切换功能、SSR环境配置、统一Hook API和v0.5.0最新特性

BTC-Connect 专业集成技能

技能概述

btc-connect 是专为比特币 Web3 应用设计的钱包连接工具包,提供统一的连接接口、事件监听和适配层。此技能支持在 React、Vue、Next.js、Nuxt 3 项目中完整集成最新版本的 btc-connect (v0.5.0+),实现 UniSat 和 OKX 钱包的连接、网络切换、状态管理,并解决 SSR 环境兼容性问题。

最新特性 (v0.5.0): 统一Hook API设计、智能主题检测系统、代码质量全面优化、完善类型安全、增强构建性能、完整测试覆盖。

使用场景

在以下情况下使用此技能:

  • 需要在 React/Vue 项目中集成比特币钱包连接功能
  • 需要在 Next.js/Nuxt 3 SSR 项目中配置 btc-connect
  • 需要实现比特币网络切换(主网/测试网/回归测试网)
  • 需要集成 UniSat 或 OKX 钱包
  • 遇到 btc-connect API 集成或配置问题
  • 需要排查钱包连接失败或 SSR 兼容性问题
  • 需要升级到最新版本的 btc-connect 包 (v0.4.0+)

核心功能

1. 依赖安装和版本管理

  • 自动安装最新版本的 @btc-connect/core、@btc-connect/react、@btc-connect/vue
  • 最低版本要求 v0.4.0+,自动选择最新稳定版本
  • 版本兼容性检查和智能验证
  • 依赖关系验证和冲突解决
  • Bun 包管理器优化

2. 框架集成配置

  • React 项目配置和 Hooks 使用(Context Provider 模式)
  • Vue 项目配置和 Composables 使用(插件系统)
  • Next.js SSR 环境配置(客户端组件模式)
  • Nuxt 3 SSR 环境配置(客户端插件模式)

3. 🆕 网络切换功能 (v0.3.11+)

  • 支持主网 (livenet)、测试网 (testnet)、回归测试网 (regtest)
  • UniSat 钱包完全支持程序化网络切换
  • OKX 钱包网络切换指导
  • 网络变化事件监听和处理

4. 钱包适配和增强检测

  • UniSat 钱包集成和完整 API 使用
  • OKX 钱包集成和适配处理
  • 🆕 增强钱包检测机制(20秒内每300ms轮询延迟注入)
  • 钱包状态管理和事件监听
  • 多钱包兼容性处理

5. 错误排查和性能优化

  • 连接失败诊断和解决方案
  • SSR 环境问题排查和修复
  • 版本兼容性问题解决
  • 🆕 性能优化(缓存系统、错误处理、连接优化)

使用流程

1. 项目评估和环境检查

首先检查项目类型和当前环境:

  • 检查项目框架类型(React/Vue/Next.js/Nuxt 3)
  • 检查现有的依赖和配置(确保无版本冲突)
  • 确定SSR或CSR环境
  • 检查 Node.js 版本(需要 >= 18)和 Bun 包管理器

2. 依赖安装和版本管理

根据项目类型安装相应包:

▼
bash
复制代码
# 使用 Bun(推荐) bun add @btc-connect/core @btc-connect/react # React 项目 bun add @btc-connect/core @btc-connect/vue # Vue 项目 # 或使用 npm npm install @btc-connect/core @btc-connect/react

版本要求:

  • @btc-connect/core: v0.4.0+ (自动安装最新版本)
  • @btc-connect/react: v0.4.0+ (自动安装最新版本)
  • @btc-connect/vue: v0.4.0+ (架构优化版本,自动安装最新版本)

💡 安装策略: 安装脚本自动选择最新稳定版本,确保最低版本要求为 v0.4.0+

3. 框架集成配置

根据框架和环境进行配置:

React 配置:

  • 配置 BTCWalletProvider 包装应用
  • 使用 useWallet、useNetwork、useAccount 等 Hooks
  • SSR 环境使用 'use client' 指令或动态导入

Vue 配置:

  • 配置 BTCWalletPlugin 插件系统
  • 使用 useWallet、useNetwork、useAccount 等 Composables
  • 🆕 v0.4.0+ 统一 API 使用 useWallet()

SSR 环境配置:

  • Next.js:客户端组件模式 + 动态导入
  • Nuxt 3:客户端插件模式 + onMounted 生命周期

4. 🆕 网络切换功能配置

实现比特币网络切换:

▼
typescript
复制代码
// React Hook 使用 const { network, switchNetwork } = useNetwork() await switchNetwork('testnet') // 切换到测试网 // Vue Composable 使用 const { network, switchNetwork } = useNetwork() await switchNetwork('mainnet') // 切换到主网

支持网络:livenet(主网)、testnet(测试网)、regtest(回归测试网)

5. 钱包集成和检测

选择并集成目标钱包:

  • UniSat 钱包:完全支持程序化操作和网络切换
  • OKX 钱包:基础连接和签名,网络切换需要手动操作
  • 🆕 增强检测:自动检测延迟注入的钱包(20秒内轮询)

6. 问题排查和性能优化

如遇问题,按以下步骤排查:

  1. 检查版本兼容性(确保使用最新版本)
  2. 验证配置文件和框架集成
  3. 测试钱包连接和网络切换
  4. 查看 SSR 环境错误日志
  5. 检查缓存系统和性能优化设置

框架集成指南

React 集成(最新版本 v0.4.0+)

  1. 安装依赖:@btc-connect/core + @btc-connect/react
  2. 配置 Provider:使用 BTCWalletProvider 包装应用
  3. 使用 Hooks:useWallet、useNetwork、useAccount、useAutoConnect 等
  4. 网络切换:使用 useNetwork Hook 实现网络切换
  5. SSR 注意:使用 'use client' 指令或动态导入

快速示例:

▼
tsx
复制代码
'use client' import { BTCWalletProvider, useWallet } from '@btc-connect/react' function App() { return ( <BTCWalletProvider> <WalletComponent /> </BTCWalletProvider> ) } function WalletComponent() { const { isConnected, connect, account, network } = useWallet() // 实现钱包连接逻辑 }

Vue 集成(最新版本 v0.4.0+ 架构优化)

  1. 安装依赖:@btc-connect/core + @btc-connect/vue (v0.4.0+)
  2. 配置插件:使用 BTCWalletPlugin
  3. 🆕 统一 API:使用 useWallet() 获取所有功能
  4. 组件使用:ConnectButton、WalletModal 等
  5. 网络切换:内置网络切换功能

快速示例:

▼
vue
复制代码
<template> <div> <ConnectButton @connect="handleConnect" /> <!-- v0.4.0+ 已集成模态框到 ConnectButton --> </div> </template> <script setup> import { ConnectButton, useWallet } from '@btc-connect/vue' const wallet = useWallet() // 🆕 统一 API const handleConnect = (walletId) => { console.log('连接到钱包:', walletId) } </script>

Next.js SSR 集成(完整兼容)

  1. 动态导入:钱包组件必须动态导入
  2. 客户端组件:使用 'use client' 指令标记
  3. 状态同步:避免 SSR/客户端状态不匹配
  4. 错误边界:配置客户端错误处理

关键配置:

▼
tsx
复制代码
// components/WalletConnect.tsx 'use client' import { useWallet } from '@btc-connect/react' export default function WalletConnect() { const { connect, isConnected } = useWallet() // 钱包连接逻辑 } // pages/index.tsx import dynamic from 'next/dynamic' const WalletConnect = dynamic(() => import('./WalletConnect'), { ssr: false })

Nuxt 3 SSR 集成(完整支持)

  1. 客户端插件:创建客户端专用插件
  2. 生命周期:使用 onMounted 确保客户端执行
  3. 运行时配置:配置客户端环境变量
  4. 组件保护:使用 ClientOnly 组件包装

关键配置:

▼
typescript
复制代码
// plugins/btc-connect.client.ts import { BTCWalletPlugin } from '@btc-connect/vue' export default defineNuxtPlugin((nuxtApp) => { nuxtApp.vueApp.use(BTCWalletPlugin) })
▼
vue
复制代码
<template> <ClientOnly> <ConnectButton /> </ClientOnly> </template>

钱包特定处理

UniSat 钱包(完全支持)

  • ✅ 完整程序化网络切换:支持主网、测试网、回归测试网
  • ✅ 完整 API 支持:消息签名、PSBT 签名、比特币发送
  • ✅ 事件监听完整:账户变化、网络变化、连接状态
  • ✅ 增强检测机制:自动检测延迟注入(20秒内轮询)
  • ✅ 性能优化:缓存系统、错误处理、连接优化

网络切换示例:

▼
typescript
复制代码
// 完全支持程序化切换 await switchNetwork('testnet') // 立即切换到测试网 await switchNetwork('mainnet') // 立即切换到主网

OKX 钱包(部分支持)

  • ⚠️ 有限网络切换:通常需要用户在钱包中手动切换
  • ✅ 基础连接和签名:支持钱包连接和基础签名功能
  • ✅ 账户管理:支持多账户和余额查询
  • ⚠️ 特殊错误处理:需要针对 OKX 的错误处理逻辑
  • ⚠️ 用户体验提示:需要引导用户进行手动操作

网络切换指导:

▼
typescript
复制代码
// OKX 钱包网络切换需要用户手动操作 try { await switchNetwork('testnet') } catch (error) { // 提示用户在 OKX 钱包中手动切换网络 console.log('请在 OKX 钱包中手动切换到测试网') }

🆕 网络切换功能详解 (v0.3.11+)

支持的网络类型

  • livenet/mainnet: 比特币主网
  • testnet: 比特币测试网
  • regtest: 回归测试网

核心包网络切换

▼
typescript
复制代码
import { BTCWalletManager } from '@btc-connect/core' const manager = new BTCWalletManager() await manager.switchNetwork('testnet') // 监听网络变化 manager.on('networkChange', ({ walletId, network }) => { console.log(`钱包 ${walletId} 切换到 ${network} 网络`) })

React Hook 网络切换

▼
typescript
复制代码
import { useNetwork } from '@btc-connect/react' function NetworkSwitcher() { const { network, switchNetwork, isSwitching } = useNetwork() const handleSwitch = async () => { try { await switchNetwork('mainnet') console.log('切换到主网成功') } catch (error) { console.error('切换失败:', error.message) } } return ( <div> <p>当前网络: {network}</p> <button onClick={handleSwitch} disabled={isSwitching}> {isSwitching ? '切换中...' : '切换到主网'} </button> </div> ) }

Vue Composable 网络切换

▼
vue
复制代码
<template> <div class="network-switcher"> <p>当前网络: {{ network.name }}</p> <button @click="switchToTestnet" :disabled="isSwitching"> {{ isSwitching ? '切换中...' : '切换到测试网' }} </button> </div> </template> <script setup> import { useNetwork } from '@btc-connect/vue' const { network, switchNetwork, isSwitching } = useNetwork() const switchToTestnet = async () => { try { await switchNetwork('testnet') } catch (error) { console.error('切换失败:', error.message) } } </script>

常见问题解决

连接问题

  • 钱包检测失败:检查钱包是否正确安装和启用
  • 延迟注入处理:使用增强检测机制(20秒内每300ms轮询)
  • 用户取消连接:正确处理用户取消连接的情况
  • 网络权限:确保钱包有权限访问目标网络

SSR 问题

  • 动态导入:使用动态导入避免服务端错误
  • Window 对象:检查 window 对象的可用性
  • 状态同步:处理 SSR/客户端状态不匹配问题
  • 客户端插件:在 Nuxt 3 中使用客户端专用插件

版本兼容性问题

  • 版本匹配:确保 core、react、vue 包版本兼容
  • API 变更:注意 v0.4.0+ Vue 包的架构变化
  • 类型定义:配置正确的 TypeScript 类型
  • 依赖冲突:检查是否存在依赖版本冲突

性能问题

  • 缓存系统:利用智能缓存提升性能
  • 连接优化:避免不必要的重复连接
  • 事件管理:正确清理事件监听器
  • 内存泄漏:检查组件卸载时的资源清理

最佳实践

  1. 版本一致性:使用安装脚本自动安装最新版本,确保最低版本要求(core v0.4.0+, vue v0.4.0+)
  2. 错误处理:实现完整的错误处理和用户反馈机制
  3. 状态管理:正确处理钱包连接状态和网络状态变化
  4. 用户体验:提供清晰的状态指示和操作指导
  5. 安全性:验证钱包连接和交易请求的安全性
  6. 性能优化:利用缓存系统和增强检测机制优化性能
  7. SSR 兼容:在 SSR 项目中正确配置客户端组件
  8. 网络切换:为不同钱包提供合适的网络切换体验
区块链

快捷安装

复制到终端去安装 Skill

npxskillsaddMicrock/ordinary-claude-skills--skill"btc-connect"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
property-based-testing
通过生成随机输入验证代码在各类边界条件下的行为一致性,适用于序列化、解析、归一化及纯函数等场景,能有效发现隐含缺陷并提升测试覆盖率,尤其适合需要高可靠性的算法与智能合约验证。
compliance-checker
能够对基础设施配置进行合规性评估,检查是否符合 SOC2、HIPAA 和 PCI DSS 等行业标准,识别潜在的安全风险与违规项,并生成改进建议报告,适用于安全审计与合规审查场景。
orchestration
作为系统的核心协调中枢,负责将用户复杂需求拆解为并行任务流,动态调度不同能力的智能体协同工作,自动管理任务依赖与执行状态,并在后台静默完成多线程探索、分析与实现,最终整合结果交付完整解决方案。
skill-adapter
对基础设施配置进行多标准合规性评估,覆盖 SOC2、HIPAA 和 PCI DSS 等主流框架,自动识别配置偏差与安全风险,并生成可操作的整改建议报告,支撑持续合规治理与审计准备。
contract-test-creator
自动生成符合行业规范的契约测试代码与配置,提供从框架搭建到单元测试、集成测试及模拟对象编写的全流程支持,适用于需要实现高质量自动化测试验证的开发场景。