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. 网络切换：为不同钱包提供合适的网络切换体验