从 0.1.0 到 0.103.0：读懂 fuels-ts 中 fuels 聚合包与 CLI 的能力演进全景

本篇技术指南以 fuels 聚合包版本变更日志 为骨架，梳理 Fuel TS SDK 中 fuels 包从诞生到 0.103.0 的功能演进：它既是把所有 @fuel-ts/* 子包重新导出的"SDK 统一入口"，又是承载 init / build / deploy / dev / node / typegen / versions 等命令的 Fuels CLI。读完本文，你将能够理解变更日志中 Minor / Patch Changes、! 破坏性标记的准确含义，掌握当前 fuels 包提供的 CLI 命令、fuels.config.ts 配置体系、类型生成与部署工作流，并能依据版本历史判断升级路径与破坏性变更风险。

---

一、fuels 包在 fuels-ts 仓库中的定位

fuels-ts 是一个 monorepo（turbo + pnpm），在 packages/ 下拆分了十几个 @fuel-ts/* 子包（account、contract、program、script、abi-coder、abi-typegen、address、crypto、transactions、utils 等）。fuels（package.json）是其中唯一以"无 @fuel-ts 前缀"命名的聚合包，承担两个角色：

1. 运行时聚合入口：在 src/index.ts 中统一 export * from 所有子包（含各自的 configs 子路径），并额外导出 Script、FuelAsm（@fuels/vm-asm 的命名空间导出，0.100.4 版本加入）；它同时暴露 fuels 可执行程序（bin: { fuels: "fuels.js" }）。
2. CLI 与工具入口：package.json 的 exports 提供 fuels、fuels/cli、fuels/test-utils、fuels/cli-utils 四个子路径，供库使用者与测试场景按需引入。

CHANGELOG 0.64.1 中的 "include fuel-ts/utils in fuels umbrella package"、0.32.0 的 "Adding missing export for package Predicate"、0.89.0 的 "exporting FuelError class in umbrella package"、0.34.0 的 "export mnemonic package… create/exports const MNEMONIC_SIZES"、0.91.0 的 "export test and cli utilities in fuels umbrella package" 等条目，共同勾勒出这个聚合包的演进逻辑：持续把子包能力收敛到单一命名空间，让用户只需 import ... from 'fuels' 即可。

依赖关系上，package.json 以 workspace:* 同时依赖 abi-coder、abi-typegen、account、address、contract、crypto、errors、hasher、math、program、script、transactions、utils、versions、recipes 共 15 个 @fuel-ts 子包，这也是 CHANGELOG 中几乎每个版本都会出现一长串 - @fuel-ts/xxx@0.x.y 依赖同步更新段的原因。

二、版本地图：CLI 时代的关键里程碑

CHANGELOG 前部（0.8.0 之前）使用 Conventional Commits 手写格式，之后转为 Changesets 生成的 ## x.y.z / ### Minor Changes / ### Patch Changes 三段式结构。以下表格按时间倒序（与原文档一致）浓缩了 0.66.0 之后 CLI 成熟期 以及早期关键节点的实质性变更：

版本	类型	实质性变更要点
0.103.0 / 0.102.0 / 0.101.x	Minor/Patch	0.102.0 chore! 升级 fuel-core 至 0.44.0；0.101.2 支持 Node 24、弃用 Node 18；0.101.3 升级 esbuild
0.100.x	Patch	0.100.0 改进 fuels init 目录检测、abi-typegen 优先 .ts 而非 .d.ts；0.100.4 重新导出 @fuels/vm-asm 为 FuelAsm、抑制构建噪声
0.99.0	Patch	修复 fuels dev 在编译错误后卡死；允许 fuels 配置回调（onSuccess/onDeploy 等）为异步
0.98.0	Minor(!)	provider 初始化恢复同步（breaking）；@fuel-ts/interfaces 内容重新分布（breaking）；fuels init 支持 --fuel-core-port；修复 fuels dev 中 providerUrl 的读取
0.97.0	Minor(!)	onDeploy 支持全部 Sway 程序类型（contracts/scripts/predicates，breaking）；缓存最新 fuels 版本
0.96.x–0.94.x	Patch	0.95.0 升级 fuel-core@0.37.1/0.38.0 与 forc@0.65.1；0.94.7 为 fuels deploy 加入 proxy 合约支持并提示版本过时；0.94.9 支持部署 scripts 与 predicates、proxy 带 storage 部署
0.94.0	Minor(!)	prettify typegen api（breaking）；弃用 FUEL_NETWORK_URL 与 LOCAL_NETWORK_URL 环境变量；错误类型统一切换到 FuelError
0.92.x	Minor/Patch	0.92.0 deployContract 改为非阻塞调用（breaking）、修复 launchNode.cleanup；0.92.1 新增压缩后的 minified 浏览器分发
0.91.0	Minor(!)	分离各 CLI 命令 onSuccess 回调事件（breaking）；升级 commander 至 12.1.0；CLI 停止向 process.stdout/stderr 管道输出、改用 console.log
0.90.0	Minor(!)	升级 fuel-core@0.28.0（breaking）；移除 beta-5 网络配置；新增 launchTestNode 测试工具；支持 bun
0.89.0	Minor(!)	移除 forc 与 fuel-core 内置二进制（breaking），改为独立安装；新增 node 命令；umbrella 包导出 FuelError
0.88.0–0.83.0	Patch/Minor	0.86.0 让 CLI 忽略 Sway libraries；0.85.0 CLI 节点改用 in-memory DB（替代 rocks DB）；0.83.0 升级 fuel-core@0.24.3
0.81.0–0.80.0	Minor	修复 ESM 分发运行时错误；0.80.0 全面增强交易错误处理与消息格式化
0.75.0	Patch	新增 forcBuildFlags 配置属性
0.74.0	Minor(!)	重构 Account 相关包（breaking）
0.72.0	Minor(!)	全仓库共享同一份 chain config 与 launchNode；startFuelCore 复用 launchNode；launchNode 移除 chainConfigPath/consensusKey/useInMemoryDb/poaInstant 等专用配置，改由 args 透传
0.70.0 / 0.71.0	Minor	引入 pnpm create fuels 脚手架；为 cdnjs 构建专用 JS 文件
0.68.0	Patch	修复短生命周期节点优雅退出；fuels deploy 与 typegen 一样自动加载合约 storage slots；startFuelCore 做到包管理器无关
0.66.0	Minor	Fuels CLI 全面改版：核心命令体系 init / build / deploy / dev 正式成型
0.49.0–0.42.0	Minor/Patch	0.49.0 keystore 包改名 crypto；0.48.0 修复 Node ESM 支持并拆分浏览器独立构建；0.46.0 改用 .d.ts + declaration maps；0.44.0 全面重构包配置；0.42.0 抽取 Typegen 工具为独立包
0.37.0–0.33.0	Minor	0.37.0 为旧项目增加多类型解析支持；0.36.0 删除 @fuel-ts/constants、常量迁入各包 configs 并由 umbrella 导出；0.33.0 脚本支持 main args
0.25.0	Minor(!)	用 abi-typegen 取代 fuelchain 与 typechain-target-fuels（breaking），Typegen 进入自家维护时代
0.24.0	Minor	新增 versions 包：集中管理/校验 Fuel 工具链各组件的兼容版本
0.19.0–0.15.0	Minor/Patch	交易输出变量支持；Logs/LogData 解析（0.17.0）；bn.js 替代 bigint（0.15.0）
0.8.0 之前	—	turborepo + pnpm + tsup 构建体系落地；从 BigNumber 迁移到 BigInt；包名从 typechain 系切换到 fuels

表中只归纳了"含描述"的条目；其余大量 0.xx.x 版本仅有 "Updated dependencies [hash]" 段，属于纯依赖同步发布，不影响 fuels 自身行为，可在升级时放心跟进。

三、CLI 命令体系的成型与源码落点

CHANGELOG 中最具标志性的节点是 0.66.0：

"Total revamp of Fuels CLI, providing a frictionless onboarding experience… New essential commands includes: init、build、deploy、dev"

此后 CLI 陆续补齐 node（0.89.0）并收敛外部子命令 typegen（来自 abi-typegen 包）与 versions（来自 versions 包）。当前 fuels CLI 的全部命令注册逻辑集中在 src/cli.ts：

命令	说明（源码 description）	源码落点
fuels init	生成示例 fuels.config.ts，支持 --workspace、--contracts/-c、--scripts/-s、--predicates/-p、-o/--output、--forc-path、--fuel-core-path、--auto-start-fuel-core、--fuel-core-port（0.98.0 新增）	cli/commands/init/index.ts
fuels dev	启动 Fuel 节点并开启热重载（watch Sway 变更 → 自动 build/typegen）	cli/commands/dev/index.ts
fuels node	依据项目配置启动本地 Fuel 节点	cli/commands/node/index.ts
fuels build	编译 Sway 程序并生成 TypeScript，支持 -d/--deploy 一键连部署	build 关联逻辑
fuels deploy	向 Fuel 网络部署合约	cli/commands/deploy/index.ts
fuels typegen	从 Sway ABI JSON 生成 TypeScript	路由到 @fuel-ts/abi-typegen 的 CLI
fuels versions	检查 forc/fuel-core/SDK 版本兼容性	路由到 @fuel-ts/versions 的 CLI

全局层面还有 -D/--debug（开启详细日志）与 -S/--silent（抑制输出）两个选项（src/cli.ts）。CHANGELOG 0.91.0 将"输出改为 console.log、停止直接写入 process.stdout/stderr"正是为了让调试/静默开关能统一接管日志，这一点可从 configureLogging 钩子（onPreAction）的实现得到印证。

3.1 部署流程的版本演进

fuels deploy 能力几乎是逐版本叠加的，很适合作为"用 CHANGELOG 追踪特性"的例子：

• 0.68.0：部署时自动加载合约 storage slots（此前只有 typegen 会加载）；
• 0.94.7：支持 proxy 合约部署；
• 0.94.8：发布时重新生成 proxy 产物；
• 0.94.9：支持部署 scripts 与 predicates，并支持带 storage 的 proxy 部署；
• 0.97.0（breaking）：onDeploy 回调入参从仅 contracts 扩展为 { contracts, scripts, predicates } 全类型。

当前 deploy/index.ts 的编排顺序完整体现了上述沉淀：先 deployContracts 并把合约 ID 写入 JSON → 再 deployScripts/saveScriptFiles → deployPredicates/savePredicateFiles → 触发 config.onDeploy?.() → 最后重新执行类型生成，让生成的工厂类带上 loader 代码。

3.2 fuels dev 的开发循环

0.99.0 修复了 "fuels dev hangs after compilation errors"，0.98.0 修复了 providerUrl 读取与 pnpm 下无法终止 fuels dev 的问题，0.89.0 还修复了加载 fuels.config.ts 时读取 Sway 类型出错的问题。综合来看，dev 命令的标准循环是：读取配置文件 → （按需）自动拉起 fuel-core → 监听 Sway 源码变更 → 重新 forc build + 类型生成 → 出现编译错误时给出提示且不挂死。

四、fuels.config.ts：配置体系与默认值

fuels init 生成的模板见 cli/templates/fuels.config.hbs，从 fuels 导入 createConfig：

import { createConfig } from 'fuels';

export default createConfig({
  // 二选一：指向整个 Forc workspace，
  workspace: './sway-programs',
  // 或分别列出各类程序路径（与 workspace 互斥）
  // contracts: ['./sway-programs/contract'],
  // predicates: ['./sway-programs/predicate'],
  // scripts: ['./sway-programs/script'],

  output: './src/sway-api', // 类型生成产物输出目录

  // 以下均为可选
  forcPath: undefined,     // 自定义 forc 二进制路径
  fuelCorePath: undefined, // 自定义 fuel-core 二进制路径
  autoStartFuelCore: true, // dev/deploy 时是否自动拉起节点
  fuelCorePort: 4000,      // 本地节点端口
});

配置文件的实际加载逻辑在 cli/config/loadConfig.ts：先用 joycon 在目录树中向上解析 fuels.config.{ts,js,cjs,mjs}（找到即停），找不到则抛 CONFIG_FILE_NOT_FOUND；随后用 bundle-require + esbuild（target ES2021、platform node、format esm）现场打包执行，拿到默认导出的配置对象。代码里可以看到一组缺省值：

• contracts/scripts/predicates 缺省为空数组；
• deployConfig 缺省 {}；
• autoStartFuelCore 缺省 true，fuelCorePort 缺省 4000；
• providerUrl 取自环境变量 FUEL_NETWORK_URL，否则为 http://127.0.0.1:4000/v1/graphql（注意 0.94.0 已标记 FUEL_NETWORK_URL 弃用，最终指向的 provider 由 providerUrl 字段或后续 API 决定）；
• privateKey 缺省为从 @fuel-ts/utils 导出的 defaultConsensusKey（即测试网络的固定出块密钥）；
• forcBuildFlags（0.75.0 引入）缺省 []，若其中含 --release，buildMode 即为 release，否则为 debug。

配置校验由 validateConfig 完成（cli/config/validateConfig.ts），0.80.0 曾专门修复 "properly load env vars in create-fuels template"；0.99.0 则让 fuels 配置中的回调（如 onDeploy）支持返回 Promise，使回调内可以安全地执行异步操作。

五、围绕 fuel-core / forc 的工具链策略演变

CHANGELOG 清晰记录了 SDK 与其底层节点/编译器之间的版本绑定策略变化：

1. 内建二进制阶段：早期 fuels/@fuel-ts/forc、@fuel-ts/fuel-core 会把 forc 与 fuel-core 作为依赖捆绑安装（仓库 internal/forc、internal/fuel-core 即其实现，提供 bin.js/install.js/shared.js），0.89.0 前各类 startFuelCore、launchNode 直接依赖它们。
2. 0.89.0（breaking）：remove built-in binaries for forc and fuel-core——不再自动下载，改为显式安装工具链（参见 create-fuels 生成的 fuel-toolchain.toml、fuels.config 的 forcPath/fuelCorePath 以及 fuels versions 校验）。这是向"工具链由用户掌控"迈出的关键一步。
3. 配套升级记录：0.102.0 fuel-core@0.44.0（此前还有 0.95.0 的 0.37.1→0.38.0、0.90.0 的 0.28.0、0.83.0 的 0.24.3、0.89.1 的 0.27.0、0.27.0 的 0.15.1）。此类升级常带 chore! 破坏性标记，因为节点协议或链配置（如 0.90.0 移除 beta-5 网络）往往同时变化。
4. 运行资源：0.85.0 起 CLI 本地节点改用 in-memory DB（替代需要文件系统的 rocks DB），0.72.0 把链配置统一为 @fuel-ts/utils 导出的 defaultChainConfig/defaultConsensusKey，0.71.0 修正 fuel-core 旧 --manual_blocks_enabled 标记为 --debug，0.68.0 完善短生命周期节点的优雅关闭。

六、本地测试节点：launchNode 与 launchTestNode

fuels 不仅面向 CLI，还向测试场景提供节点启动工具，相关导出在 src/setup-launch-node-server.ts（0.91.0 起随 fuels/test-utils、fuels/cli-utils 子路径一起暴露）：

• 0.72.0（breaking）：startFuelCore 改为复用 launchNode；同时为保持参数收敛，launchNode 删除了 chainConfigPath/consensusKey/useInMemoryDb/poaInstant 四个专用参数，改为全部通过 args 透传给 fuel-core：

  const { cleanup, ip, port } = await launchNode({
    args: ['--poa-interval-period', '750ms', '--poa-instant', 'false'],
  });
  

• 0.90.0：新增 launchTestNode 工具（一条 API 拉起节点并返回地址/密钥/钱包等测试脚手架）。

• 0.92.0：修复 launchNode.cleanup 在测试组最后一条用例中未能杀死节点的问题，避免测试进程残留。

• 0.98.0（breaking）：provider 初始化回归 同步 方式（此前曾改异步），因此 Provider.create 类的调用方式需同步适配。

仓库内 internal/check-tests 以及 packages/fuel-gauge（80+ 个集成测试文件）、apps/demo-bun-fuels、apps/demo-fuels 都是这些节点工具的实际消费方，例如 apps/demo-fuels 的 turbo.json/fuels.config.ts 演示了最小配置即可跑通测试。

七、类型生成（Typegen）的自我演进

fuels 的一大职责是 ABI → TypeScript 类型化客户端 的生成能力：

• 0.25.0（breaking）：用自研 @fuel-ts/abi-typegen 替换第三方 fuelchain 与 typechain-target-fuels。这是 fuels-ts 摆脱对 typechain 生态依赖的分水岭。
• 0.37.0：在旧项目（legacy ABI 风格）上也支持多类型解析。
• 0.42.0：把 Typegen 工具函数与测试工具抽取为独立包，降低耦合。
• 0.94.0（breaking）：prettify typegen api——生成的类型与工厂 API 全面改版（生成物中的类方法命名、参数类型风格变化），属升级时需重点回归的点。
• 0.100.0：abi-typegen 在遇到同名类型时优先使用 .ts 源而非 .d.ts 声明文件。
• 0.68.0：typegen 自动加载合约 storage slots 的能力被 deploy 命令复用。

在仓库中，类型生成全流程的测试覆盖见 packages/abi-typegen（AbiTypeGen.test.ts、runTypegen.test.ts 等），应用示例见 apps/demo-typegen（contract/script/predicate 三种 Sway 程序 + demo.test.ts）。

八、聚合包出口与模块架构的重构史

由于 fuels 是统一命名空间，任何底层包拆分都会在 CHANGELOG 留下 ! 记录，反向阅读即可得到 SDK 的架构变迁图：

• 0.36.0：删除 @fuel-ts/constants，常量迁到各包的 <pkg>/configs 子路径，并由 umbrella 一并导出（对应今天 index.ts 中多行 export * from '@fuel-ts/xxx/configs'）。
• 0.49.0：keystore 包更名为 crypto。
• 0.64.1：fuel-ts/utils 纳入 umbrella。
• 0.74.0（breaking）：Account 相关包重构（wallet/signer/hdwallet/wallet-manager/connectors 收拢为 @fuel-ts/account，对应当前 packages/account 下的 wallet/、hdwallet/、predicate/、providers/、signer/ 目录）。
• 0.98.0（breaking）：@fuel-ts/interfaces 内容重新分布到各归属包。
• 0.89.0：umbrella 导出 FuelError（来自 @fuel-ts/errors），0.94.0 全面把错误类型切换到 FuelError 统一体系。
• 0.100.4：export * as FuelAsm from '@fuels/vm-asm'，方便需要直接拼接/内联 Fuel VM 汇编的用户。

九、构建产物与运行环境支持

一份 SDK 的成熟度往往体现在分发形态上，fuels 在此的演进包括：

• 0.35.0：统一调整所有包的导出字段（main/module/types/exports）。
• 0.46.0：弃用 publishConfigs，使用 .d.ts 声明 + .d.ts.map 声明映射。
• 0.48.0：修复 Node ESM 支持，并为 Browser 提供独立构建（index.browser）；0.44.2 起通过代理 bin 入口修复本地符号链接问题。
• 0.81.0（breaking）：修复 ESM 分发的运行时错误，ESM 成为一等公民。
• 0.92.1：新增 minified 浏览器产物（见 package.json 中 build:minified 对 browser.mjs 的 uglify 处理，dist/browser.min.mjs）。
• 0.90.0：官方支持 bun 运行时（仓库 apps/demo-bun-fuels 即验证示例）。
• 0.101.2：支持 Node 24，并标记 Node 18 弃用；当前 package.json 的 engines 为 ^20.0.0 || ^22.0.0 || ^24.0.0。
• 0.71.0/0.70.0：为 cdnjs 集成构建专门的 JS 文件。

十、如何正确阅读这份 CHANGELOG 并规划升级

fuels 的 CHANGELOG 由 Changesets 自动化生成，解读时抓住三个要点即可：

1. 看 Minor Changes 段的 !：feat! / fix! / chore! 中的 ! 表示破坏性变更（semver breaking），如 0.98.0 provider 同步初始化、0.94.0 prettify typegen api、0.97.0 onDeploy 全类型化、0.102.0 fuel-core@0.44.0 升级。这些是升级前必须回归测试的版本。
2. 看 Patch Changes 中带描述的条目：它们包含真实的行为修复或小特性（如 0.99.0 dev 卡死、0.94.9 脚本/谓词部署），对应各自版本应跟进；而只有 Updated dependencies [hash] 的段落通常只是把子包版本抬齐，无感知风险。
3. 用 fuels versions 做工具链体检：versions 包（0.24.0 引入）会检查你的 forc/fuel-core/SDK 组合是否匹配，0.94.7 起 CLI 还会在检测到版本过旧时主动提示，0.97.0 起会缓存"最新版本"查询结果以减少网络请求。

升级实操建议：先看目标版本区间内所有带 ! 的 Minor 条目，对照本文第六至九节的演进路径确认自己用到的 API 是否受影响；随后用仓库自带的 apps/demo-fuels、apps/demo-typegen 与 packages/fuel-gauge 测试集做冒烟验证；最后回归 fuels init/build/deploy/dev 四个主命令及 launchTestNode 测试用例。

结语

packages/fuels/CHANGELOG.md 与其说是一份流水账，不如说是一部 fuels-ts 顶层 SDK 的产品路线图：从 typechain 时代的试验品，成长为集 聚合导出 + 完备 CLI + 类型生成 + 本地节点 + 多运行时分发 于一体的 SDK 入口。结合 src/cli.ts、src/index.ts 与 cli/config/loadConfig.ts 等源码阅读这份日志，你可以精确地判断每个版本改变了什么、为何改变，以及在你的 Fuel 应用升级时应当重点回归哪些环节。