開始使用 ffx

這份文件將引導你瞭解 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>] [-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 接受指令列上的目標，可指定為： - 目標節點名稱。 - 目標的 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 呼叫必須先找出所需目標的位址，判斷如何連線至該目標 (如果未指定目標，則找出所有可存取的目標)。使用 Daemon 時，探索結果會由 Daemon 儲存。但如果直接建立連線，每個指令可能都需要執行 (相對) 緩慢的探索程序，這可能需要一秒以上。

如要消除這項延遲，可以執行 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 連線會重複使用相同管道。詳情請參閱ControlMaster說明文件man 5 ssh_config。

控制目標裝置的狀態

您可以使用 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 指令都會將代號做為參數。如要進一步瞭解 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 允許對網址、路徑名稱和元件執行個體 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 元件。首先，您需要在自己的環境中安裝 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 進行測試

編寫需要與 Fuchsia 環境互動的整合測試時，ffx 指令非常實用。不過，由於 ffx 主要為開發人員設計，因此會檢查目前的環境設定，並在背景啟動精靈，協調與 Fuchsia 裝置的通訊。這使得使用 ffx 編寫自動化測試變得更加複雜，因為設定和精靈應隔離，以免產生副作用或受到全域環境干擾。

為達成這種隔離效果，測試作者在執行使用 ffx 的測試時，需要使用隔離目錄。

後續步驟