Forc Reference 完全指南Sway 生态的 Fuel Orchestrator 命令行工具箱【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/swayForcFuel Orchestrator是 Sway 智能合约开发的核心命令行工具集对标 Rust 生态中的 cargo负责项目脚手架、构建、格式化、测试、部署与依赖管理等全链路工作流。本篇指南以官方 Forc 参考文档为主体结合本仓库forc目录下的真实 CLI 实现源码系统讲解 Forc 的命令体系、Manifest 配置、依赖管理、工作区与插件机制帮助你从零上手并深入理解 Sway 项目的构建原理。一、Forc 是什么Forc 是 Fuel 生态的开发者工具编排器为使用 Sway 语言的开发者提供了一系列工具与命令覆盖以下典型场景搭建scaffolding一个新的 Sway 项目格式化formattingSway 源码运行脚本scripts部署合约deploying contracts测试合约testing contracts以及更多围绕 Fuel 开发的工作流。如果你有 Rust 背景可以把forc理解为 Sway 世界的cargo它统一管理包、依赖与构建产物让开发者不必关心底层编译链的细节。从源码层面看Forc 的 CLI 定义位于 forc/src/cli/mod.rs程序入口在 forc/src/main.rs。入口仅做一件事——调用forc::cli::run_cli()启动异步 CLI 主循环#[tokio::main] async fn main() - ForcCliResult() { forc::cli::run_cli().await.into() }run_cli()内部通过 clap 解析子命令并把每个子命令分派到对应的exec函数Forc::Add(command)→add::exec(command)Forc::Build(command)→build::exec(command)Forc::Test(command)→test::exec(command)Forc::Plugin(args)→ 查找并执行外部插件forc-unknown-subcommand这个分派表forc/src/cli/mod.rs是理解整个 Forc 命令体系的最佳入口。二、Forc CLI 命令全景Forc 内置了 16 个原生子命令全部由 clap 派生宏定义在 forc/src/cli/mod.rs 的Forc枚举中同时预留了Plugin(VecString)作为未知子命令的兜底交给forc-subcommand形式的可执行文件处理。命令别名作用forc add—添加依赖到Forc.tomlforc addr2line—将字节码地址映射回源码位置forc buildb编译当前或指定项目forc check—检查当前或指定项目不生成字节码forc clean—删除项目构建产物out目录forc completions—生成 shell 自动补全脚本forc new/forc init—新建 / 初始化项目forc parse-bytecode—解析字节码为可读指令forc testt运行测试forc remove—移除依赖forc update—更新依赖版本forc plugins—列出已安装插件forc template—基于模板生成项目forc contract-id—计算合约 IDforc predicate-root—计算谓词根哈希此外Forc 还提供一组全局选项在Opt结构体中定义作用于所有子命令-v/--verbose输出详细日志可叠加使用提高级别-s/--silent静默所有输出-L/--log-level LEVEL设置日志级别取值来自tracing的LevelFilter。这些全局选项在 forc/src/cli/mod.rs 中声明并统一传给init_tracing_subscriber初始化追踪器。2.1 构建命令forc buildforc build是日常使用最频繁的命令其输出取决于项目类型见 forc/src/cli/commands/build.rsscript、predicate、contract项目会生成二进制字节码文件project-name.binscript项目额外生成字节码哈希文件project-name-bin-hash使用fuel_crypto::Hasherpredicate项目额外生成根哈希文件project-name-bin-root使用fuel_tx::Contract::root_from_codecontract与library项目还会生成公开 ABI 的 JSON 文件project-name-abi.json。常用用法# 编译当前项目 forc build # 从指定路径编译 forc build --path PATH # 锁定依赖版本、不更新依赖的情况下编译 forc build --path PATH --locked # 使用发布构建配置 forc build --release # 附带构建测试 forc build --tests--locked、--offline、--terse等构建选项最终会被 forc/src/ops/forc_build.rs 中的opts_from_cmd组装成pkg::BuildOpts再调用forc-pkg的build_with_options完成真正的包解析与编译。forc build与forc check的区别在于check只做解析、类型检查等语义分析不产出字节码。2.2 项目脚手架forc new/forc initforc new NAME在新建目录中创建一个完整项目forc init在当前目录初始化项目两者都支持--workspace标志用于创建空工作区。生成的项目包含Forc.toml清单文件与src/main.sw源码文件开箱即得一个可forc build的最小工程。仓库中examples/目录下的 40 余个示例如 examples/counter、examples/wallet_abi就是一个个可以直接forc build/forc test的成品项目。三、Manifest 清单文件Forc.toml 完全参考每个 Sway 包都必须有一个Forc.toml清单文件TOML 格式。本节完整展开 manifest 参考文档docs/book/src/forc/manifest_reference.md的全部字段。3.1[project]段[project]定义了一个 Sway 项目主要字段如下字段必填默认值说明name是—项目名称version否—项目版本description否—项目描述authors否—作者列表organization否—组织名license否—项目许可证homepage/repository/documentation否—相关 URLcategories/keywords否—分类与关键词entry否main.sw编译器解析的入口文件implicit-std否true是否隐式添加随当前 forc 版本附带的std依赖非特殊情况保持默认forc-version否—项目正常工作所需的最低 forc 版本metadata否—供外部工具存储配置的元数据段experimental否—编译时启用或禁用的实验特性一个完整的示例含可选字段与元数据[project] authors [user] entry main.sw description Wallet contract version 1.0.0 homepage https://example.com/ repository https://example.com/ documentation https://example.com/ organization Fuel_Labs license Apache-2.0 name wallet_contract categories [example] keywords [example] experimental { some_feature true, some_other_feature false } [project.metadata] indexing { namespace counter-contract, schema_path out/release/counter-contract-abi.json }元数据段[project.metadata][project.metadata]为外部工具和插件提供了一个在Forc.toml中存放自身配置的专属空间。关键约定元数据键名是任意的不必与工具名一致元数据可定义在工作区级[workspace.metadata]与项目级[project.metadata.any_name_here]两层项目级元数据应优先于工作区级Forc 本身不解析元数据内容插件开发者自行负责解析与合并逻辑典型用途包括文档生成设置、格式化配置、调试器选项、钱包集成、合约索引、测试框架等。# 工作区级元数据 [workspace.metadata] my_tool { shared_setting value } # 项目级元数据 [project.metadata.indexing] namespace counter-contract schema_path out/release/counter-contract-abi.json3.2[dependencies]段依赖可用以下字段声明version期望的依赖版本namespace可选registry 源关联的命名空间path本地依赖路径git托管依赖的 Git 仓库 URLbranch/tag/rev从 Git 仓库拉取的指定分支 / 标签 / commit。依赖的完整用法见下文第四节以及 docs/book/src/forc/dependencies.md。3.3[network]段定义 forc 交互的网络字段url默认值为http://127.0.0.1:4000即本地 Fuel 节点默认地址。3.4[build-profile.*]段构建配置[build-profile]表用于定制编译设置调试输出等每个 manifest 隐含两个默认 profiledebug与release。可用字段如下字段默认值说明print-astfalse是否打印生成的 ASTprint-dca-graphfalse是否打印死代码分析DCA图GraphViz DOT 格式print-dca-graph-url-format—DOT 文件中使用的 URL 格式VS Code 示例vscode://file/{path}:{line}:{col}print-irfalse是否打印生成的 Sway IR中间表示print-asmfalse是否打印生成的汇编tersefalse精简模式限制警告与错误输出time_phasesfalse是否输出编译各阶段耗时include_testsfalse是否在解析、类型检查、代码生成中包含测试函数forc test会自动置为trueerror_on_warningsfalse是否将警告视为错误backtraceall_except_neverdebug/only_alwaysreleasepanic 回溯包含哪些函数可取all、all_except_never、only_always、none自定义 profile 示例[build-profile.debug] print-asm { virtual false, allocated false, final true } print-ir { initial false, final true, modified false, passes []} terse false [build-profile.release] print-asm { virtual true, allocated false, final true } print-ir { initial true, final false, modified true, passes [dce, sroa]} terse true使用方式forc build默认走debug加--release走release自定义 profile 则用--build-profile name。注意对应的 CLI 选项如--asm all会覆盖所选 profile。例如同时传--release --asm all时最终生效的 profile 等价于print-ast false print-ir { initial false, final false, modified false, passes []} print-asm { virtual true, allocated true, final true } terse false time-phases false include-tests false error-on-warnings false experimental-private-modules false3.5[patch]段依赖覆写[patch]用于用其他副本覆盖依赖适合测试本地修改、使用未发布特性或调试依赖。覆写 Git 依赖[patch.https://github.com/fuellabs/sway] std { git https://github.com/fuellabs/sway, branch test }也可以用本地路径覆写[patch.https://github.com/fuellabs/sway] std { path /path/to/local_std_version }覆写 registry 依赖forc.pub[dependencies] std 0.70.1 [patch.forc.pub] std { path ../sway/sway-lib-std }即使std 0.70.1本应从 registry 拉取这里也会改用本地路径版本。registry 依赖同样可以用 Git 仓库覆写[patch.forc.pub] std { git https://github.com/fuellabs/sway, branch my-feature }两个重要约束键必须加引号[patch]后的每个键如[patch.forc.pub]必须加引号否则 TOML 会把点号解析为嵌套表源类型必须匹配Git patch 匹配 Git 依赖registry patch 匹配 registry 依赖。3.6[contract-dependencies]段合约依赖[contract-dependencies]声明我们的合约或脚本可能与之交互的合约集合。它让源码中引用合约 ID 变得简单无需每次部署新版本后手工更新 IDforc 会像管理库依赖一样固定pin并更新合约依赖。被声明的合约会像普通依赖一样被构建和固定但不会导入整个公开命名空间而是把各自的合约 ID 作为CONTRACT_ID常量暴露在依赖包的命名空间根部等价于在包根部声明了一个pub const[contract-dependencies] foo { path ../foo }script; fn main() { let foo_id foo::CONTRACT_ID; }由于合约 ID 是确定性计算的相同合约反复构建会得到相同 ID而链上不允许部署两个 ID 相同的合约因此需要salt因子来修改合约 ID[contract-dependencies] foo { path ../foo, salt 0x1000000000000000000000000000000000000000000000000000000000000000 }未显式指定salt的合约依赖会隐式应用全零salt。四、依赖管理拉取与发布 Sway 库Forc 的依赖管理系统支持从git、ipfs、path与社区registryforc.pub四种源拉取包这使开发者可以构建和共享 Sway 库。4.1 使用forc add添加依赖forc add dep [--path PATH] [--git URL --tag TAG] [--ipfs CID] [--contract-dep]典型示例# 从 Git 分支添加 forc add custom_lib --git https://github.com/FuelLabs/custom_lib --branch master # 从本地路径添加 forc add custom_lib --path ../custom_lib # 从 IPFS 添加 forc add custom_lib --ipfs QmYwAPJzv5CZsnA... # 从 registry 添加指定版本 forc add custom_lib0.0.1 # 添加为合约依赖 forc add my_contract --git https://github.com/example/contract --contract-dep可选参数--salt HEX自定义合约 salt--package NAME定位工作区中的特定包--manifest-path PATH指定清单文件路径。添加完成后运行forc build会自动拉取并解析依赖。⚠️ 注意使用registry源的项目目前不支持离线模式通配符声明如custom_lib *和 caret 声明如custom_lib ^0.1也尚未支持。4.2 手动编辑Forc.toml如果清单中还没有[dependencies]或[contract-dependencies]表可手动添加列出包名与其源即可# 本地路径 [dependencies] custom_lib { path ../custom_lib } # IPFS 源 custom_lib { ipfs QmYwAPJzv5CZsnA... } # registry 源 custom_lib 0.0.14.3 移除与更新依赖# 移除普通依赖 forc remove custom_lib # 移除合约依赖 forc remove my_contract --contract-dep # 针对工作区中特定包移除 forc remove custom_lib --package my_project更新依赖forc update对path与ipfs依赖无效果对带分支引用的git依赖会更新到该分支的最新 commit。五、工作区Workspaces工作区是多个包工作区成员的集合统一管理。核心要点单包可用的公共 forc 命令同样适用于工作区如forc build、forc deploy所有包共享位于工作区根目录的一个Forc.lock文件。用forc new --workspace或forc init --workspace创建空工作区。工作区清单同样写在Forc.toml中支持members与[patch]两个字段。5.1members字段[workspace] members [member1, path/to/member2]members条目使用相对工作区根目录的路径位于工作区目录内但不在members集合中的包会被忽略。5.2 工作区级[patch]用法与包级[patch]一致详见 docs/book/src/forc/manifest_reference.md但注意如果工作区清单包含 patch 表成员包中不允许再声明 patch 表。[workspace] members [member1, path/to/member2] # 工作区内所有 std 依赖都替换为 test 分支 [patch.https://github.com/fuellabs/sway] std { git https://github.com/fuellabs/sway, branch test }registry 覆写示例[workspace] members [contract-a, contract-b, script] # 所有成员改用本地自定义 std [patch.forc.pub] std { path ../custom-std }5.3 支持工作区的命令forc build构建整个工作区forc deploy按正确顺序构建并部署所有可部署成员合约forc run构建并运行工作区所有脚本forc check检查所有成员forc update检查并更新成员共享的工作区级Forc.lockforc clean清理每个成员的构建产物forc fmt格式化所有成员。仓库中的 examples/multi_contract_calls 就是一个典型的工作区示例根Forc.toml声明memberscallee与caller两个成员包共享同一份Forc.lock。六、插件机制扩展 Forc 能力插件系统允许为forc扩展超越内置命令的新命令。Fuel 生态已提供若干常用插件forc-fmt、forc-client、forc-lsp、forc-migrate等任何人都可以编写自己的插件。6.1 插件如何被调用当 forc 收到未知子命令时会查找名为forc-unknown-subcommand的可执行文件并执行forc-unknown-subcommand args这一逻辑实现在 forc/src/cli/mod.rs 的Plugin(VecString)分支与 forc/src/cli/plugin.rs 中。查看已安装插件$ forc plugins Installed Plugins: forc-install6.2 编写自己的插件插件必须命名为forc-MY_PLUGIN格式可基于模板起步。一个插件 crate 还可以通过在其 manifest 中声明多个[[bin]]目标来提供多个命令——例如forc-client插件同时提供forc deploy和forc run两个命令。插件可以用 clap 增加子命令、选项与配置以满足自身需求。提示编写插件时如果想在Forc.toml中存放工具配置请使用[project.metadata]段见 3.1 节并遵循“键名清晰、文档化、不依赖强制存在、避免键冲突”等最佳实践。七、小结从命令到源码的完整链路回顾整条工具链你可以用一张“心智地图”串起来脚手架forc new/forc init生成Forc.tomlsrc/main.sw配置Forc.toml的[project]、[dependencies]、[build-profile.*]、[patch]、[contract-dependencies]描述包的元信息与构建方式依赖forc add/forc remove/forc update管理四种来源git / ipfs / path / registry的依赖构建forc build通过 forc/src/ops/forc_build.rs 组装BuildOpts交给forc-pkg完成包解析与编译产出.bin、ABI JSON 等产物验证forc check做语义检查forc test运行测试自动启用include_tests部署与交互forc deploy、forc run、forc contract-id、forc predicate-root等命令进入链上环节扩展插件机制forc-name让社区工具无缝融入统一 CLI。如果想要更系统的按命令逐个深入可继续阅读 commands 章节索引 下对应的命令文档如 forc build想动手练习可以浏览仓库 examples 目录下的真实示例工程并参考 Sway 程序类型 中关于大库入口点选择的建议以及 实验特性 了解experimental字段的作用范围。【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Forc Reference 完全指南：Sway 生态的 Fuel Orchestrator 命令行工具箱
Forc Reference 完全指南Sway 生态的 Fuel Orchestrator 命令行工具箱【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/swayForcFuel Orchestrator是 Sway 智能合约开发的核心命令行工具集对标 Rust 生态中的 cargo负责项目脚手架、构建、格式化、测试、部署与依赖管理等全链路工作流。本篇指南以官方 Forc 参考文档为主体结合本仓库forc目录下的真实 CLI 实现源码系统讲解 Forc 的命令体系、Manifest 配置、依赖管理、工作区与插件机制帮助你从零上手并深入理解 Sway 项目的构建原理。一、Forc 是什么Forc 是 Fuel 生态的开发者工具编排器为使用 Sway 语言的开发者提供了一系列工具与命令覆盖以下典型场景搭建scaffolding一个新的 Sway 项目格式化formattingSway 源码运行脚本scripts部署合约deploying contracts测试合约testing contracts以及更多围绕 Fuel 开发的工作流。如果你有 Rust 背景可以把forc理解为 Sway 世界的cargo它统一管理包、依赖与构建产物让开发者不必关心底层编译链的细节。从源码层面看Forc 的 CLI 定义位于 forc/src/cli/mod.rs程序入口在 forc/src/main.rs。入口仅做一件事——调用forc::cli::run_cli()启动异步 CLI 主循环#[tokio::main] async fn main() - ForcCliResult() { forc::cli::run_cli().await.into() }run_cli()内部通过 clap 解析子命令并把每个子命令分派到对应的exec函数Forc::Add(command)→add::exec(command)Forc::Build(command)→build::exec(command)Forc::Test(command)→test::exec(command)Forc::Plugin(args)→ 查找并执行外部插件forc-unknown-subcommand这个分派表forc/src/cli/mod.rs是理解整个 Forc 命令体系的最佳入口。二、Forc CLI 命令全景Forc 内置了 16 个原生子命令全部由 clap 派生宏定义在 forc/src/cli/mod.rs 的Forc枚举中同时预留了Plugin(VecString)作为未知子命令的兜底交给forc-subcommand形式的可执行文件处理。命令别名作用forc add—添加依赖到Forc.tomlforc addr2line—将字节码地址映射回源码位置forc buildb编译当前或指定项目forc check—检查当前或指定项目不生成字节码forc clean—删除项目构建产物out目录forc completions—生成 shell 自动补全脚本forc new/forc init—新建 / 初始化项目forc parse-bytecode—解析字节码为可读指令forc testt运行测试forc remove—移除依赖forc update—更新依赖版本forc plugins—列出已安装插件forc template—基于模板生成项目forc contract-id—计算合约 IDforc predicate-root—计算谓词根哈希此外Forc 还提供一组全局选项在Opt结构体中定义作用于所有子命令-v/--verbose输出详细日志可叠加使用提高级别-s/--silent静默所有输出-L/--log-level LEVEL设置日志级别取值来自tracing的LevelFilter。这些全局选项在 forc/src/cli/mod.rs 中声明并统一传给init_tracing_subscriber初始化追踪器。2.1 构建命令forc buildforc build是日常使用最频繁的命令其输出取决于项目类型见 forc/src/cli/commands/build.rsscript、predicate、contract项目会生成二进制字节码文件project-name.binscript项目额外生成字节码哈希文件project-name-bin-hash使用fuel_crypto::Hasherpredicate项目额外生成根哈希文件project-name-bin-root使用fuel_tx::Contract::root_from_codecontract与library项目还会生成公开 ABI 的 JSON 文件project-name-abi.json。常用用法# 编译当前项目 forc build # 从指定路径编译 forc build --path PATH # 锁定依赖版本、不更新依赖的情况下编译 forc build --path PATH --locked # 使用发布构建配置 forc build --release # 附带构建测试 forc build --tests--locked、--offline、--terse等构建选项最终会被 forc/src/ops/forc_build.rs 中的opts_from_cmd组装成pkg::BuildOpts再调用forc-pkg的build_with_options完成真正的包解析与编译。forc build与forc check的区别在于check只做解析、类型检查等语义分析不产出字节码。2.2 项目脚手架forc new/forc initforc new NAME在新建目录中创建一个完整项目forc init在当前目录初始化项目两者都支持--workspace标志用于创建空工作区。生成的项目包含Forc.toml清单文件与src/main.sw源码文件开箱即得一个可forc build的最小工程。仓库中examples/目录下的 40 余个示例如 examples/counter、examples/wallet_abi就是一个个可以直接forc build/forc test的成品项目。三、Manifest 清单文件Forc.toml 完全参考每个 Sway 包都必须有一个Forc.toml清单文件TOML 格式。本节完整展开 manifest 参考文档docs/book/src/forc/manifest_reference.md的全部字段。3.1[project]段[project]定义了一个 Sway 项目主要字段如下字段必填默认值说明name是—项目名称version否—项目版本description否—项目描述authors否—作者列表organization否—组织名license否—项目许可证homepage/repository/documentation否—相关 URLcategories/keywords否—分类与关键词entry否main.sw编译器解析的入口文件implicit-std否true是否隐式添加随当前 forc 版本附带的std依赖非特殊情况保持默认forc-version否—项目正常工作所需的最低 forc 版本metadata否—供外部工具存储配置的元数据段experimental否—编译时启用或禁用的实验特性一个完整的示例含可选字段与元数据[project] authors [user] entry main.sw description Wallet contract version 1.0.0 homepage https://example.com/ repository https://example.com/ documentation https://example.com/ organization Fuel_Labs license Apache-2.0 name wallet_contract categories [example] keywords [example] experimental { some_feature true, some_other_feature false } [project.metadata] indexing { namespace counter-contract, schema_path out/release/counter-contract-abi.json }元数据段[project.metadata][project.metadata]为外部工具和插件提供了一个在Forc.toml中存放自身配置的专属空间。关键约定元数据键名是任意的不必与工具名一致元数据可定义在工作区级[workspace.metadata]与项目级[project.metadata.any_name_here]两层项目级元数据应优先于工作区级Forc 本身不解析元数据内容插件开发者自行负责解析与合并逻辑典型用途包括文档生成设置、格式化配置、调试器选项、钱包集成、合约索引、测试框架等。# 工作区级元数据 [workspace.metadata] my_tool { shared_setting value } # 项目级元数据 [project.metadata.indexing] namespace counter-contract schema_path out/release/counter-contract-abi.json3.2[dependencies]段依赖可用以下字段声明version期望的依赖版本namespace可选registry 源关联的命名空间path本地依赖路径git托管依赖的 Git 仓库 URLbranch/tag/rev从 Git 仓库拉取的指定分支 / 标签 / commit。依赖的完整用法见下文第四节以及 docs/book/src/forc/dependencies.md。3.3[network]段定义 forc 交互的网络字段url默认值为http://127.0.0.1:4000即本地 Fuel 节点默认地址。3.4[build-profile.*]段构建配置[build-profile]表用于定制编译设置调试输出等每个 manifest 隐含两个默认 profiledebug与release。可用字段如下字段默认值说明print-astfalse是否打印生成的 ASTprint-dca-graphfalse是否打印死代码分析DCA图GraphViz DOT 格式print-dca-graph-url-format—DOT 文件中使用的 URL 格式VS Code 示例vscode://file/{path}:{line}:{col}print-irfalse是否打印生成的 Sway IR中间表示print-asmfalse是否打印生成的汇编tersefalse精简模式限制警告与错误输出time_phasesfalse是否输出编译各阶段耗时include_testsfalse是否在解析、类型检查、代码生成中包含测试函数forc test会自动置为trueerror_on_warningsfalse是否将警告视为错误backtraceall_except_neverdebug/only_alwaysreleasepanic 回溯包含哪些函数可取all、all_except_never、only_always、none自定义 profile 示例[build-profile.debug] print-asm { virtual false, allocated false, final true } print-ir { initial false, final true, modified false, passes []} terse false [build-profile.release] print-asm { virtual true, allocated false, final true } print-ir { initial true, final false, modified true, passes [dce, sroa]} terse true使用方式forc build默认走debug加--release走release自定义 profile 则用--build-profile name。注意对应的 CLI 选项如--asm all会覆盖所选 profile。例如同时传--release --asm all时最终生效的 profile 等价于print-ast false print-ir { initial false, final false, modified false, passes []} print-asm { virtual true, allocated true, final true } terse false time-phases false include-tests false error-on-warnings false experimental-private-modules false3.5[patch]段依赖覆写[patch]用于用其他副本覆盖依赖适合测试本地修改、使用未发布特性或调试依赖。覆写 Git 依赖[patch.https://github.com/fuellabs/sway] std { git https://github.com/fuellabs/sway, branch test }也可以用本地路径覆写[patch.https://github.com/fuellabs/sway] std { path /path/to/local_std_version }覆写 registry 依赖forc.pub[dependencies] std 0.70.1 [patch.forc.pub] std { path ../sway/sway-lib-std }即使std 0.70.1本应从 registry 拉取这里也会改用本地路径版本。registry 依赖同样可以用 Git 仓库覆写[patch.forc.pub] std { git https://github.com/fuellabs/sway, branch my-feature }两个重要约束键必须加引号[patch]后的每个键如[patch.forc.pub]必须加引号否则 TOML 会把点号解析为嵌套表源类型必须匹配Git patch 匹配 Git 依赖registry patch 匹配 registry 依赖。3.6[contract-dependencies]段合约依赖[contract-dependencies]声明我们的合约或脚本可能与之交互的合约集合。它让源码中引用合约 ID 变得简单无需每次部署新版本后手工更新 IDforc 会像管理库依赖一样固定pin并更新合约依赖。被声明的合约会像普通依赖一样被构建和固定但不会导入整个公开命名空间而是把各自的合约 ID 作为CONTRACT_ID常量暴露在依赖包的命名空间根部等价于在包根部声明了一个pub const[contract-dependencies] foo { path ../foo }script; fn main() { let foo_id foo::CONTRACT_ID; }由于合约 ID 是确定性计算的相同合约反复构建会得到相同 ID而链上不允许部署两个 ID 相同的合约因此需要salt因子来修改合约 ID[contract-dependencies] foo { path ../foo, salt 0x1000000000000000000000000000000000000000000000000000000000000000 }未显式指定salt的合约依赖会隐式应用全零salt。四、依赖管理拉取与发布 Sway 库Forc 的依赖管理系统支持从git、ipfs、path与社区registryforc.pub四种源拉取包这使开发者可以构建和共享 Sway 库。4.1 使用forc add添加依赖forc add dep [--path PATH] [--git URL --tag TAG] [--ipfs CID] [--contract-dep]典型示例# 从 Git 分支添加 forc add custom_lib --git https://github.com/FuelLabs/custom_lib --branch master # 从本地路径添加 forc add custom_lib --path ../custom_lib # 从 IPFS 添加 forc add custom_lib --ipfs QmYwAPJzv5CZsnA... # 从 registry 添加指定版本 forc add custom_lib0.0.1 # 添加为合约依赖 forc add my_contract --git https://github.com/example/contract --contract-dep可选参数--salt HEX自定义合约 salt--package NAME定位工作区中的特定包--manifest-path PATH指定清单文件路径。添加完成后运行forc build会自动拉取并解析依赖。⚠️ 注意使用registry源的项目目前不支持离线模式通配符声明如custom_lib *和 caret 声明如custom_lib ^0.1也尚未支持。4.2 手动编辑Forc.toml如果清单中还没有[dependencies]或[contract-dependencies]表可手动添加列出包名与其源即可# 本地路径 [dependencies] custom_lib { path ../custom_lib } # IPFS 源 custom_lib { ipfs QmYwAPJzv5CZsnA... } # registry 源 custom_lib 0.0.14.3 移除与更新依赖# 移除普通依赖 forc remove custom_lib # 移除合约依赖 forc remove my_contract --contract-dep # 针对工作区中特定包移除 forc remove custom_lib --package my_project更新依赖forc update对path与ipfs依赖无效果对带分支引用的git依赖会更新到该分支的最新 commit。五、工作区Workspaces工作区是多个包工作区成员的集合统一管理。核心要点单包可用的公共 forc 命令同样适用于工作区如forc build、forc deploy所有包共享位于工作区根目录的一个Forc.lock文件。用forc new --workspace或forc init --workspace创建空工作区。工作区清单同样写在Forc.toml中支持members与[patch]两个字段。5.1members字段[workspace] members [member1, path/to/member2]members条目使用相对工作区根目录的路径位于工作区目录内但不在members集合中的包会被忽略。5.2 工作区级[patch]用法与包级[patch]一致详见 docs/book/src/forc/manifest_reference.md但注意如果工作区清单包含 patch 表成员包中不允许再声明 patch 表。[workspace] members [member1, path/to/member2] # 工作区内所有 std 依赖都替换为 test 分支 [patch.https://github.com/fuellabs/sway] std { git https://github.com/fuellabs/sway, branch test }registry 覆写示例[workspace] members [contract-a, contract-b, script] # 所有成员改用本地自定义 std [patch.forc.pub] std { path ../custom-std }5.3 支持工作区的命令forc build构建整个工作区forc deploy按正确顺序构建并部署所有可部署成员合约forc run构建并运行工作区所有脚本forc check检查所有成员forc update检查并更新成员共享的工作区级Forc.lockforc clean清理每个成员的构建产物forc fmt格式化所有成员。仓库中的 examples/multi_contract_calls 就是一个典型的工作区示例根Forc.toml声明memberscallee与caller两个成员包共享同一份Forc.lock。六、插件机制扩展 Forc 能力插件系统允许为forc扩展超越内置命令的新命令。Fuel 生态已提供若干常用插件forc-fmt、forc-client、forc-lsp、forc-migrate等任何人都可以编写自己的插件。6.1 插件如何被调用当 forc 收到未知子命令时会查找名为forc-unknown-subcommand的可执行文件并执行forc-unknown-subcommand args这一逻辑实现在 forc/src/cli/mod.rs 的Plugin(VecString)分支与 forc/src/cli/plugin.rs 中。查看已安装插件$ forc plugins Installed Plugins: forc-install6.2 编写自己的插件插件必须命名为forc-MY_PLUGIN格式可基于模板起步。一个插件 crate 还可以通过在其 manifest 中声明多个[[bin]]目标来提供多个命令——例如forc-client插件同时提供forc deploy和forc run两个命令。插件可以用 clap 增加子命令、选项与配置以满足自身需求。提示编写插件时如果想在Forc.toml中存放工具配置请使用[project.metadata]段见 3.1 节并遵循“键名清晰、文档化、不依赖强制存在、避免键冲突”等最佳实践。七、小结从命令到源码的完整链路回顾整条工具链你可以用一张“心智地图”串起来脚手架forc new/forc init生成Forc.tomlsrc/main.sw配置Forc.toml的[project]、[dependencies]、[build-profile.*]、[patch]、[contract-dependencies]描述包的元信息与构建方式依赖forc add/forc remove/forc update管理四种来源git / ipfs / path / registry的依赖构建forc build通过 forc/src/ops/forc_build.rs 组装BuildOpts交给forc-pkg完成包解析与编译产出.bin、ABI JSON 等产物验证forc check做语义检查forc test运行测试自动启用include_tests部署与交互forc deploy、forc run、forc contract-id、forc predicate-root等命令进入链上环节扩展插件机制forc-name让社区工具无缝融入统一 CLI。如果想要更系统的按命令逐个深入可继续阅读 commands 章节索引 下对应的命令文档如 forc build想动手练习可以浏览仓库 examples 目录下的真实示例工程并参考 Sway 程序类型 中关于大库入口点选择的建议以及 实验特性 了解experimental字段的作用范围。【免费下载链接】sway Empowering everyone to build reliable and efficient smart contracts.项目地址: https://gitcode.com/GitHub_Trending/sw/sway创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考