Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

ffx 使用入门

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

与 ffx 团队联系

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

前提条件

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

如需启动已启用网络但不支持图形界面 (GUI) 的模拟器，请运行 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
  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 接受命令行中的目标，则可以将其指定为： - 目标节点名称。 - 目标的 IP 地址（ffx target list 中提及的任何地址）。 - 目标序列号。

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

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

为端口指定 0 将专门与未指定端口的主机匹配。

设置默认目标

如需设置默认目标，请运行：

fx set-device $NODENAME

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

ffx target default get

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

ffx target list

明确指定目标

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

# 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（通过指定 stdout 或 -），也可以是 stderr（通过指定 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

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

配置

请参阅配置命令的文档。

与组件交互

Moniker

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

查找组件

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

$ 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 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

### Exploring a component

You can use the `component explore` command to interactively explore the namespace of a component.
This allows you to see exactly what capabilities are available to the component at runtime.

```posix-terminal
ffx component explore /core/network/dhcpd

在 Shell 中，您可以使用 ls 浏览 /svc 目录（和其他命名空间条目）来验证预期功能是否可用。

验证功能路由

您可以使用 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 组件的示例。首先，您需要在您的宇宙中包含 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 创建并启动组件实例，其 moniker 为 /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 与目标设备通信时遇到问题，请运行 ffx doctor 命令来诊断并尝试解决这些问题：

ffx doctor

如果您提交的 bug 涉及目标设备，我们通常会要求您提供 ffx doctor 的输出，以提供有关问题所在位置的信息。

ffx doctor 命令会检查主机环境配置。如果成功，它会尝试通过 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

如果 ffx doctor 失败，它会尝试提供问题的解决方案。如果您持续遇到问题，可以为 ffx 团队提交 bug 。例如，如果 ffx 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。