此页面由 Cloud Translation API 翻译。

ffx 使用入门

本文档将引导您了解 ffx 的一些功能。如需简要了解 ffx 的设计和组件，请参阅 ffx 概览。

与 FFX 团队联系

如果您发现可能存在的 bug，或者有任何问题或建议，请提交 bug。

前提条件

如需按照本文档中的示例进行操作，您需要运行 Fuchsia 设备。如果您没有连接实体设备，可以使用模拟器。

如需启动已启用网络但不支持图形用户界面的模拟器，请运行 ffx emu start --headless。

如需详细了解如何配置模拟器，请参阅启动 Fuchsia 模拟器。

您的设备必须运行 core 产品配置或扩展 core 的产品配置（例如 workstation_eng）。

您可以选择运行 ffx log，该命令将提供有关 ffx 与 Fuchsia 目标设备之间互动的一些额外信息。

简介

满足所有前提条件后，在终端中运行以下命令：

ffx help

此命令将列出所有可用的 ffx 子命令。您会看到类似如下内容：

Usage: ffx [-c <config>] [-e <env>] [-t <target>] [-d] [<command>] [<args>]

Fuchsia's developer tool

Options:
  -c, --config      override default configuration
  -d, --direct      make a direct connection to the target
  -e, --env         override default environment settings
  -t, --target      apply operations across single or multiple targets
  -o, --log-output  specify destination of log output
  --help            display usage information

Commands:
  component         Discover and manage components
  config            View and switch default and user configurations
  daemon            Interact with/control the ffx daemon
  diagnostic        Run diagnostic tests on Fuchsia targets
  docs              View suite of docs for ffx and for Fuchsia
  doctor            Run common checks for the ffx tool and host environment
  emulator          Start and manage Fuchsia emulators
  overnet           Interact with the Overnet mesh
  package           Create and publish Fuchsia packages
  sdk               Modify or query the installed SDKs
  target            Interact with a target device or emulator
  version           Print out ffx tool and daemon versions

您可以使用 ffx help <subcommand> 或 ffx <subcommand> --help 详细了解任何子命令。

与目标设备互动

在终端中，运行以下命令：

ffx target list

您会看到 ffx 发现的设备列表。例如，在单个模拟器运行的情况下，输出如下所示：

NAME                    SERIAL       TYPE       STATE      ADDRS/IP                       RCS
fuchsia-emulator  <unknown>    Unknown    Product    [fe80::5054:ff:fe63:5e7a%4]    N

RCS：指示我们是否已连接到设备上的远程控制服务。此连接对于所有其他 ffx 操作至关重要，但它是延迟建立的，因此当我们尚未与设备互动时，在此处看到 N 并不奇怪。

如果连接了多个设备，您必须按照与多个设备互动中的步骤指定要互动的目标设备。

在大多数情况下，只需与目标互动即可开始连接。例如：

ffx target echo

然后，下次列出目标时，您应该会看到 RCS 连接处于有效状态。

$ ffx target list
NAME                    SERIAL       TYPE       STATE      ADDRS/IP                       RCS
fuchsia-emulator  <unknown>    Unknown    Product    [fe80::5054:ff:fe63:5e7a%4]    Y

如果您之前运行过 ffx log，还应该在日志中看到类似以下所示的内容：

[00009.776170][28540][28542][remote-control, remote_control_bin] INFO: published remote control service to overnet

与多部设备互动

如果 ffx target list 中显示多个目标，您必须指定要使用的目标。如果无法明确确定 ffx 命令应在哪个设备上运行，大多数 ffx 命令都会失败。

指定目标的最简单方法是使用默认目标。

引用目标

无论是设置默认目标，还是为单个命令明确指定目标，您都需要某种方式在命令行中引用目标。

如果 ffx 接受命令行中的目标，则可以指定为： - 目标节点名称。 - 目标设备的 IP 地址（ffx target list 中提及的任何地址）。 - 目标设备的序列号。

IPv6 和 IPv4 地址均可接受。如果查询的地址是 IPv6 地址且包含端口号，则该地址（以及范围 ID，如果有）必须用方括号括起来。范围和端口号均为可选，但可以存在。

如果指定了端口号，则只会与具有相同端口号的目标匹配（目标上未设置端口时，会被视为默认 SSH 端口 22）。

如果为端口指定 0，则只会匹配未指定端口的主机。

设置默认目标平台

如需设置默认目标，请运行以下命令：

fx set-device $NODENAME

您可以运行以下命令来验证默认目标是否已正确设置：

ffx target default get

目标列表命令会在默认目标名称旁边显示星号 (*)。如需查看目标列表，请执行以下操作：

ffx target list

明确指定目标

如需指定在一次性使用场景（例如刷写）中使用哪个目标，您可以为 ffx 和 fx 命令指定 -t 或 --target 标志，例如：

# These commands will all use the same target.
fx -t $NODENAME serve
fx --target $NODENAME serve
ffx -t $NODENAME repository server start
ffx --target $NODENAME repository server start

建立直接连接

ffx 的正常行为是建立由 ffx daemon 调解的与目标的间接连接。不过，由于该守护程序的复杂性和有状态性，不过，您也可以通过传递 -d/--direct 标志（例如）来建立连接，而无需通过守护程序。

ffx -d target echo

如需更改所有 ffx 调用的默认行为，您可以将 connectivity.direct 配置选项设置为 true：

ffx config set connectivity.direct true

缓解连接延迟

与基于守护程序的连接相比，直接连接可提高可预测性和可靠性，但也会带来一些延迟。接下来两个部分将介绍如何消除这两种延迟。同时启用这两种缓解措施后，目标连接的速度与使用守护程序时一样快。

缓存发现的目标

使用直接连接时，ffx 调用必须先通过查找所需目标的地址（或者，如果未指定目标，则通过发现所有可访问的目标）来确定如何连接到所需目标。使用守护程序时，发现结果由守护程序存储。但如果直接建立连接，每个命令可能都需要执行（相对）缓慢的发现过程，这可能需要一秒或更长时间。

为消除此延迟，您可以运行 ffx target discover，该命令将启动一个后台进程来发现可用的目标，并在连接到目标时使这些目标可用。此发现缓存默认每 60 秒刷新一次，但如果您想更快地刷新它（例如，因为您刚刚断开目标连接），只需再次运行 ffx target discover 即可立即更新缓存。

如需了解详情，请参阅 ffx target discover help。

加快 `ssh` 连接速度

通过网络（即通过 ssh）连接到目标时，直接连接可能会导致额外的延迟。此连接可能会在每次调用 ffx 时增加明显的延迟。为了缓解此延迟，您可以通过设置以下配置选项来使用 ssh 的 ControlMaster 功能：

ffx config set ssh.controlmaster.mode managed

这会导致 ffx 在与目标建立通信时使用共享的 ssh 连接。之后，对目标的初始 ffx 调用将设置 ssh 通道，而未来的 ffx 连接将重用同一通道。如需了解详情，请参阅 man 5 ssh_config 中的 ControlMaster 文档。

控制目标设备的状态

您可以使用 target off 和 target reboot 子命令来关闭设备或重启设备。

`ffx` 日志

目的地

日志通常会进入缓存目录（在 Linux 上，通常为 $HOME/.local/share/Fuchsia/ffx/cache/logs）。您可以通过运行以下命令找到该位置

ffx config get log.dir

不过，您可以使用 -o/--log-output <destination> 替换该位置，其中 <destination> 可以是文件名、标准输出（通过指定 stdout 或 -）或标准错误（通过指定 stderr）。

记录级别

可以使用 -l/--log-level <level> 指定调试级别，其中 <level> 是 off、error、warn、info、debug 或 trace 之一。默认值为 info。

也可以通过配置 log.level 永久设置，例如：

ffx config set log.level debug

互动式使用

上述选项的常见用途是查看特定命令的调试信息：

ffx -l debug -o - target echo

上述命令将在命令行上生成调试日志，作为调用的一部分。

目标级别

通过在 log.target_levels 下指定配置条目，可以为特定日志“目标”设置不同的级别。例如，如需仅查看 analytics 的调试日志，请执行以下操作：

ffx config set log.target_levels.analytics debug

日志“目标”只是日志行的前缀。

配置

请参阅 config 命令的文档。

与组件互动

Monikers

许多使用组件的 ffx 命令都将别名作为参数。如需详细了解 moniker 及其语法，请参阅组件 moniker 文档。

查找组件

component list 命令将输出组件拓扑中当前存在的所有组件的别名。

$ ffx component list
/
/bootstrap
/bootstrap/archivist
/bootstrap/base_resolver
/bootstrap/console
/bootstrap/console-launcher
/bootstrap/cr50_agent
/bootstrap/device_name_provider
/bootstrap/driver_index
/bootstrap/driver_manager
/bootstrap/flashmap
/bootstrap/fshost
/bootstrap/fshost/blobfs
/bootstrap/fshost/blobfs/decompressor
...

您可以使用 component select capability 命令搜索使用/公开具有给定名称的功能的组件。

以下命令将显示使用/公开 diagnostics 功能的所有组件：

$ ffx component capability diagnostics
Exposed:
  /bootstrap/archivist
  /bootstrap/base_resolver
  /bootstrap/driver_manager
  /bootstrap/fshost
  /bootstrap/fshost/blobfs
  /bootstrap/fshost/blobfs/decompressor
  /bootstrap/fshost/minfs
  /bootstrap/pkg-cache
  /bootstrap/power_manager
  ...

检查组件

您可以使用 component show 命令获取有关特定组件的详细信息。

component show 允许对网址、Moniker 和组件实例 ID 进行部分匹配。

以下命令将显示有关 /core/network/dhcpd 组件的信息：

$ ffx component show dhcpd
               Moniker:  /core/network/dhcpd
                   URL:  #meta/dhcpv4_server.cm
           Instance ID:  20b2c7aba6793929c252d4e933b8a1537f7bfe8e208ad228c50a896a18b2c4b5
                  Type:  CML Component
       Component State:  Resolved
 Incoming Capabilities:  /svc/fuchsia.net.name.Lookup
                         /svc/fuchsia.posix.socket.packet.Provider
                         /svc/fuchsia.posix.socket.Provider
                         /svc/fuchsia.stash.SecureStore
                         /svc/fuchsia.logger.LogSink
  Exposed Capabilities:  fuchsia.net.dhcp.Server
           Merkle root:  521109a2059e15acc93bf77cd20546d106dfb625f2d1a1105bb71a5e5ea6b3ca
       Execution State:  Running
          Start reason:  '/core/network/netcfg' requested capability 'fuchsia.net.dhcp.Server'
         Running since:  2022-09-15 16:07:48.469094140 UTC
                Job ID:  28641
            Process ID:  28690
 Outgoing Capabilities:  fuchsia.net.dhcp.Server

验证功能路由

您可以使用 component doctor 命令验证组件公开和使用的所有功能是否已成功路由。

例如：

$ ffx component doctor /bootstrap/archivist
Querying component manager for /bootstrap/archivist
URL: fuchsia-boot:///#meta/archivist.cm
Instance ID: None

      Used Capability                      Error
 [✓]  fuchsia.boot.ReadOnlyLog             N/A
 [✓]  fuchsia.boot.WriteOnlyLog            N/A
 [✓]  fuchsia.component.DetectBinder       N/A
 [✓]  fuchsia.component.KcounterBinder     N/A
 [✓]  fuchsia.component.PersistenceBinder  N/A
 [✓]  fuchsia.component.SamplerBinder      N/A
 [✓]  fuchsia.sys.internal.ComponentEvent  N/A
      Provider
 [✓]  fuchsia.sys.internal.LogConnector    N/A
 [✓]  config-data                          N/A

      Exposed Capability                   Error
 [✓]  fuchsia.diagnostics.ArchiveAccessor  N/A
      feedback
 [✓]  fuchsia.diagnostics.ArchiveAccessor  N/A
      .legacy_metrics
 [✓]  fuchsia.diagnostics.ArchiveAccessor  N/A
      .lowpan
 [✓]  diagnostics                          N/A
 [✓]  fuchsia.diagnostics.ArchiveAccessor  N/A
 [✓]  fuchsia.diagnostics.LogSettings      N/A
 [✓]  fuchsia.logger.Log                   N/A
 [✓]  fuchsia.logger.LogSink               N/A

$ ffx component doctor /core/feedback
Querying component manager for /core/feedback
URL: fuchsia-pkg://fuchsia.com/forensics#meta/feedback.cm
Instance ID: eb345fb7dcaa4260ee0c65bb73ef0ec5341b15a4f603f358d6631c4be6bf7080

      Used Capability                      Error
 [✓]  fuchsia.boot.ReadOnlyLog             N/A
 [✓]  fuchsia.boot.WriteOnlyLog            N/A
 [✓]  fuchsia.diagnostics.FeedbackArchive  N/A
      Accessor
 [✓]  fuchsia.hardware.power.statecontrol  N/A
      .RebootMethodsWatcherRegister
 [✓]  fuchsia.hwinfo.Board                 N/A
 [✓]  fuchsia.hwinfo.Product               N/A
 [✓]  fuchsia.metrics.MetricEventLoggerFa  N/A
      ctory
 [✓]  fuchsia.net.http.Loader              N/A
 [✓]  fuchsia.process.Launcher             N/A
 [✓]  fuchsia.sysinfo.SysInfo              N/A
 [✓]  fuchsia.ui.activity.Provider         N/A
 [✗]  fuchsia.feedback.DeviceIdProvider    `/core/feedback` tried to use `fuchsia.feedback.DeviceIdProvider` from its parent,
                                           but the parent does not offer that capability. Note, use clauses in CML default to
                                           using from parent.
 ...

运行组件

component run 命令可以在给定的隔离集合中创建和启动组件。

以下示例展示了如何在 /core/ffx-laboratory 集合中运行 Rust hello-world 组件。首先，您需要在自己的 universe 中添加 hello-world 软件包：

$ fx set <product>.<board> --with //examples/hello_world/rust:hello-world-rust && fx build
...

然后，使用 component run 命令从网址 fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm 创建并启动具有标示名 /core/ffx-laboratory:hello-world-rust 的组件实例：

$ ffx component run /core/ffx-laboratory:hello-world-rust fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
URL: fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
Moniker: /core/ffx-laboratory:hello-world-rust
Creating component instance...
...
$ ffx component show hello-world-rust
               Moniker: /core/ffx-laboratory:hello-world-rust
                   URL: fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cm
                  Type: v2 dynamic component
       Execution State: Running
                Job ID: 50775
            Process ID: 50819
...

解决连接问题

如果您在使用 ffx 与目标设备通信时遇到问题，可以使用 doctor 命令来诊断并尝试解决这些问题。如果您提交的 bug 涉及目标设备，我们通常会要求您提供 ffx doctor 的输出，以便了解问题所在。

doctor 将尝试与 ffx 精灵通信，并在需要时终止并重新启动该精灵。如果成功，它将尝试通过 SSH 连接到目标设备并启动远程控制服务。

如果您尝试在正常情况下运行 ffx doctor，则应看到：

$ ffx doctor

Doctor summary (to see all details, run ffx doctor -v):

[✓] FFX Environment Context
    [✓] Kind of Environment: Fuchsia.git In-Tree Rooted at /usr/local/google/home/username/fuchsia, with default build directory of /usr/local/google/home/username/fuchsia/out/default
    [✓] Environment-default build directory: /usr/local/google/home/username/fuchsia/out/default
    [✓] Config Lock Files
        [✓] /usr/local/google/home/username/global_ffx_config.json locked by /usr/local/google/home/username/global_ffx_config.json.lock
    [✓] SSH Public/Private keys match

[✓] Checking daemon
    [✓] Daemon found: [3338687]
    [✓] Connecting to daemon

[✓] Searching for targets
    [✓] 1 targets found

[✓] Verifying Targets
    [✓] Target: fuchsia-emulator
        [i] Running `ffx target show` against device

[✓] No issues found

如果 doctor 失败，系统会尝试建议问题的解决方案。如果您持续遇到问题，可以向 ffx 团队提交 bug。例如，如果 doctor 无法启动 RCS，您会看到以下内容：

$ ffx doctor -v

Doctor summary:

[✓] FFX doctor
    [✓] Frontend version: 2025-03-25T18:48:31+00:00
    [✓] abi-revision: 0xB5D2EBDA9DA50585
    [✓] api-level: 26
    [i] Path to ffx: /usr/local/google/home/username/fuchsia/out/default/host_x64/ffx

[✓] FFX Environment Context
    [✓] Kind of Environment: Fuchsia.git In-Tree Rooted at /usr/local/google/home/username/fuchsia, with default build directory of /usr/local/google/home/username/fuchsia/out/default
    [✓] Environment File Location: /usr/local/google/home/username/.local/share/Fuchsia/ffx/config/.ffx_env
    [✓] Environment-default build directory: /usr/local/google/home/username/fuchsia/out/default
    [✓] Config Lock Files
        [✓] /usr/local/google/home/username/global_ffx_config.json locked by /usr/local/google/home/username/global_ffx_config.json.lock
    [✓] SSH Public/Private keys match

[✓] Checking daemon
    [✓] Daemon found: [3338687]
    [✓] Connecting to daemon
    [✓] Daemon version: 2025-03-25T18:48:31+00:00
    [✓] path: /usr/local/google/home/username/fuchsia/out/default/host_x64/ffx
    [✓] abi-revision: 0xB5D2EBDA9DA50585
    [✓] api-level: 26
    [✓] Default target: (none)

[✓] Searching for targets
    [✓] 1 targets found

[✗] Verifying Targets
    [✗] Target: fuchsia-emulator
        [✓] Compatibility state: supported
            [✓] Host overnet is running supported revision
        [✓] Opened target handle
        [✗] Timeout while connecting to RCS

[✗] Doctor found issues in one or more categories.

使用 ffx 进行测试

在编写需要与 Fuchsia 环境交互的集成测试时，ffx 命令非常有用。不过，由于 ffx 主要面向开发者，因此它会检查当前环境的配置，并在后台启动一个守护程序来协调与 Fuchsia 设备的通信。这使得编写使用 ffx 的自动化测试变得更加复杂，因为配置和守护程序应隔离，以避免副作用或来自全局环境的干扰。

为了实现这种隔离，测试作者需要在运行使用 ffx 的测试时使用隔离目录。

后续步骤

请与 FFX 团队联系，就本文档提供反馈！
了解如何延长 ffx。