fuels-ts 的 Fuels CLI 快速上手指南：统一构建、部署与类型生成的全栈 Fuel dApp 工作流

Fuels CLI 是 fuels-ts（Fuel Network 的 TypeScript SDK 仓库）中把「Sway 智能合约开发」与「TypeScript 前端接入」打通的关键工具，被官方定位为构建全栈 Fuel dApp 最快的方式。本文以仓库内入门文档 apps/docs/src/guide/fuels-cli/index.md 为主线，完整介绍它的定位、环境要求、安装校验、核心子命令（init / build / deploy / dev）、项目目录约定与 fuels.config.ts 配置骨架，并结合仓库源码说明每个命令背后的真实调用链。读完你可以把一个普通的 Next.js / Vite 前端项目变成「写 Sway → 编译 → 生成类型安全的 TS 客户端 → 本地部署」全自动化的 Fuel dApp 工程。

一、Fuels CLI 是什么：四条命令覆盖一个完整 dApp 开发生命周期

在 fuels-ts 中，fuels 是一个可独立安装的 CLI 包，核心职责是把分散的工具链动作收敛成少量高层命令。入门文档在最开头就给出了它的四条核心命令：

• fuels init：创建一个新的 fuels.config.ts 文件；
• fuels build：编译 forc workspace 并为其中所有程序生成 TypeScript 类型；
• fuels deploy：部署 workspace 下的合约，并把合约 ID 保存到 JSON 文件；
• fuels dev：启动本地 Fuel Core 节点，并在每次文件变更时自动执行 build + deploy。

从源码看，这四条命令并非散落在多个入口里，而是统一注册在 packages/fuels/src/cli.ts：它基于 commander 构造了一个名为 fuels 的 Command 对象，并依次挂载 init、dev、node、build、deploy 等本地子命令，同时把 typegen（类型生成）与 versions（版本检查）路由到子包 @fuel-ts/abi-typegen 与 @fuel-ts/versions 的实现上。也就是说，fuels 是 Fuel SDK 全家桶的命令行门面，底层各司其职：

子命令	定位	入口注册位置（仓库源码）
init	生成 fuels.config.ts 样板	packages/fuels/src/cli.ts 中 Commands.init 分支
dev	本地节点 + 热重载开发	packages/fuels/src/cli/commands/dev
node	按项目配置启动 Fuel 节点	packages/fuels/src/cli/commands/node
build	编译 Sway 并生成类型	packages/fuels/src/cli/commands/build
deploy	部署合约并落盘合约 ID	packages/fuels/src/cli/commands/deploy
typegen	由 ABI JSON 手工生成类型	路由自 @fuel-ts/abi-typegen
versions	工具链与 SDK 版本兼容性检查	路由自 @fuel-ts/versions

所有子命令都遵循「先读取项目根目录的 fuels.config.ts，再执行动作」的模式（withConfig），因此配置文件是整套 CLI 工作流的中枢。

二、前置条件：Sway 工具链（forc 与 fuel-core）

入门文档明确指出，Fuel Toolchain 及其组件（主要是 forc 与 fuel-core）是使用 Fuels CLI 多项操作的前置条件。具体而言：

• 用 fuels build 编译合约，需要系统里存在 forc；
• 用 fuels deploy 在本地部署合约，需要 fuel-core。

如果尚未安装这两个二进制，需要先完成 Fuel 官方提供的工具链安装（通常在 Fuel 生态里通过 fuelup 统一安装管理）。仓库源码层面也印证了这一点：fuels 配置文件中的 forcPath 与 fuelCorePath 两个字段的默认值分别是系统路径上的 forc 与 fuel-core（见 apps/demo-fuels/fuels.config.full.ts 中的注释与默认值），即默认直接使用系统级二进制；此外仓库还在 internal/forc 与 internal/fuel-core 中以独立 npm 包形式封装了这两个二进制的下载/安装/升级脚本，作为内部 CI 与测试的固定版本来源。

三、安装 fuels 包

把 fuels 添加到你的 my-fuel-dapp 项目中，按包管理器三选一：

npm install fuels --save

pnpm add fuels

bun add fuels

官方入门文档中给出的命令形如 fuels@<version>，其中版本号由文档站点运行时注入——它来自 apps/docs/src/versions.data.ts 中从 @fuel-ts/versions 导出的当前 SDK 版本。因此在你的真实项目里，建议安装与 fuels-ts 发布版对齐的版本。对版本敏感的工程化项目，还可以用下文介绍的 fuels versions 命令做双向校验。

安装完成后先做一次自检，确认命令可用：

npx fuels -v

该输出并非硬编码字符串，而是由 packages/fuels/src/cli.ts 中的 program.version(versions.FUELS, '-v, --version', ...) 动态绑定，其中 versions.FUELS 来源于 @fuel-ts/versions 包。

四、从一个典型项目结构开始

入门文档用一个示例目录描述了「前端 + Sway workspace + 类型安全 API」的目标工程形态：

my-fuel-dapp # NextJS app 或类似项目
├── sway-programs # Forc 的 workspace
│   ├── src
│   ├── ...
│   └── Forc.toml
├── public
│   └── ...
├── src
│   ├── app
│   ├── ...
│   └── sway-programs-api # 类型安全的生成 API
└── package.json

关键认知有两处：

1. sway-programs 是一个标准 Forc workspace，目录根部有 Forc.toml 声明其成员（contract / predicate / script）；
2. src/sway-programs-api 是 CLI 自动生成的 TypeScript 输出目录——不要手写，它由 fuels 依据 ABI 与合约字节码自动产出类型、工厂类与合约 ID 索引。

仓库内的真实例子见 apps/demo-fuels（含 sway-programs 与生成的测试），其目录形态与上述骨架完全一致；apps/create-fuels-counter-guide 则给出了一个同时包含 contract / predicate / script 三种程序类型、更接近生产形态的参考工程。

五、第一步：用 fuels init 生成配置文件

下一跳就是运行 fuels init。它的完整参数如下（来自 commands.md 的 help init 输出）：

Options:
  --path <path>                Path to project root (default: current directory)
  -w, --workspace <path>       Relative dir path to Forc workspace
  -c, --contracts [paths...]   Relative paths to Contracts
  -s, --scripts [paths...]     Relative paths to Scripts
  -p, --predicates [paths...]  Relative paths to Predicates
  -o, --output <path>          Relative dir path for Typescript generation output
  --forc-path <path>           Path to the `forc` binary
  --fuel-core-path <path>      Path to the `fuel-core` binary
  --auto-start-fuel-core       Auto-starts a `fuel-core` node during `dev` command
  --fuel-core-port <port>      Port to use when starting a local `fuel-core` node for dev mode
  -h, --help                   Display help

两种最常见的用法：

用法 A——没有用 Forc workspace，而是散落的多个合约目录：

npx fuels init --contracts ./my-contracts/* --output ./src/sway-contracts-api

用法 B——使用 Forc workspace（推荐，与入门文档目录骨架对齐）：

npx fuels init --workspace ./sway-programs --output ./src/sway-programs-api

运行后，项目根目录会生成一个 fuels.config.ts。仓库 apps/demo-fuels/fuels.config.minimal.ts 保存了这个「最小配置」的精确形态：

import { createConfig } from 'fuels';

export default createConfig({
  workspace: './sway-programs', // forc workspace
  output: './src/sway-programs-api',
});

注意 createConfig 是 fuels 包导出的类型化辅助函数（实现见 packages/fuels/src/cli/utils/createConfig.ts），它能让你在写配置时获得完整的 TypeScript 类型提示与字段校验。

六、理解 fuels.config.ts：配置项一览

fuels.config.ts 是整套 CLI 的行为契约。除 workspace/output 外，仓库还维护了一份覆盖全部字段的完整示例 apps/demo-fuels/fuels.config.full.ts，逐字段讲解见 config-file.md。这里先给出一份速查表（默认值均来自上面这份完整示例文件中的注释）：

配置项	作用	默认值 / 备注
workspace	Forc workspace 的相对路径	与 contracts/predicates/scripts 互斥
contracts / predicates / scripts	不使用 workspace 时，分别声明各类程序目录	与 workspace 互斥
output	TypeScript 生成的输出目录	必填，如 ./src/sway-programs-api
privateKey	部署合约所用的钱包私钥	建议从环境变量读取（process.env.…）
providerUrl	部署时连接的节点 URL	默认 http://127.0.0.1:4000/v1/graphql
snapshotDir	本地节点的 chainConfig.json 等快照配置目录	仅 fuels dev 使用，需配合 autoStartFuelCore
autoStartFuelCore	是否由 fuels dev 自动拉起短生命周期 fuel-core 节点	true 时会用本地节点地址覆盖 providerUrl
fuelCorePort	本地 fuel-core 节点端口	默认从 4000 起取第一个空闲端口
forcBuildFlags	传给 forc build 的额外标志	默认 []；Sway 默认以 debug 编译
deployConfig	部署配置对象，或返回部署配置的异步函数	函数可访问 options.contracts 取已部署合约
onBuild / onDeploy / onDev / onNode / onFailure	各生命周期钩子回调	参数含 config，onDeploy/onFailure 额外携带数据或错误
forcPath / fuelCorePath	指向 forc / fuel-core 二进制的路径	默认使用系统二进制

值得展开的两个行为：

• privateKey 与 providerUrl 会被本地节点覆盖：当 autoStartFuelCore 为 true 时，fuels dev 会启动一个临时节点，并用该节点的地址覆盖 providerUrl、用其 consensusKey 覆盖 privateKey——这正是「开箱即用、无需自行部署网络」的关键。若置为 false，则需要自己启动 fuel-core 并显式配置 providerUrl。
• forcBuildFlags 控制编译模式：Sway 程序默认以 debug 模式编译，若需发布 release 版本，可在此传入标志，例如 forcBuildFlags: ['--release']。

如果你希望配置从 .env 读取私钥等敏感信息，官方推荐引入 dotenv 包（pnpm install dotenv / npm install dotenv / bun install dotenv），然后在 fuels.config.ts 顶部加载环境变量。仓库内参考实现见 apps/create-fuels-counter-guide/fuels.config.ts。

七、fuels build：一次命令完成「编译 + 类型生成」

fuels build 会依次做两件事（选项见 commands.md）：

1. 用 forc 编译 workspace 下所有 Sway 程序（Sway 程序默认以 debug 模式构建，可通过 fuels.config.ts 的 forcBuildFlags 调整）；
2. 用 fuels-typegen 为它们生成 TypeScript 类型与工厂类，落到 output 目录。

npx fuels build

额外还支持 --deploy 标志：

npx fuels build --deploy

带上 --deploy 时，构建完成后会额外：先按需自动启动一个短生命周期的 fuel-core 节点（见 config-file.md 中 autoStartFuelCore 一节），再在该节点上执行部署。这对合约开发尤其有用——因为合约 ID 只在其被部署的那一刻才会产生，只有先部署才能拿到可写进前端代码的合约地址。该行为的 CLI 定义可回溯到 packages/fuels/src/cli.ts 中 build 命令的 -d, --deploy 选项声明。

八、fuels deploy：部署并持久化合约 ID

npx fuels deploy

fuels deploy 做两件事：

1. 部署 workspace 下的全部 Sway 合约；
2. 把部署得到的合约 ID 保存到 JSON 文件：./src/sway-programs-api/contract-ids.json（即 output 目录下）。

文件内容形如：

{
  "myContract1": "0x..",
  "myContract2": "0x.."
}

这些 ID 直接用于在 TS 侧实例化合约——把「链上地址」与「类型安全的生成代码」绑定起来。仓库中 demo-fuels 的测试 apps/demo-fuels/src/index.test.ts 演示了如何从生成产物中取出这些 ID 完成调用；完整的端到端写法见 using-generated-types.md。

关于代理合约（Proxy Contract）：如需在部署阶段自动部署可升级代理，可以在 Forc.toml 中开启相关配置；官方同时提供了 Sway Libs 的可升级性库与 SRC-14（Simple Upgradable Proxies）标准作为参考。

九、fuels dev：本地节点 + 全自动热更新开发模式

npx fuels dev

fuels dev 做三件事：

1. 自动启动一个短生命周期的 fuel-core 节点（依赖配置文件的 autoStartFuelCore: true）；
2. 在启动时先执行一次 build 和 deploy；
3. 持续监听你的 Forc workspace，每次 Sway 文件变更就重复第 2 步。

典型的使用体验是：在另一个终端里运行 next dev（或 vite）驱动前端，本终端运行 fuels dev；每当你在 workspace 里改一个合约，Fuels CLI 就重新生成类型定义与工厂类，前端构建系统感知到文件更新后会自动重编译/热更新。换言之，dev 模式把「智能合约即数据层」的迭代体验拉平到与传统前后端 HMR 一致的节奏。

十、其余命令：node、typegen 与 versions

除四条主命令外，CLI 还提供了三个辅助命令：

• fuels node：只负责按当前项目的 fuels.config.ts 启动一个短生命周期 fuel-core 节点，适合手动调试场景。
• fuels typegen：当你不走完整 workspace 流程、而是手里已有 ABI JSON 文件时，可手动生成类型定义与工厂类：

Options:
  -i, --inputs <path|glob...>  Input paths/globals to your Abi JSON files
  -o, --output <dir>           Directory path for generated files
  -c, --contract               Generate types for Contracts [default]
  -s, --script                 Generate types for Scripts
  -p, --predicate              Generate types for Predicates
  -S, --silent                 Omit output messages

其更完整的用法参见 generating-types.md。

• fuels versions：对照你本机 Fuel 工具链组件的版本，与你当前安装的 TypeScript SDK 版本所支持的版本做兼容性匹配，输出类似下面这样的比对表：

┌───────────┬───────────┬────────────────┬─────────────┐
│           │ Supported │ Yours / System │ System Path │
├───────────┼───────────┼────────────────┼─────────────┤
│ Forc      │ <ver>     │ <ver>          │ forc        │
├───────────┼───────────┼────────────────┼─────────────┤
│ Fuel-Core │ <ver>     │ <ver>          │ fuel-core   │
└───────────┴───────────┴────────────────┴─────────────┘

十一、补充：版本号从哪来——文档与 CLI 的版本对齐机制

入门文档在注入安装命令与 versions 表格里的 fuels/forc/fuel-core 版本时，并非静态写死。整套取值链路在仓库中清晰可查：

• 文档站点运行时从 apps/docs/src/versions.data.ts 读取 { forc, fuels, fuelCore }；
• 这三个值统一来自 @fuel-ts/versions 包，其根实现为 packages/versions/src/index.ts 中的 getBuiltinVersions()；
• 按该文件顶部注释说明：FUELS 取自 packages/fuels/package.json，FORC 与 FUEL_CORE 分别取自 internal/forc/VERSION 与 internal/fuel-core/VERSION 文件。

这也解释了 fuels versions 命令为什么能给出「Supported」列——SDK 在发布时就把与之匹配的工具链版本固化了。换句话说：当你升级 fuels SDK 后，如果本地 forc/fuel-core 与 SDK 内置的兼容版本不一致，fuels versions 会第一时间给出提示，避免「类型生成了但部署报错」的隐性故障。

十二、下一步：把每一条命令吃透

本文覆盖了入门文档 index.md 的完整主线——安装、校验、目录约定与 init 起步。要继续深入，建议按顺序阅读同一指南目录下的系列文档：

• commands.md：逐条命令的完整参数表与运行语义；
• config-file.md：全部配置项的精讲与「对象 vs 函数」两种 deployConfig 写法；
• generating-types.md：fuels typegen 面向 ABI 文件的类型生成；
• using-generated-types.md：把生成的合约/谓词/脚本类型接入业务代码；
• abi-typegen.md：类型生成器本身的机制说明。

综合来看，Fuels CLI 通过一份 fuels.config.ts + 四条核心命令，把「Sway workspace 编译、TS 类型生成、本地 Fuel 节点启停、合约部署与 ID 落盘、热重载监听」串成了一条完整且可复现的流水线。无论你是从零 create-fuels 脚手架起步，还是把 CLI 接入既有 Next.js / Vite 工程，其上手路径都收敛在这份快速入门文档所描述的步骤里：装好工具链 → 安装 fuels → fuels init 生成配置 → fuels dev 进入开发循环 → fuels build --deploy 固化产物。