安装 fuels：Fuel Network TypeScript SDK 的安装、工具链配套与验证指南

fuels 是 Fuel Network 官方 TypeScript SDK 的统一发行包，当前版本为 0.103.0（见 packages/fuels/package.json）。本文以官方入门指南中的 installation.md 为骨架，结合本仓库的实际源码与配置，完整讲解在浏览器、Node.js 项目中通过 bun / pnpm / npm 安装 fuels 的前置条件、操作命令、安装产物与版本校验方法。读完本文，你将能正确选择与工具链配套的 SDK 版本完成安装，并顺利进入「连接网络」的下一步开发流程。

安装前必须理解的两件事：fuels 是什么，以及它依赖什么

在敲下任何安装命令之前，先明确两个关键前提，它们决定了后续所有操作的成败。

fuels 是一个聚合了 SDK 与 CLI 的统一依赖

与逐个引入 @fuel-ts/* 底层模块不同，官方推荐的入口是只安装一个名为 fuels 的包。查看 packages/fuels/package.json 可以看到它的设计：

• 类型与入口：同时提供 CJS（dist/index.js）、ESM（dist/index.mjs）与类型声明（dist/index.d.ts），并声明了 ./cli、./test-utils、./cli-utils 等子路径导出；
• 命令行工具：bin 字段将 fuels 命令映射到 fuels.js，安装后即可在项目中直接运行 fuels CLI（用于类型生成、本地节点等任务）；
• 运行时要求：engines 字段明确要求 Node.js 版本为 ^20.0.0 || ^22.0.0 || ^24.0.0（packages/fuels/package.json），低于 Node 20 的环境将无法满足其运行约束；
• 依赖聚合：内部聚合了 @fuel-ts/account、@fuel-ts/abi-coder、@fuel-ts/contract、@fuel-ts/program、@fuel-ts/script 等全套 @fuel-ts/* 工作区包（见其 dependencies 字段），对使用者屏蔽了包间版本编排细节。

也就是说，一次 fuels 安装即可获得合约交互、钱包账户、类型生成（typegen）与测试工具等完整能力。

SDK 与 Fuel Toolchain 必须配套使用

官方安装文档的开篇要求是：在使用本库之前，必须先安装 Fuel Toolchain。本仓库自身即是这一配套关系的具体体现：

• 仓库通过 packages/versions/src/index.ts 统一维护三者的版本来源，并明确注释：
  • FUELS 来自 packages/fuels/package.json；
  • FUEL_CORE 来自 internal/fuel-core/VERSION；
  • FORC 来自 internal/forc/VERSION。
• 从当前仓库看，fuels 0.103.0 所配套的工具链版本为：Forc（Sway 编译器与工具链）0.68.7（见 internal/forc/VERSION）与 fuel-core（Fuel 节点）0.47.1（见 internal/fuel-core/VERSION）。仓库还内置了 internal/forc 与 internal/fuel-core 两个工具包（含 lib/install.js 等安装脚本），用于在 CI 与开发环境中拉取与 SDK 配套的二进制。
• packages/versions/src/lib/checkFuelCoreVersionCompatibility.ts 中实现了对系统内 fuel-core 版本与 SDK 内置支持版本的兼容性比对逻辑，说明「版本必须匹配」不是口头约定，而是 SDK 运行时会主动校验的约束。

因此安装 fuels 前，请先在本机准备好与目标 SDK 版本配套的 Forc 与 fuel-core；版本不一致时，后续的类型生成、合约部署与链交互都可能出现预期外的失败。

前置检查：Node 版本与工具链就绪确认

在执行安装命令前，建议先完成两项检查，它们都能在当前仓库中找到对应的事实依据：

# 1. 检查 Node.js 版本是否满足 fuels 的 engines 约束（^20 || ^22 || ^24）
node -v

# 2. 确认工具链二进制可用
forc --version
fuel-core --version

关于第 2 步补充说明：仓库的版本对比与校验逻辑分布在 packages/versions/src/cli.ts（将系统内的 forc/fuel-core 版本与 SDK 支持版本进行对比展示）以及 packages/versions/src/lib/compareSystemVersions.ts（比较系统版本与内置版本的大小/相等关系）中。这从源码层面印证了：安装成功不等于环境可用，工具链版本与 fuels 版本是否匹配是决定后续开发能否顺利的关键因素。

在项目中安装 fuels

确认前置条件无误后，进入项目目录并执行安装。官方文档针对三种主流包管理器分别给出了命令。考虑到 SDK 需要与工具链强配套，文档中的版本号都是精确固定的（示例中的 {{fuels}} 占位符会被渲染为当前发布版本，即仓库中 fuels 包的版本 0.103.0）：

使用 bun

bun add fuels@0.103.0

使用 pnpm

pnpm add fuels@0.103.0

使用 npm

npm install fuels@0.103.0 --save

说明：{{fuels}} 这个动态占位符的取值逻辑可以在文档基础设施中找到证据——apps/docs/src/versions.data.ts 从 @fuel-ts/versions 读取 versions 并导出 forc、fuels、fuelCore 三个字段，安装页正是用其中的 fuels 字段动态填充版本号。因此你在阅读本仓库 docs 时看到的 fuels@x.y.z，与 packages/fuels/package.json 中 version 字段保持同步。

三个命令的差异仅在于包管理器本身：--save 对 npm 而言是默认行为，写出来用于显式声明依赖会写入 package.json 的 dependencies；bun 与 pnpm 默认即写入依赖清单。按精确版本安装的原因在于：fuels SDK 的 ABI 编码、类型生成与脚本执行逻辑都受 Forc/fuel-core 版本影响，精确锁定版本有助于复现同一套开发环境。

安装后你得到了什么：SDK、CLI 与子路径导出

安装完成后，fuels 会为你提供三类可直接使用的能力，这些都可以从 packages/fuels/package.json 的 exports 字段得到印证：

使用方式	导出/入口	典型用途
主入口	fuels（import { Provider } from 'fuels'）	Provider、Wallet、合约工厂、脚本与断言等 SDK 核心 API
CLI	fuels（bin，映射到 fuels.js）	生成类型（typegen）、启动本地节点、执行测试等命令行任务
测试工具	fuels/test-utils	测试辅助（launchNode 等，对应 packages/fuels/src/test-utils.ts 的实现）
CLI 工具	fuels/cli-utils、fuels/cli	供工具链复用或深度定制 CLI 行为

主入口默认导出的核心 API 包括 Provider、Wallet、ContractFactory、Script、Predicate 等。SDK 源码位于 packages/fuels/src/index.ts，它负责把上述各能力统一对外暴露；CLI 相关命令分布在 packages/fuels/src/cli 目录下。需要按需精简打包时，也可直接依赖底层 @fuel-ts/* 各包，但日常开发推荐始终以 fuels 单一依赖为主，避免自行维护版本矩阵。

验证安装：用一段最小代码确认环境可用

安装完成后，可以运行一个最小冒烟测试确认 SDK 可被正确加载。官方入门文档在安装步骤之后紧接着的「连接网络」示例（connecting-to-the-network.md）给出了可直接复制的验证代码，其完整片段见 snippets/connecting-to-the-network.ts：

import { Provider } from 'fuels';

const NETWORK_URL = 'https://mainnet.fuel.network/v1/graphql';

const provider = new Provider(NETWORK_URL);

const baseAssetId = await provider.getBaseAssetId();
const chainId = await provider.getChainId();
const gasConfig = await provider.getGasConfig();

console.log('chainId', chainId);
console.log('baseAssetId', baseAssetId);
console.log('gasConfig', gasConfig);

如果这段代码能成功打印出链 ID、基础资产 ID 与 gas 配置，说明 fuels 安装正确、网络可达，且运行时与远端节点版本协商正常；若在早期即报出版本兼容性错误，请回到上文的工具链版本配套检查，逐一核对 forc 与 fuel-core 版本。

安装之后的官方推荐路线

fuels 的安装只是起点。官方「快速开始」系列（见 getting-started 索引）为初次使用者规划了一条循序渐进的学习路径，安装完成后建议按顺序继续：

1. 连接网络：使用 Provider 连接主网/测试网，掌握官方 RPC 地址与如何运行本地节点；
2. 运行本地 Fuel 节点：在开发与测试阶段通过本地节点获得即时反馈，无需依赖公共网络；
3. React 示例：在 React 应用中接入 SDK 的完整前端示例；
4. CDN 用法：不需要打包器的场景下如何通过 CDN 直接引入；
5. 后续步骤：类型生成、合约部署、钱包等进阶主题的入口。

在仓库中，每个 demo 应用（如 apps/demo-fuels、apps/demo-react-vite、apps/demo-bun-fuels）都提供了可直接运行的完整工程，其 package.json 与 fuels.config.ts 是理解「安装 + 配置 + 运行」三者如何衔接的真实范本；templates 目录下还有官方脚手架模板供新项目起步参考。

小结

安装 fuels 的本质是一次「环境对齐」而非简单的依赖下载：先确保 Node.js 满足 ^20 || ^22 || ^24 的 engines 约束，再安装与目标 SDK 版本配套的 Fuel Toolchain（Forc 0.68.7 / fuel-core 0.47.1 为当前 fuels@0.103.0 仓库内配套版本），最后通过 bun/pnpm/npm 精确安装 fuels 包。完成这三个步骤并跑通上述最小连接示例后，你就可以放心地进入合约类型生成、链交互与 DApp 开发阶段了。