本文档将引导您了解 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>] [<command>] [<args>]
Fuchsia's developer tool
Options:
-c, --config override default configuration
-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：指示设备上是否有可访问的 Remote Control Service (RCS) 实例在运行。
如果连接了多个设备，您必须按照与多部设备互动中的步骤指定要与哪个目标设备互动。
在大多数情况下，如果您只与目标进行互动，就应该足以建立连接。例如：
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 命令将失败，因为无法确定要使用哪个设备。
设置默认目标
如需设置默认目标，请运行以下命令：
fx set-device $NODENAME您可以运行以下命令来验证是否已正确设置默认目标：
ffx target default get目标列表命令会在默认目标的名称旁边显示一个星号 (*)。如需查看目标列表，请执行以下操作：
ffx target list明确指定目标
如需指定在一次性情况下（例如刷写）要使用的目标，您可以向 ffx 命令指定 -t 或 --target 标志，例如：
# These 2 commands are equivalent.
ffx --target $NODENAME target flash
ffx -t $NODENAME target flash对于 fx 命令，标志的名称为 -d，而不是 -t|--target。例如：
fx -d $NODENAME serve控制目标设备的状态
您可以分别使用 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 命令的文档。
与组件交互
标识名
许多使用组件的 ffx 命令都将标识名作为参数。如需详细了解标识符及其语法，请参阅组件标识符文档。
查找组件
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 命令搜索使用/公开具有给定名称的 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 允许对网址、标识名和组件实例 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
验证 capability 路由
您可以使用 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 创建并启动具有标识符 /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。