从零开始使用 @bsv/sdk：安装、验证与第一步

一句话理解

@bsv/sdk 是用 TypeScript 开发 BSV 应用的主要入口之一，它将交易、脚本、钱包连接和常用协议能力封装成可调用的代码。

如果你之前只是理解“交易是什么”，那么从现在开始，你将真正动手写代码。安装 SDK 的意义不仅在于让项目能运行，更在于把抽象概念放进真实开发环境：你会看到 WalletClient、Script、createAction()、交易 ID、区块浏览器这些对象是如何连接在一起的。

先准备什么

开始之前，需要三个基本条件：

1. 安装 Node.js —— 新手不必一开始研究 Node.js 的所有细节，只需知道它负责运行 JavaScript 和 TypeScript 项目。
2. 准备一个 TypeScript 项目 —— BSV SDK 的官方教程使用 TypeScript 示例，建议从 TypeScript 开始，而不是纯 JavaScript。
3. 准备能与应用通信的钱包 —— 官方第一笔交易教程以符合 BRC-100 钱包接口的钱包为前提（例如本地桌面钱包）。没有钱包，SDK 仍然可以导入，但你无法完成需要签名和资金的真实交易。

一个最小项目长什么样

从一个空目录开始：

这些命令做了几件事：

• npm init -y 创建 package.json，即 Node.js 项目的基本说明文件。
• typescript 提供 TypeScript 编译能力。
• ts-node 让你可以直接运行 .ts 文件，适合入门阶段快速验证。
• @types/node 提供 Node.js 的类型定义，让 TypeScript 能识别 Buffer 等 Node.js 对象。
• @bsv/sdk 是本阶段真正要使用的 BSV SDK。

接着创建一个最小的 tsconfig.json：

这不是唯一配置，但足以用于第一笔交易教程。新手阶段不建议把重点放在构建工具上，先让交易代码跑起来更重要。

安装之后先验证导入

新建 check-sdk.ts：

运行：

如果没有报“找不到模块”、语法错误或 TypeScript 配置错误，说明项目已经能导入 SDK。

注意：这一步只验证 SDK 能被项目加载，不代表钱包已经连接成功，也不代表你已经能广播交易。

在 BSV 技术栈里的位置

@bsv/sdk 在 BSV 技术栈中处于应用开发入口的位置。

底层协议关心的是 inputs、outputs、locking script、unlocking script、序列化、签名和广播。SDK 将这些能力组织成开发者能调用的对象和方法。

本阶段使用 SDK 的高级接口，是为了先建立完整链路：

这条链路跑通之后，再学习手动构造交易（第 8 阶段），理解会更稳。否则新手很容易一开始就被字节序、签名哈希、找零和手续费卡住。

安装不是全部

安装 @bsv/sdk 只是开始。真正能创建交易，还要解决以下问题：

• 钱包是否可用 —— 官方第一笔交易教程假设有可连接的钱包（例如符合 BRC-100 的钱包）。
• 钱包是否有可用资金 —— 没有可花费的 UTXO，就无法支付输出金额和手续费。
• 应用是否被钱包授权 —— 使用 WalletClient 时，应用通常需要用户确认或授权。
• 网络是否可广播 —— 交易创建后还要被处理网络接受，才能得到可查询的链上结果。

这些问题属于“运行环境”，不是 SDK 包本身能完全解决的。

为什么不一开始手写交易

手写交易确实重要，但不适合作为第一步。

一笔真实交易需要完成很多步骤：

• 找到可花费的 UTXO
• 构造 inputs
• 构造 outputs
• 计算手续费
• 生成找零 output
• 对每个 input 生成正确签名
• 序列化交易
• 广播交易
• 处理交易状态

SDK 的高级接口将这些步骤先封装起来，让你先看到完整结果。学习顺序应该是先跑通，再拆解。第 7 阶段就是“跑通”，第 8 阶段才是“拆解”。

新手常见误解

• 安装成功 ≠ 钱包连接成功 —— npm install @bsv/sdk 只说明项目有了依赖。
• SDK 不等于区块链节点 —— SDK 是应用侧工具，不是矿工节点，也不是完整交易处理网络。
• 代码能运行 ≠ 交易已上链 —— 创建交易、广播交易、交易被接受、交易被打包，是不同阶段。
• 官方示例可能随 SDK 版本调整 —— 写真实项目时，应以当前官方文档和实际安装版本为准。

参考来源

• BSV TypeScript SDK 官方文档
• First Transaction 教程
• 钱包接口参考