本文件將引導您逐步瞭解 ffx 的部分功能。如要概略瞭解 ffx 的設計和元件，請參閱 ffx 總覽。
與 ffx 團隊聯絡
如果發現可能的錯誤，或有任何問題或建議，請回報錯誤。
必要條件
如要按照本文件中的範例操作，您需要執行 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明確指定目標
如要指定在一次性情況 (例如閃爍) 中要使用的目標，您可以將 -t 或 --target 標記指定給 ffx 指令，例如：
# 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 (透過指定 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記錄「目標」只是記錄列的前置字串。
設定
請參閱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 指令搜尋使用/公開特定名稱能力的元件。
下列指令會顯示所有使用/公開 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
驗證能力路徑
您可以使用 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 指令進行診斷，並嘗試解決問題。如果您回報的錯誤涉及目標裝置，我們通常會要求您提供 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 團隊回報錯誤。舉例來說，如果 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 進行測試
ffx 指令在編寫需要與 Fuchsia 環境互動的整合測試時非常實用。不過，由於 ffx 主要設計給開發人員使用，因此會檢查目前環境的設定，並在背景啟動 Daemon，以協調與 Fuchsia 裝置的通訊。因此，您必須隔離設定和守護程式，才能避免副作用或來自全域環境的干擾，這會使編寫使用 ffx 的自動化測試更加複雜。
為達到這種隔離效果，測試作者在執行使用 ffx 的測試時，需要使用隔離目錄。
後續步驟
- 如對這份文件有任何意見，請與 ffx 團隊聯絡！
- 瞭解如何擴充
ffx。