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. 依赖安装和版本管理

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

使用 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. 🆕 网络切换功能配置

实现比特币网络切换：

// 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. 问题排查和性能优化

如遇问题，按以下步骤排查：

• 检查版本兼容性（确保使用最新版本）

• 验证配置文件和框架集成

• 测试钱包连接和网络切换

• 查看 SSR 环境错误日志

• 检查缓存系统和性能优化设置

框架集成指南

React 集成（最新版本 v0.4.0+）

• 安装依赖：@btc-connect/core + @btc-connect/react

• 配置 Provider：使用 BTCWalletProvider 包装应用

• 使用 Hooks：useWallet、useNetwork、useAccount、useAutoConnect 等

• 网络切换：使用 useNetwork Hook 实现网络切换

• SSR 注意：使用 'use client' 指令或动态导入

快速示例：

'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+ 架构优化）

• 安装依赖：@btc-connect/core + @btc-connect/vue (v0.4.0+)

• 配置插件：使用 BTCWalletPlugin

• 🆕 统一 API：使用 useWallet() 获取所有功能

• 组件使用：ConnectButton、WalletModal 等

• 网络切换：内置网络切换功能

快速示例：

<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 集成（完整兼容）

• 动态导入：钱包组件必须动态导入

• 客户端组件：使用 'use client' 指令标记

• 状态同步：避免 SSR/客户端状态不匹配

• 错误边界：配置客户端错误处理

关键配置：

// 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 集成（完整支持）

• 客户端插件：创建客户端专用插件

• 生命周期：使用 onMounted 确保客户端执行

• 运行时配置：配置客户端环境变量

• 组件保护：使用 ClientOnly 组件包装

关键配置：

// plugins/btc-connect.client.ts import { BTCWalletPlugin } from '@btc-connect/vue'

export default defineNuxtPlugin((nuxtApp) => { nuxtApp.vueApp.use(BTCWalletPlugin) })

<template> <ClientOnly> <ConnectButton /> </ClientOnly> </template>

钱包特定处理

UniSat 钱包（完全支持）

• ✅ 完整程序化网络切换：支持主网、测试网、回归测试网

• ✅ 完整 API 支持：消息签名、PSBT 签名、比特币发送

• ✅ 事件监听完整：账户变化、网络变化、连接状态

• ✅ 增强检测机制：自动检测延迟注入（20秒内轮询）

• ✅ 性能优化：缓存系统、错误处理、连接优化

网络切换示例：

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

OKX 钱包（部分支持）

• ⚠️ 有限网络切换：通常需要用户在钱包中手动切换

• ✅ 基础连接和签名：支持钱包连接和基础签名功能

• ✅ 账户管理：支持多账户和余额查询

• ⚠️ 特殊错误处理：需要针对 OKX 的错误处理逻辑

• ⚠️ 用户体验提示：需要引导用户进行手动操作

网络切换指导：

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

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

支持的网络类型

• livenet/mainnet: 比特币主网

• testnet: 比特币测试网

• regtest: 回归测试网

核心包网络切换

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 网络切换

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 网络切换

<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 类型

• 依赖冲突：检查是否存在依赖版本冲突

性能问题

• 缓存系统：利用智能缓存提升性能

• 连接优化：避免不必要的重复连接

• 事件管理：正确清理事件监听器

• 内存泄漏：检查组件卸载时的资源清理

最佳实践

• 版本一致性：使用安装脚本自动安装最新版本，确保最低版本要求（core v0.4.0+, vue v0.4.0+）

• 错误处理：实现完整的错误处理和用户反馈机制

• 状态管理：正确处理钱包连接状态和网络状态变化

• 用户体验：提供清晰的状态指示和操作指导

• 安全性：验证钱包连接和交易请求的安全性

• 性能优化：利用缓存系统和增强检测机制优化性能

• SSR 兼容：在 SSR 项目中正确配置客户端组件

• 网络切换：为不同钱包提供合适的网络切换体验