Skip to main content

DFX 常用指令

DFX

命令行工具 dfx 是用于创建、部署和管理互联网计算机 (IC) 平台上的去中心化应用的主要工具，用来管理身份、账本、cycles 钱包、以及容器等。dfx 包含有二十多个子命令，每个子命令又拥有不同的子命令，使得 dfx 的功能非常强大的同时也很庞大。

这篇文章的目的并不是介绍 dfx 所有命令的用法，而是试着从开发者日常开发中着眼，列举出一些常用的 dfx 命令。如果需要查阅 dfx 说明书，请参考 dfx 官方链接。

dfx​

dfx 的基本用法如下：

dfx [subcommand] [flag]

dfx 命令常用的标志、参数有：

  • -h, --help
    用来输出帮助信息
  • -V, --version
    用来输出版本信息
  • --identity <identity>
    用来指定执行命令时所使用的用户身份（适用于本地有多个身份的情况）。具体身份的管理可以参考身份管理章节。

dfx 包含有二十多个子命令，常用的有 canister, deploy, identity, ledger, wallet 等，后面章节会介绍到其中的一部分，具体的所有子命令请参考官方开发文档。

身份 (Identity)​

dfx identity 命令和其子命令可以用来管理用于执行命令和与 IC 或本地容器执行环境通信的身份信息。它的基本用法如下：

dfx identity [subcommand] [flag]

创建身份​

dfx identity new 可以用来创建一个新的用户身份。它的基本用法如下：

dfx identity new [options] <identity-name>

常用的参数和选项有：

  • <identity-name>
    用来指定创建的身份名称。
  • --storage-mode
    这个参数有两个选项：
    • password-protected
      这个是默认的选项，会提醒您为加密的 PEM 文件设置一个密码。
    • plaintext
      有些时候会用到非加密的 PEM 文件，比如在 CI 这种不提供用户交互的情况下。

下面是一个示例：

dfx identity new ic_test --storage-mode plaintext

它创建了一个非加密的名为 ic_test 的身份。

导入身份​

dfx identity import 可以通过导入一个 PEM 文件来创建用户身份，它的基本用法如下：

dfx identity import [options] <identity-name> <pem_file>

它常用的参数和创建身份很相似，不同之处在于：

  • <pem_file> 用来指定需要导入的 PEM 文件。
  • --force 如果指定的 identity-name 已经存在，指定 --force 选项会覆盖原有的身份。

下面是一个示例：

dfx identity import ic_test test.pem --storage-mode plaintext

它导入当前目录下的 test.pem 文件并创建一个非加密的名为 ic_test 的身份。

删除身份​

dfx identity remove 可以用来删除您不再需要的身份。它的基本用法如下：

dfx identity remove [options] <identity-name>

下面是一个示例：

dfx identity remove ic_test

它会删除名为 ic_test 的身份。

需要注意的是：对于加密的身份，在删除的时候并不需要输入身份加密时所设置的密码。

列举身份​

dfx identity list 可以列举出您本机所有的身份，并显示出当前正在使用的身份，基本用法如下：

dfx identity list

以下就是笔者在本机执行该命令所输出的结果：

~$ dfx identity list
anonymous
default
first *
ic123
ic_test

以星号结尾标注的就是当前正在使用的身份。

使用身份​

当您想要使用的身份并不是当前身份的时候，可以通过 dfx identity use 命令来切换身份。基本用法如下：

dfx identity use [flag] <identity-name>

下面是一个示例：

dfx identity use ic_test

它会切换当前用户身份为 ic_test。

获取主体​

dfx identity get-principal 可以用来显示与当前用户身份相关联的主体。

下面是一个示例：

dfx identity get-principal --identity=ic_test

它会返回 ic_test 身份所关联的主体。如果当前身份就是 ic_test，则可以省略 --identity=ic_test。

获取钱包​

dfx identity get-wallet 可以用来显示与当前用户身份相关联的 cycles 钱包。

下面是一个示例：

dfx identity get-wallet --network ic

它会返回 IC 主网上当前身份所关联的 cycles 钱包。

设置钱包​

dfx identity set-wallet 可以用来设置与当前用户身份相关联的 cycles 钱包。

下面是一个示例：

dfx identity set-wallet <canister-id> --network ic

它会在 IC 主网上设置与当前身份相关联的 cycles 钱包。

部署钱包​

dfx identity deploy-wallet 可以通过在一个容器里安装钱包 Wasm 代码来创建 cycles 钱包。基本用法如下：

dfx identity deploy-wallet [flag] <canister_id>

下面是一个示例：

dfx identity deploy-wallet gastn-uqaaa-aaaae-aaafq-cai --network ic

它会在 IC 主网上在指定容器安装钱包 Wasm 代码。

以上就是 dfx identity 命令的基本用法，未列举部分请参考官方文档。

账本 (Ledger)​

dfx ledger 命令及其子命令可以用来与账本容器交互。它可用于从一个容器向另一个容器进行 ICP 转账，或使用 ICP 为容器充值 cycles。

它的基本用法如下：

dfx ledger [subcommand] [flag]

获取账户​

dfx ledger account-id 命令返回与当前身份关联的账户 ID。同身份所关联的主体一样，帐户 ID 是从您的私钥派生、并用于在账本容器中表示您的身份。

下面是一个示例：

dfx ledger account-id

它返回当前身份相关联的账户 ID，类似如下：

03e3d86f29a069c6f2c5c48e01bc084e4ea18ad02b0eec8fccadf4487183c223

获取余额​

dfx ledger balance 命令返回与当前账号的余额。

下面是一个示例：

dfx ledger balance

它返回当前账号的余额，类似如下：

2.49798000 ICP

转账​

您可以使用 dfx ledger transfer 命令将 ICP 从您在账本容器中的帐户转移到目标账户。它的基本用法如下：

dfx ledger transfer [options] <to_account_id> --memo memo

常用的参数和选项有：

  • <to_account_id>
    用来指定您要转账的目标账户。
  • --memo <memo>
    用来指定该交易的数字备忘录。
  • --amount <amount>
    用来指定要转账的 ICP 数量，最多可以指定八位小数的数字。可以理解为 --amount 是 --icp 和 --e8s 的结合。
  • --icp <icp>
    指定 ICP 为整数，可以单独使用或与 --e8s 结合使用。
  • --e8s <e8s>
    指定 e8s 为整数。e8 是 ICP 的最小单位，例如 1.05000000 是 1 个 ICP 和 5000000 个 e8s 的组合。它可以单独使用或与 --icp 结合使用。
  • --fee <fee>
    用来指定该交易的费用，默认是 10000 e8s。

下面是一个示例：

dfx ledger transfer dd81336dbfef5c5870e84b48405c7b229c07ad999fdcacb85b9b9850bd60766f --memo 12345 --icp 1 --network ic

它在 IC 主网上向指定账户发起一笔数量为 1 ICP 的交易。 返回信息类似如下所示：

Transfer sent at BlockHeight: 59513

结束后您可以通过 dfx ledger balance --network ic 命令查询当前账号的余额。

充值 cycles​

您可以使用 dfx ledger top-up 命令使用通过 ICP 铸造而来的 cycles 给容器充值。 它的基本用法如下：

dfx ledger top-up [options] canister_id [flag] --network ic

它常用的参数和转账很相似，比如：--amount, --icp, --e8s, --fee 等。不同之处在于：

  • <canister_id>
    用来指定您要充值的容器 ID。

下面是一个示例：

dfx ledger top-up --icp 1 5a46r-jqaaa-aaaaa-qaadq-cai --network ic

它在 IC 主网上向指定容器充值价值为 1 ICP 的 cycles。如果转账成功会返回类似如下所示信息：

Transfer sent at BlockHeight: 59482
Canister was topped up!

制造 cycles​

您可使用 dfx ledger fabricate-cycles 向指定的容器存入 cycles。这些 cycles 都是虚拟的，并不会从任何地方扣除。

info

请注意，只有在本地开发环境中，才能使用 dfx ledger fabricate-cycles 命令。

它的基本用法如下：

dfx ledger fabricate-cycles [options]

常用的参数和选项有：

  • --all
    用来向 dfx.json 文件中所配置的所有容器充值 cycles。
  • --canister <canister name/id>
    指定要接收 cycles 的容器名称或 ID。您必须指定容器名称或 提供 –all 选项。
  • --amount <amount>
    用来指定要铸造成 cycles 的 ICP 数量，最多可以指定八位小数的数字。可以理解为 --amount 是 --icp 和 --e8s 的结合。
  • --icp <icp>
    指定 ICP 为整数，可以单独使用或与 --e8s 结合使用。
  • --e8s <e8s>
    指定 e8s 为整数。e8 是 ICP 的最小单位，例如 1.05000000 是 1 个 ICP 和 5000000 个 e8s 的组合。它可以单独使用或与 --icp 结合使用。
  • --cycles <cycles>
    用来指定您要制造的 cycles 数量。
  • --t <trillion cycles>
    用来指定您要制造的 cycles 数量，以 T 来计算。

下面是一个示例：

dfx ledger fabricate-cycles --all --cycles 8000000000000

该命令会向工程 dfx.json 文件中所配置的容器全部充值 8T 的 cycles，并输入如下所示的信息：

Fabricating 8000000000000 cycles onto hello_backend
Fabricated 8000000000000 cycles, updated balance: 11_899_662_119_932 cycles
info

dfx ledger fabricate-cycles 另外一个常见的用处是向本地开发环境的钱包充值 cycles。请参考如下示例：

$ dfx identity get-wallet
bnz7o-iuaaa-aaaaa-qaaaa-cai

$ dfx wallet balance
90.699 TC (trillion cycles).

$ dfx ledger fabricate-cycles --canister bnz7o-iuaaa-aaaaa-qaaaa-cai --t 100
Fabricating 100000000000000 cycles onto bnz7o-iuaaa-aaaaa-qaaaa-cai
Fabricated 100000000000000 cycles, updated balance: 190_699_334_378_341 cycles

我们需要执行该命令的原因是，本地环境部署容器也会消耗本地钱包的 cycles。当本地钱包 cycles 余额不足，您会得到如下类似的返回信息：

$ dfx deploy
Deploying all canisters.
Creating canisters...
Creating canister greet_backend...
Error: Failed while trying to deploy canisters.
Caused by: Failed while trying to deploy canisters.
  Failed while trying to register all canisters.
    Failed to create canister 'greet_backend'.
      The replica returned a replica error: Replica Error: reject code CanisterError, reject message Canister bnz7o-iuaaa-aaaaa-qaaaa-cai is out of cycles: requested 3_100_000_000_000 cycles but the available balance is 797_770_504_197 cycles and the freezing threshold 173_237_730 cycles, error code None

此时您就需要调用 dfx ledger fabricate-cycles 来为您的本地钱包充值 cycles，从而继续本地开发。

创建容器​

您可以使用 dfx ledger create-canister 命令来在 IC 上创建容器、并充值价值为指定 ICP 的 cycles。 它的基本用法如下：

dfx ledger create-canister <controller> [options]  [flag] --network ic

它常用的参数和转账很相似，比如：--amount, --icp, --e8s, --fee 等。不同之处在于：

  • <controller>
    用来指定新创建容器的控制者。

  • --subnet-type <subnet-type> 用来指定子网类型。如果没有指定，容器会被创建在随机的默认应用子网上。
    目前支持的类型是 fiduciary，请参考论坛文章获取详细信息。

下面是一个示例：

dfx ledger create-canister tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe --amount 1.25 --network ic

它在 IC 主网上创建一个容器，将指定的主体设置为容器的控制者，并向充值价值为 1.25 ICP 的 cycles。如果创建成功会返回类似如下所示信息：

Transfer sent at BlockHeight: 20
Canister created with id: "53zcu-tiaaa-aaaaa-qaaba-cai"

以上就是 dfx ledger 命令的基本用法，未列举部分请参考官方文档。

钱包 (Wallet)​

容器需要 cycles 来执行操作、并为所使用的资源付费，用户和开发人员通过一种称为 cycles 钱包的特殊容器来管理 cycles 的分配和所有权。

目前 cycles 钱包是一种复杂的解决方案，它本质上是一个容器、自身也会消耗 cycles。如果对应的容器 ID 在迁移过程中遗失，则会丢失 cycles。所以目前 DFINITY 基金会在开发的一个新功能就是 cycles 账本，用来简化 cycles 的管理。Cycles 账本将作为单个全局账本容器来部署，它将符合 ICRC-2 标准，并且还将与 NNS 容器、用户容器交互，以提供账本特定功能，例如可以使用 cycles 创建新容器、向容器发送 cycles 和接受转入的 cycles。更多关于 cycles 账本的信息请参考这里。

因为 cycles 账本预计近期将会推出，这里关于 cycles 钱包我们只做简单介绍。

创建钱包​

常用的创建钱包的方式有两种：一种是通过兑换 cycles 优惠券来自动创建；一种是通过创建容器、并安装钱包的 Wasm 代码。

自动创建​

请参考如何获得免费 cycles 文档。

其中如下的命令行会帮助您创建一个 cycles 钱包。

dfx wallet --network ic redeem-faucet-coupon <your-coupon-code>

您可以通过以下命令来查看您的钱包余额。

dfx wallet balance --network ic

手动创建​

按照以下步骤，您可以手动创建 cycles 钱包：

  • 通过 dfx ledger create-canister 创建一个新的容器，请参考这里；

  • 通过 dfx identity deploy-wallet 在容器里安装钱包 Wasm 代码，请参考这里；

  • 通过 dfx identity get-wallet 来查看跟当前身份关联的 cycles 钱包，请参考这里。

获取余额​

dfx wallet balance 命令返回与当前 cycles 钱包的余额。

下面是一个示例：

dfx wallet balance --network ic

它返回当前 cycles 钱包的余额，类似如下：

15.292 TC (trillion cycles)

转账​

您可以通过 dfx wallet send 将 cycles 从 cycles 钱包发送到另一个容器。它的基本用法如下：

dfx wallet send [flag] <destination> <amount> --network <network>

常用的参数和选项有：

  • <destination>
    用来指定您要转账的容器 ID。
  • --amount <amount>
    用来指定要转账的 cycles 数量。

下面是一个示例：

dfx wallet send r7inp-6aaaa-aaaaa-aaabq-cai 2000000000

它将会从跟当前身份相关联的 cycles 钱包发送 2000000000 个 cycles 到指定的容器。

以上就是 dfx wallet 命令的基本用法，未列举部分请参考官方文档。

容器 (Canister)​

您可以使用 dfx canister 命令来和 IC 或者本地的容器执行环境交互。大多数情况，你可以通过 dfx canister 命令来管理容器的生命周期、执行一些任务（比如调用容器方法）。

它的基本用法如下：

dfx canister <subcommand> [flags]

创建​

dfx canister create 可以用来创建一个新的容器。它的基本用法如下：

dfx canister create [option] [flag] [--all | canister_name]

常用的参数和选项有：

  • --controller <principal>
    用来指定新创建的容器的控制者。
  • -with-cycles <number-of-cycles>
    用来指定要充值的 cycles 数量，该数量会从 cycles 钱包里面扣除。
  • --specified-id <principal>
    用来指定所创建的容器的 ID。
  • <canister_name>
    用来指定所创建的容器名字，该容器名字必须在项目的 dfx.json 文件中已经存在。
  • --all
    如果没有指定所创建的容器名字，而是提供了 --all 参数，则会创建所有在 dfx.json 中已经配置的容器。

这里并未一一列举 dfx canister create 所有的参数，如需了解请参考官方文档。

下面是一个示例：

dfx canister create --with-cycles 8000000000000 --all

该命令会创建所有 dfx.json 中配置的容器，并指定初始 cylces 数量为 8000000000000。

与 dfx ledger create-canister 通过 ICP 来创建容器不同，虽然两者都能创建容器，但 dfx canister create 通过 cycles 钱包转入 cycles，并且提供了更精细的控制，比如可以指定 memory、compute 分配的大小。

删除​

dfx canister delete 可以用来删除容器，并将剩余的 cycles 转出到您的 cycles 钱包。它的基本用法如下：

dfx canister delete [flag] [--all | canister_name]

常用的参数和选项有：

  • <canister_name>
    用来指定所创建的容器名字或 ID。
  • --all
    如果没有指定所创建的容器名字，而是提供了 --all 参数，则会创建所有在 dfx.json 中已经配置的容器。

需要注意的是，dfx canister delete 必须要在一个 dfx 工程的目录下运行。

如果您已经没有本地工程环境，可以尝试以下示例从 IC 主网删除一个容器：

  1. 执行 mkdir dfx_deleting 创建 dfx_deleting 目录；
  2. 执行 cd dfx_deleting 进入该目录；
  3. 执行 echo '{}' > dfx.json 生成一个空的 dfx.json 文件；
  4. 执行 dfx canister delete <canister_id> --network ic 通过容器 ID 来删除给定的容器。

您可以在运行该示例前、后调用 dfx wallet balance --network ic 来查看 cycles 余额变化。

充值 cycles​

dfx canister deposit-cycles 命令可以用来从 cycles 钱包给指定容器充值 cycles。它的基本用法如下：

dfx canister deposit-cycles [amount of cycles] [--all | canister_name]

常用的参数和选项有：

  • <canister_name>
    用来指定所需充值的容器名字或 ID。
  • --all
    如果没有指定所需充值的容器名字，而是提供了 --all 参数，则会充值所有在 dfx.json 中已经配置的容器。

下面是一个示例：

dfx canister deposit-cycles 2000000000000 --all

该命令会给所有 dfx.json 中配置的容器充值数量为 2000000000000 的 cylces。

查看容器 ID​

dfx canister id 命令可以用来查看指定容器的 ID。它的基本用法如下：

dfx canister id <canister-name>

下面是一个示例：

dfx canister id hello_world --network ic

查看容器信息​

dfx canister info 命令可以用来查看指定容器的信息。它的基本用法如下：

dfx canister info <canister-id>

下面是一个示例：

dfx canister info rrkah-fqaaa-aaaaa-aaaaq-cai --network ic

该命令会输出 nns governance 容器的相关信息如下：

Controllers: r7inp-6aaaa-aaaaa-aaabq-cai
Module hash: 0x3eadce8399b6bc9450bfb8bb54adefc1e27b2564146684d4c6d41a62c4110b73

查看容器日志​

dfx canister logs 命令可以显示容器的日志。它的基本用法如下：

dfx canister logs <canister-name>

下面是一个示例，显示来自 hello_world 容器的日志。

dfx canister logs hello_world

该命令将显示类似于以下内容的输出：

[0. 2024-06-04T21:14:25.882276Z]: Some text message
[1. 2024-06-04T21:18:18.094003Z]: (bytes) 0xc0ffee

容器快照​

当容器因未按预期工作、陷入陷阱等原因需要回滚到之前的版本，开发人员可以使用容器快照。一个容器包含编译后的 Wasm 代码和数据（例如容器 ID、配置和 Wasm 内存等），开发人员可以对已停止的容器进行快照，以保存当前的稳定内存、堆内存、数据和 Wasm 模块等信息。该快照可以在后期进行加载、以将容器回滚到快照中所保存的状态。

创建快照​

dfx canister snapshot create 命令可以用来为已停止状态的容器创建快照。它的基本用法如下：

dfx canister snapshot create <canister> [--replace <replace>]

常用的参数和选项有：

  • <canister>
    用来指定容器名字或 ID。
  • --replace <replace>
    如果提供了快照 ID，当前快照将替换它并重用该 ID。

以下是一个示例：

dfx canister stop hello
dfx canister snapshot create hello
dfx canister start hello

加载快照​

dfx canister snapshot load 命令可以用来加载之前通过 dfx canister snapshot create 命令创建的容器快照。它的基本用法如下：

dfx canister snapshot load <canister> <snapshot>

常用的参数和选项有：

  • <canister>
    用来指定容器名字或 ID。
  • <snapshot>
    用来指定需要加载的快照 ID。

以下是一个示例：

dfx canister stop hello
dfx canister snapshot load hello 1a2b3c4d
dfx canister start hello

删除快照​

dfx canister snapshot delete 命令可以用来删除之前通过 dfx canister snapshot create 命令创建的容器快照。它的基本用法如下：

dfx canister snapshot delete <canister> <snapshot>

常用的参数和选项有：

  • <canister>
    用来指定容器名字或 ID。
  • <snapshot>
    用来指定需要加载的快照 ID。

以下是一个示例：

dfx canister snapshot load hello 1a2b3c4d

列举快照​

dfx canister snapshot list 命令可以用来列举之前通过 dfx canister snapshot create 命令创建的容器快照。它的基本用法如下：

dfx canister snapshot list <canister>

常用的参数和选项有：

  • <canister>
    用来指定容器名字或 ID。

以下是一个示例：

dfx canister snapshot list hello

安装容器代码​

dfx canister install 命令可以用来安装容器代码。它的基本用法如下：

dfx canister install [flag] [option] [--all | canister_name]

常用的参数和选项有：

  • <canister_name>
    用来指定所需安装代码的容器名字或 ID。
  • --all
    如果没有指定所需安装代码的容器名字，而是提供了 --all 参数，则会安装所有在 dfx.json 中已经配置的容器。
  • --wasm <file.wasm>
    用来指定所需安装的 Wasm 代码文件。如果这里指定了，dfx.json 中配置的则会被忽略。

这里并未一一列举 dfx canister install 所有的参数，如需了解请参考官方文档。

更新容器设置​

dfx canister update-settings 命令可以用来更改容器设置。它的基本用法如下：

dfx canister update-settings [flags] [options] [canister_name | --all]

常用的参数和选项有：

  • <canister_name>
    用来指定所需更新的容器名字或 ID。
  • --all
    如果没有指定所需更新的容器名字，而是提供了 --all 参数，则会更新所有在 dfx.json 中已经配置的容器。
  • --add-controller <principal> 给指定容器添加控制者。
  • --remove-controller <principal> 删除指定容器的控制者。

这里并未一一列举 dfx canister update-settings 所有的参数，如需了解请参考官方文档。

下面是一个示例：

dfx canister update-settings --add-controller <principal-id> <canister-id> --network=ic

该命令会给指定的容器添加一个新的控制者。

调用容器方法​

dfx canister call 命令可以调用容器上的方法。它的基本用法如下：

dfx canister call [option] <canister_name> <method_name> [argument] [flag]

常用的参数和选项有：

  • canister_name
    用来指定所调用的容器名字或 ID。
  • method_name
    用来指定所调用的方法名字。
  • argument 给指定所调用方法的参数。

下面是一个示例：

dfx canister call qvhir-riaaa-aaaan-qekqa-cai greet --network ic

该命令会给调用 qvhir-riaaa-aaaan-qekqa-cai greet 容器上的 greet 方法。

这里并未一一列举 dfx canister call 所有的参数，如需了解请参考官方文档。

以上就是 dfx canister 命令的基本用法，未列举部分请参考官方文档。

开发相关命令​

启动​

您可以使用 dfx start 命令启动本地容器执行环境和 Web 服务器进程。这样您可以通过 dfx deploy 命令将容器代码部署到本地容器执行环境，进而在开发过程中测试您的 dapp。

默认情况下，所有本地 dfx 工程都将共同使用一个本地容器执行环境，您可以从任何目录运行 dfx start 和 dfx stop。

该命令的基本用法如下：

dfx start [option] [flag]

该命令的参数和选项较多，常用的如下：

  • --background
    在后台启动本地容器执行环境和 Web 服务器进程，并等待回复后才返回到命令行。
  • --clean
    在启动本地容器执行环境和 Web 服务器进程时，清除项目缓存中的检查点。您可以使用此选项将项目缓存设置为新状态，进行调试或者故障排除。
  • --host <host>
    指定主机接口 IP 地址和端口号以绑定前端。

下面是一个示例：

dfx start

该命令会在当前命令行中启动本地容器执行环境和 Web 服务器进程，您需要打开一个新的命令行来运行其他命令。

您可以使用以下命令来在后台运行一个本地容器执行环境：

dfx start --background

停止​

您可以使用 dfx stop 命令停止当前在计算机上运行的本地容器执行环境。为了模拟与 IC 的连接，本地容器执行环境会在启动它们的终端中或后台持续运行，所以需要手动停止。

该命令的基本用法如下：

dfx stop [flag]

该命令的用法比较简单，除了通用的一些参数，并没有提供特定的参数。运行以下命令就会停止您的本地容器执行环境。

dfx stop

创建​

您可以使用 dfx new 命令创建一个新的 IC 工程。该命令会创建一个默认的项目结构，其中包含了一个 dapp 的模板，您可以用来作为基础进而修改成为您所需要的 dapp。它的基本用法如下：

dfx new <project_name> [flag]

常用的参数和选项有：

  • project_name
    用来指定所创建的工程名称。
  • --type 用来指定所创建工程的类型，可以选择 rust 或 motoko。默认值为 motoko。
  • --no-frontend
    用来跳过安装前端模板代码，创建仅包括一个 .txt 文件的 Asset 容器。如果没有指定该选项，并检测到您的计算机上未安装 node.js，则会以 --no-frontend 为默认行为执行。
  • --frontend
    用来安装前端模板代码。如果没有指定该选项，并检测到您的计算机上已安装 node.js，则会以 --frontend 为默认行为执行。如果您的计算机上当前未安装 node.js，而您指定了 --frontend 选项，则会在创建项目时尝试安装 node.js。

下面是一个示例：

dfx new my_test_project

该命令将创建一个名为 my_test_project 的新工程，该工程包括默认项目目录结构和项目的 Git 存储仓库。

您可以用带有 --dry-run 的命令来预览将要创建的文件。

dfx new my_test_project --dry-run

构建​

您可以使用 dfx build 命令将程序编译为可在 IC 上部署的 WebAssembly 模块。该命令会编译工程的 dfx.json 配置文件中所定义的程序，并使用该配置文件中 canisters 部分所配置的信息查找要编译的源代码。

请注意，您只能在工程目录下运行此命令。例如，如果您的项目名称是 hello_world，则您的当前工作目录必须是 hello_world 目录或其任一子目录。

该命令的基本用法如下：

dfx build [flag] [option] [--all | canister_name]

常用的参数和选项有：

  • --network <network>
    指定您要连接的网络别名或 URL。您可以使用此选项覆盖 dfx.json 配置文件中指定的网络。
  • --all
    构建项目 dfx.json 文件中配置的所有容器，它是 dfx build 的默认选项。
  • canister_name
    指定您需要构建的容器名称。如果您仅仅想构建某一个容器，请在不使用 --all 选项的同时提供一个容器名称作为参数。请注意，该容器名称必须与 dfx.json 的 canisters 部分中的某一个容器名称匹配。

下面是一个 dfx.json 的示例。

{
    "canisters": {
        "hello_world: {
            "main": "src/hello_world/main.mo",
            "type": "motoko"
        },
        "hello_world_assets": {
            "dependencies": [
                "hello_world"
            ],
            "frontend": {
                "entrypoint": "src/hello_world_assets/public/index.js"
            },
            "source": [
                "src/hello_world_assets/assets",
                "dist/hello_world_assets/"
            ],
            "type": "assets"
        }
    },
    "defaults": {
        "build": {
            "packtool": ""
        }
    },
    "version": 1
}

执行以下命令会构建 hello_world 和 hello_world_assets 这两个容器。

dfx build

如果您只想构建后端容器 hello_world ，可以运行如下命令：

dfx build hello_world

部署​

您可以使用 dfx deploy 命令注册、构建和部署 dapp。通过提供不同的参数，您可以在本地容器执行环境、IC 主网 或指定的测试网络上执行该命令。默认情况下，该命令将部署工程 dfx.json 配置文件中定义的所有容器。

该命令等价于以下命令集，使得您能够运行一个命令来简化开发流程：

dfx canister create --all
dfx build
dfx canister install --all

同 dfx build 一样，您只能在工程目录下运行此命令。

该命令的基本用法如下：

dfx deploy [flag] [option] [canister_name]

常用的参数和选项有：

  • --network <network>
    指定您要连接的网络别名或 URL。默认使用本地容器执行环境。
  • --ic
    --network ic 的别名。
  • --argument <argument>
    指定使用 Candid 语法在部署期间向容器传递参数。
  • --with-cycles <number-of-cycles>
    可以指定工程中容器的初始 cycles 数量。
  • canister_name
    指定您需要部署的容器名称。请注意，该容器名称必须与 dfx.json 的 canisters 部分中的某一个容器名称匹配。

下面是一个示例：

dfx deploy --with-cycles 8000000000000 --network ic

该命令会将 dfx.json 中所定义的容器部署到 IC 主网，每个容器都包含初始 8000000000000 cycles 数量。

依赖​

您可以使用 dfx deps 命令从 IC 主网获取所依赖的容器、并在本地部署。您只能在工程目录下运行此命令。

该命令的基本用法如下：

dfx deps [subcommand] [options]

该命令有三个子命令：

  1. pull: 拉取项目所依赖的容器；
  2. init：为依赖容器设置初始化参数；
  3. deploy：部署依赖容器。

分别介绍如下。

拉取​

您可以使用 dfx deps pull 子命令来拉取在 dfx.json 中定义的依赖容器，该命令会自动拉取所有的间接依赖。

该命令的基本用法如下：

dfx deps pull [options]

常用的参数和选项有：

  • --network <network>
    指定您要连接的网络别名，默认使用 IC 主网。

下面是一个示例：

dfx deps pull

当执行成功后，您可以到项目的 deps/pulled.json 文件查看具体依赖信息。

初始化​

您可以使用 dfx deps init 命令为依赖容器设置初始化参数。

该命令的基本用法如下：

dfx deps init [options] [canister]

当执行成功后，您可以到项目的 deps/init.json 文件查看具体初始化信息。

默认情况下，该命令会从 deps/pulled.json 读取 init_arg 参数并保存至 deps/init.json 文件。

如果有任何依赖容器缺少初始化参数，上述命令会提示它们的 canister ID。然后，您可以指定 canister ID 单个依赖容器设置初始化参数。

dfx deps init <CANISTER> --argument <ARGUMENT> [--argument-type <TYPE>]

以下是一些示例。

  1. 下面的命令将数字 1 作为容器 dep_a 的初始化参数，参数类型是默认的 Candid 类型。

    dfx deps init dep_a --argument 1

  2. 下面的命令将十六进制编码的原始字节作为容器 dep_b 的初始化参数。

    dfx deps init dep_b --argument "4449444c00017103616263" --argument-type raw

  3. 下面的命令将文件 init_c.txt 的内容作为容器 dep_c 的初始化参数。

    dfx deps init dep_c --argument-file init_c.txt
info

请注意，即使您依赖的容器不需要初始化参数，您仍需要执行 dfx deps init 以生成 deps/init.json 文件。dfx deps deploy 命令会检查该文件。

部署​

您可以使用 dfx deps deploy 命令为部署所有依赖容器。

该命令的基本用法如下：

dfx deps deploy [options] [canister]

下面是一个示例：

dfx deps deploy

该命令会在本地副本上部署所有依赖容器，如果某些依赖容器尚未被拉取、或未设置初始化参数，该命令将失败。您可以根据错误信息来进行修复。

其他​

帮助​

您可以使用 dfx help 命令来查看 dfx 及其子命令的使用方法。它的基本用法如下：

dfx help [subcommand]

常用的参数有：

  • subcommand
    用来指定您想要查看的子命令。

下面是一个示例，用来查看 dfx 命令的用法。

dfx help

而下面的命令则可以查看子命令 new 的具体用法。

dfx help new

升级​

您可以使用 dfx upgrade 命令升级在本地计算机上运行的 SDK 组件。此命令会检查您当前安装的 SDK 版本与 manifest.json 文件中指定的最新公开版本之间的差异。如果在本地检测到旧版本的 SDK，则 dfx upgrade 命令会自动从 CDN 获取最新版本。

它的基本用法如下：

dfx upgrade [flag] [option]

常用的参数有：

  • --current-version <version>
    用来指定当前版本。如果设置了该选项，您指定的版本将会作为本地当前版本与 manifest.json 文件中的最新版本进行比较。

下面是一个示例，用来更新您的 SDK 版本。

dfx upgrade

ping​

使用 dfx ping 命令可以检查与 IC 主网或测试网络的连接。

请注意：

  • 如果要测试与本地服务器的连接，您只能从工程目录下运行此命令。
  • 如果您要测试与 IC 主网的连接，您可以从任何目录运行 dfx ping ic 命令。

它的基本用法如下：

dfx ping [provider] [flag]

常用的参数有：

  • provider
    用来指定需要测试的网络。

下面是一个示例，用来测试与 IC 主网的连接。

dfx ping ic

总结​

除了本文列举的关于身份、账本、cycles 钱包、容器以及开发相关的命令，dfx 命令还有更多的子命令，目前就不在一一列举，后续如果有需要可以根据大家反馈继续增加，也欢迎大家参与贡献。

有问题么？​

欢迎大家随时向我们提出任何技术问题。我们会尽力尽快回应。

  1. 上网比较方便的，在 ICP China 的 Twitter Community，用中文发帖提问

    info

    https://twitter.com/i/communities/1679302895571988481

  2. 有经验的开发者在 DFINITY 基金会运营的开发者论坛上用英文提问

    info

    https://forum.dfinity.org/ ，可以 cue 我们：Ben，Paul，Vincent ，Herbert。

  3. 深度 ICP 用户可以在 OpenChat 上的 IC123.xyz Community 里的频道 ic123.xyz 工作组 里提问题

    info

    https://oc.app/community/gb3c3-hiaaa-aaaar-a35sa-cai/channel/316363584640902102086769779217159683798/?ref=inda5-hyaaa-aaaaf-aaioq-cai

    欢迎您申请 DFINITY 基金会的 Developer Grant 项目，加入互联网计算机的大家庭！