在 fuels-ts 中运行本地 Fuel 节点：`fuels node`、`fuel-core` 与 `launchTestNode` 使用全指南-北京尧图网络

区块链Web3【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址https://gitcode.com/GitHub_Trending/fu/fuels-ts点击查看免费下载导读本文围绕 fuels-tsFuel Network TypeScript SDK中“如何运行本地 Fuel 节点”这一核心开发环节展开系统讲解两条官方支持路径直接使用fuel-core二进制程序以及通过 TS SDK 提供的fuels nodeCLI 命令启动。在此基础上进一步深入fuels dev热重载开发模式与launchTestNode测试节点工具并结合仓库源码说明其底层实现原理。读完本文你将能独立完成本地节点的启动、配置、接入与测试集成覆盖从开发到单元测试的完整本地工作流。本文对应官方文档running-a-local-fuel-node.md。文档中的命令、配置与行为均以当前仓库实际实现为准。一、前置条件先安装 Fuel Toolchain在启动任何本地 Fuel 节点之前需要先安装 Fuel Toolchain 中明确指出使用本库之前必须安装 Fuel Toolchain。随后在你的项目中添加fuels依赖当前仓库各 demo 应用均使用fuels包例如 demo-fuels/package.jsonnpm install fuels --save # 或 pnpm add fuels # 或 bun add fuels二、两条启动路径fuel-core二进制 vsfuels nodeCLI官方文档给出的速览表如下启动方式命令用途Fuel 二进制fuel-core直接运行一个本地 Fuel 节点TS SDKfuels node通过fuelsCLI 启动本地节点两条路径各有适用场景fuel-core二进制适合需要对节点启动参数有完全掌控的场景例如手动指定端口、快照目录、链配置等fuels node基于项目内已有的fuels.config.ts配置启动节点与项目构建链路天然集成无需手动拼装启动参数。原始文档中曾被考虑过的forc node命令对应 Forc 工具链的节点子命令目前仍处于注释状态说明官方当前推荐的本地节点方案就是上述两种。三、方式一使用fuels node启动节点3.1 前提先生成fuels.config.tsfuels node命令要求项目根目录存在fuels.config.ts配置文件。官方推荐用fuels init命令生成见 commands.md 的fuels init小节。对于使用 Forc workspace 的项目一条命令即可生成最小配置npx fuels init --workspace ./sway-programs --output ./src/sway-programs-api生成的fuels.config.ts最小配置如下完整示例见 demo-fuels/fuels.config.minimal.tsimport { createConfig } from fuels; export default createConfig({ workspace: ./sway-programs, // forc workspace output: ./src/sway-programs-api, });fuels init的常用选项包括选项说明--path path项目根目录默认当前目录-w, --workspace pathForc workspace 相对路径-c, --contracts [paths...]合约相对路径列表-s, --scripts [paths...]脚本相对路径列表-p, --predicates [paths...]谓词相对路径列表-o, --output pathTypeScript 生成输出目录--forc-path pathforc二进制路径--fuel-core-path pathfuel-core二进制路径--auto-start-fuel-coredev命令期间自动启动fuel-core节点--fuel-core-port port本地fuel-core节点使用的端口-h, --help显示帮助init之后的项目布局. ├── sway-programs # forc workspace ├── src │ └── sway-programs-api # 类型生成输出目录 ├── fuels.config.ts └── package.json3.2 运行fuels nodenpx fuels node该命令会启动一个短生命周期的fuel-core节点short-lived这意味着它主要用于本地开发与调试不会常驻后台。3.3 源码剖析fuels node到底做了什么从源码看fuels node命令的实现位于 packages/fuels/src/cli/commands/node/index.ts通过loadConfig(config.basePath)加载fuels.config.ts调用autoStartFuelCore(config)启动fuel-core子进程#L43-L44使用chokidar监听fuels.config.ts与snapshotDir的变化一旦文件变更就关闭旧节点、重新加载配置并重启新节点#L28-L41因此修改配置无需手动重启每次成功重启后调用配置中的onNode回调#L37。节点本身由autoStartFuelCore完成见 packages/fuels/src/cli/commands/dev/autoStartFuelCore.ts其关键行为默认绑定0.0.0.0对外地址127.0.0.1端口取config.fuelCorePort未配置时用portfinder从 4000 开始寻找第一个空闲端口#L26以--db-type in-memory方式启动即内存数据库进程退出数据即消失启动成功后会覆盖config.providerUrl为本地节点 URL并将config.privateKey覆盖为defaultConsensusKey#L52-L54。3.4 与节点相关的常用配置项fuels node的行为由 config-file.md 中定义的一系列配置项控制完整示例见 demo-fuels/fuels.config.full.tsimport { createConfig } from fuels; export default createConfig({ workspace: ./sway-programs, // 自动启动本地 fuel-core 节点 autoStartFuelCore: true, // 端口默认从 4000 起取第一个空闲端口 fuelCorePort: 4000, // 自定义 fuel-core 快照目录包含 chainConfig.json / metadata.json / stateConfig.json snapshotDir: ./my/snapshot/dir, // 节点启动成功并刷新后触发 onNode: (config) { console.log(fuels:onNode, { config }); }, // 默认使用系统 binaries可指定路径 forcPath: ~/.fuelup/bin/forc, fuelCorePath: ~/.fuelup/bin/fuel-core, });要点说明autoStartFuelCore置为true时自动启动节点并覆盖providerUrl置为false时你必须自行启动fuel-core并通过providerUrl手动指定节点地址providerUrl默认http://127.0.0.1:4000/v1/graphqlsnapshotDir仅fuels dev/fuels node使用且只在autoStartFuelCore为true时生效目录内可放置chainConfig.json、metadata.json、stateConfig.json来定制链的创世状态。四、方式二直接运行fuel-core二进制如果你希望完全绕开 CLI 封装可以手动安装并运行fuel-core二进制程序fuel-core run --ip 127.0.0.1 --port 4000 --db-type in-memory运行本地节点后在 TS SDK 中通过Provider接入示例见 connecting-to-the-network.md 及 snippets/connecting-to-the-network.tsimport { Provider } from fuels; const NETWORK_URL http://127.0.0.1:4000/v1/graphql; const provider new Provider(NETWORK_URL); const baseAssetId await provider.getBaseAssetId(); const chainId await provider.getChainId(); const gasConfig await provider.getGasConfig();采用这种方式时需要手动配置fuels.config.ts中的providerUrl因为不会自动覆盖export default createConfig({ workspace: ./sway-programs, output: ./src/sway-programs-api, providerUrl: http://127.0.0.1:4000/v1/graphql, });五、开发模式fuels dev与热重载除了fuels nodefuels dev是本地开发体验的进阶选择。根据 commands.md 的fuels dev小节它会做三件事自动启动一个短生命周期的fuel-core节点对应配置项autoStartFuelCore启动时先执行一次build与deploy监听你的 Forc workspace每次变更都重新构建、重新生成类型定义与工厂类、重新部署。在dev模式下每次更新 workspace 中的合约都会按照你配置的output目录重新生成类型定义与工厂类如果它被其他构建系统如next dev纳入还可以触发自动重编译 / 自动刷新。得益于autoStartFuelCore在启动节点后自动覆盖providerUrl与privateKey你无需关心本地节点地址SDK 会直接与自动启动的节点通信。这正是fuels node/fuels dev相比手动运行fuel-core的便利之处。六、在单元测试中启动节点launchTestNode除了命令行方式你还可以在.ts单元测试内部直接拉起一个临时 Fuel 节点。官方文档 launching-a-test-node.md 提供了launchTestNode工具函数源码位于 packages/contract/src/test-utils/launch-test-node.ts。它可以在一次调用中完成启动短生命周期的fuel-core节点、创建自定义Provider、生成钱包、部署合约等全部准备工作。6.1 显式资源管理using自动清理launchTestNode返回的对象实现了Symbol.dispose源码#L177因此支持 TypeScript 5.2 引入的显式资源管理explicit resource managementimport { launchTestNode } from fuels/test-utils; using launched await launchTestNode(); // launched.cleanup() 会在 launched 离开块作用域时被自动调用使用using前需要调整tsconfig.json{ compilerOptions: { target: es2022, lib: [es2022, esnext.disposable] } }要求TypeScript ≥ 5.2、编译目标为es2022或以下、lib包含esnext或esnext.disposable。6.2 标准 API手动调用cleanup()如果不使用或无法使用显式资源管理按常规const声明即可但必须手动调用.cleanup()来销毁节点const launchedTestNode await launchTestNode(); // 运行你的测试…… launchedTestNode.cleanup();6.3 返回值provider / wallets / contractslaunchTestNode返回{ provider, wallets, contracts, cleanup }。基本用法示例来自 snippets/launching-a-test-node.tsimport { CounterFactory } from ./typegend/contracts/CounterFactory; using launched await launchTestNode({ contractsConfigs: [CounterFactory], }); const { contracts: [contract], provider, wallets } launched; const { waitForResult } await contract.functions.get_count().call(); const response await waitForResult();6.4 配置钱包walletsConfig通过walletsConfig可以精细控制创世区块中的钱包与资产分布配置类型定义见 packages/account/src/test-utils/wallet-config.ts字段含义count生成的钱包数量assets数字表示每个钱包拥有的资产种类数含基础资产TestAssetId[]表示除基础资产外指定的资产 ID 列表coinsPerAsset每种资产对应的 UTXO 币数量amountPerCoin每个币的金额messages预置到钱包的链上消息recipient会被覆盖为钱包地址示例来自 snippets/launch-test-node-wallets.tsimport { launchTestNode, TestAssetId } from fuels/test-utils; using launched await launchTestNode({ walletsConfig: { count: 3, assets: [TestAssetId.A, TestAssetId.B], coinsPerAsset: 5, amountPerCoin: 100_000, }, }); const { wallets: [wallet1, wallet2, wallet3] } launched;从实现上看wallet-config.tsWalletsConfig会根据这些配置在stateConfig中生成对应的coins与messages写入快照的创世状态。TestAssetId预置了A、B两个固定资产也支持TestAssetId.random(n)生成随机资产见 packages/account/src/test-utils/test-asset-id.ts。6.5 部署合约contractsConfigscontractsConfigs接受合约工厂类或带细粒度控制的对象using launched await launchTestNode({ walletsConfig: { count: 4, assets: TestAssetId.random(2), coinsPerAsset: 2, amountPerCoin: 1_000_000, messages: [new TestMessage({ amount: 1000 })], }, contractsConfigs: [ { factory: CounterFactory, walletIndex: 3, // 使用第 4 个钱包部署 options: { storageSlots: [] }, }, ], }); const { contracts: [counterContract], wallets: [wallet1, wallet2, wallet3, wallet4] } launched;部署逻辑见 launch-test-node.ts逐个调用工厂的deploy(wallet, options)walletIndex指定部署所用钱包默认第 0 个options透传给ContractFactory.deploy如storageSlots。6.6 自定义节点行为nodeOptions允许你传入自定义参数包括args透传给fuel-core的附加参数与snapshotConfig覆盖链配置 / 状态配置process.env.DEFAULT_FUEL_CORE_ARGS --tx-max-depth 20; // 注意nodeOptions.args 会覆盖上述环境变量中的值 const nodeWithCustomArgs await launchTestNode(); process.env.DEFAULT_FUEL_CORE_ARGS ; nodeWithCustomArgs.cleanup();还支持通过DEFAULT_CHAIN_SNAPSHOT_DIR环境变量指向自定义快照目录包含metadata.json、chainConfig、stateConfig或者直接用nodeOptions.snapshotConfig覆盖链配置例如修改基础资产 IDconst [baseAssetId] TestAssetId.random(); using launched await launchTestNode({ nodeOptions: { snapshotConfig: { chainConfig: { consensus_parameters: { V2: { base_asset_id: baseAssetId.value }, }, }, }, }, });这些快照合并与参数解析逻辑分别位于 launch-test-node.ts 的getChainSnapshot与getFuelCoreArgs函数中。6.7 节点启动的底层实现无论 CLI 还是测试工具最终都通过 packages/account/src/test-utils/launchNode.ts 的launchNode函数以子进程方式拉起fuel-core在临时目录中写入metadata.json、chainConfig.json、stateConfig.json#L187-L217使用spawn执行fuel-core run携带--ip、--port、--db-type、--snapshot、--consensus-key等参数#L219-L240通过监听进程 stderr 中的Binding GraphQL provider to日志判断节点就绪并解析出真实 GraphQL 地址#L295-L321提供cleanup()负责杀掉子进程并清理临时目录同时挂载了exit、SIGINT等进程信号处理以保证资源释放#L262-L338。理解了这一层你就明白为什么fuels node、fuels dev与launchTestNode都能“一键起节点”——它们共享同一套fuel-core子进程管理机制。七、更多参考资源React 示例react-example.md演示在 React 应用中使用 fuels-ts 的完整流程CDN 用法cdn-usage.md不经过打包器直接在浏览器中以 CDN 方式使用CLI 全部命令commands.md涵盖init、build、deploy、dev、node、typegen、versions配置项详解config-file.md接入本地节点的官方 RPC 地址本地节点地址即http://127.0.0.1:4000/v1/graphql与 connecting-to-the-network.md 中列出的 Mainnet / Testnet 地址对应真实项目参考本仓库的 demo-fuels含完整与最小配置示例、create-fuels-counter-guide/fuels.config.ts演示如何结合dotenv从.env加载端口与 provider 配置。小结本地节点是 fuels-ts 开发与测试的基石日常调试可用fuels node/fuels dev借助fuels.config.ts一键启动并热重载对节点有完全控制需求时可手动运行fuel-core二进制单元测试则统一交给launchTestNode快速拉起隔离环境。理解它们共享的launchNode子进程机制与快照生成逻辑能帮助你在遇到端口占用、节点启动失败或创世状态异常时快速定位问题。赞分享区块链Web3【免费下载链接】fuels-tsFuel Network Typescript SDK项目地址https://gitcode.com/GitHub_Trending/fu/fuels-ts点击查看免费下载相关推荐Fuels SDK 测试指南通过 Fuel-Core Options 定制 launchTestNode 的快照与节点参数Fuels SDK 测试指南通过 Fuel Core Options 定制 launchTestNode 的快照与节点参数 launchTestNode 是区块链Web3fuels-rs 外部节点连接指南用 Provider::connect 接入 Testnet 与本地 fuel-core 节点fuels rs 外部节点连接指南用 Provider::connect 接入 Testnet 与本地 fuel core 节点本文围绕 fuels rs区块链后端使用 Fuel Rust SDK 连接 Fuel 节点Provider、Testnet/本地 fuel-core 与测试用临时节点全指南使用 Fuel Rust SDK 连接 Fuel 节点Provider、Testnet/本地 fuel core 与测试用临时节点全指南 Fuel Rust区块链后端上一篇Redux-Saga测试覆盖率确保异步逻辑的全面测试下一篇10个必备Scoop扩展让Windows包管理效率提升300%的秘密武器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

在 fuels-ts 中运行本地 Fuel 节点：`fuels node`、`fuel-core` 与 `launchTestNode` 使用全指南

相关推荐

YOLOv5+大疆Tello TT无人机目标识别追踪与测距实战

南开软院96分C子集编译器：手写四阶段流水线实战

DCS与Tricon系统GPS时钟同步改造：SOE时间戳混乱的根治方案

更多资讯

GB/T31455.1-2025深度解读：BRT智能系统开发落地关键路径

刚刚，MarkItDown 再次登顶 GitHub 榜：这次刷屏的『重新登顶』到底靠什么翻红？

SSM+Vue理发店管理系统：毕设选题到答辩完整指南

对话模型记忆层实战：给无状态API加上持久记忆

多Agent协作系统实战：构建数字机构框架与踩坑指南

C++内存布局实战：结构体对齐、虚表与堆栈的底层真相

今日更新

再见，SSE！你好，Streamable HTTP！轻松开发 Streamable HTTP MCP Server 并接入 TaoToken

工业软件标准化路线图：国产替代的落地施工图

VCMI安卓版实操指南：原生运行英雄无敌3的3步技术落地

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？