我們會閱讀每一則回饋，並非常重視您的意見。

欲查看所有可用的限定符，請參閱我們的文件。

此擴充套件透過使用原生訊息（native messaging）為 Firefox 新增 WebUSB 功能。

使用此功能時，您需要在瀏覽器中安裝擴充套件，並在電腦上安裝一個獨立的小程式，稱為「原生 stub」。

此擴充套件應與 Chrome 的實作相容，若遇到任何導致軟體無法運作的差異，請回報。

不過，與 Chrome 不同的是，此 API 僅在主頁面可用，Web Workers 中無法使用。

Android 無法支援，因其不具備原生訊息功能。

此擴充套件僅支援 WebUSB，WebUSB 是網頁存取實體裝置的多種方式之一（即使裝置是透過 USB 連接到電腦）。

請閱讀相關文件以獲得詳細說明。

您可以從 GitHub 的「Releases」頁面下載二進位檔安裝此擴充套件，或自行從原始碼編譯。

安裝簽署版本時，下載 .xpi 檔案並在 Firefox 中開啟即可。

若使用 Firefox Developer Edition 測試版本，請開啟 about:debugging，選擇左側清單的「This Firefox」，點選「Load Temporary Add-on…」，然後瀏覽至擴充套件目錄中的 manifest.json。

若使用預建二進位檔，請解壓所有檔案，並執行 ./install.sh（Linux 或 macOS）或 install.bat（Windows）。安裝程式會嘗試自動將檔案複製到合適位置，並設定原生清單以便瀏覽器尋找。

預建二進位檔支援以下平台：

若不使用預建檔案，請參考下方說明。

預設安裝程式在某些非典型配置上可能有問題，原因在於「原生清單」機制設計時未充分考慮這些情況（例如使用絕對路徑）。若遇此狀況，您可能需要自行想出臨時解決方案。

此原生 stub 盡量避免執行過於複雜的操作，但因開發與測試資源有限，主要針對「較新」的桌面平台。

macOS 需 10.15 以上版本，符合 Firefox 系統需求。舊系統測試較少，建議以 macOS 12 作為合理基準。

Windows 需 10 以上版本，因 Rust 平台支援需求，也符合 Firefox 系統需求。理論上可回溯支援 Windows 8/8.1，但更舊版本不被預期可用（因 WinUSB 限制）。

Linux 需核心版本 4.8 以上（更精確地說，需包含 commit 5cce438 與 USBDEVFS_CAP_REAP_AFTER_DISCONNECT，且必須支援 USBDEVFS_DISCONNECT_CLAIM）。

系統必須掛載 /dev 與 /sys。

偵測 USB 裝置連接需使用 udev 或相容守護程序，該守護程序需在 NETLINK_KOBJECT_UEVENT 群組 2 廣播 0xfeedcafe 格式訊息。

此原生 stub 完全以 Rust 撰寫，可在 native-stub 目錄使用 cargo build 編譯，支援交叉編譯，並預設配置支援平台。

若無法正常運作，以下說明或許有幫助：

理論上應該直接可用。倉庫內含所有連結最終二進位檔所需的 .tbd 檔案。如有問題，可在 .cargo/config.toml 中停用相關條目（此時需安裝 macOS SDK）。

Linux 預建檔使用 musl libc 與 Rust 預設靜態連結，目標是產生跨發行版可用的二進位檔。如不需此設定，可能需調整 RUSTFLAGS。

Glibc 編譯理論可用，但未測試。

Windows 預建檔使用 mingw-w64 編譯，目標為 UCRT，對應 Rust 的 *-windows-gnu 目標。

Windows 主要透過非 Windows 平台交叉編譯測試。Windows 上編譯理應可行，但可能需安裝 rust-mingw 元件，詳見 rustc 文件。

非 Windows 系統編譯時，需取得 mingw-w64 .lib 檔（例如參考 Dockerfile 步驟），並檢查/修改 .cargo/config.toml 中硬編碼路徑以尋找這些庫。

不支援使用 MSVC 工具鏈編譯（無根本性障礙，僅未測試）。

瀏覽器要找到編譯好的二進位檔，需在電腦特定位置安裝「清單」檔案。清單為短小 JSON 檔，依作業系統放置於不同路徑。重點路徑如下：

/Library/Application Support/Mozilla/NativeMessagingHosts/awawausb_native_stub.json（全域）

~/Library/Application Support/Mozilla/NativeMessagingHosts/awawausb_native_stub.json（使用者）

/usr/lib/mozilla/native-messaging-hosts/awawausb_native_stub.json（全域）

/usr/lib64/mozilla/native-messaging-hosts/awawausb_native_stub.json（全域）

~/.mozilla/native-messaging-hosts/awawausb_native_stub.json（使用者）

清單檔可放任意位置，但必須設定註冊表鍵指向它。註冊表鍵如下：

HKLM\SOFTWARE\Mozilla\NativeMessagingHosts\awawausb_native_stub（全域）

HKCU\SOFTWARE\Mozilla\NativeMessagingHosts\awawausb_native_stub（使用者）

Windows 上不需完整路徑，僅需 "awawausb-native-stub.exe" 即可。

此擴充套件內建除錯頁面，可點擊瀏覽器工具列的按鈕（通常在「擴充功能」圖示中）進入。

對終端使用者而言，除錯頁面最有用的功能是「列出裝置」按鈕，可顯示擴充套件已知的所有 USB 裝置（即使沒有網頁嘗試連接）。

若您想讓網頁連接的裝置未出現在此列表，表示作業系統層級有設定問題，需在瀏覽器外調整電腦設定，可能需要管理員權限。

開發者可參考此擴充套件的內部除錯功能說明。

在 Windows 上，此擴充套件只能存取使用「WinUSB」驅動程式的 USB 裝置。驅動程式是電腦用來與裝置溝通的特殊軟體。

USB 裝置設計者會在裝置中放入資訊，建議使用適當驅動程式。例如滑鼠或鍵盤會建議使用標準驅動，網路攝影機會建議使用標準攝影機驅動，特殊裝置可能建議自訂驅動。

WinUSB 是可與「任何」USB 裝置溝通的驅動程式，但使用 WinUSB 會犧牲系統對裝置特殊功能的支援。使用 WinUSB 時，只有一個程式能獨佔裝置，且無法享有作業系統的多工支援。例如 USB 印表機若使用「印表機」驅動，系統可讓多個程式排隊列印；若改用 WinUSB，則只能一個程式獨佔，且需自行實作與印表機溝通的程式碼。

對於不需系統共用功能的「簡單」裝置，製造商可建議 Windows 使用 WinUSB，這是 WebUSB 設計裝置的推薦做法，通常不需使用者額外設定。

系統管理員可覆寫 Windows 或裝置製造商的驅動建議，例如強制使用 WinUSB，原因可能是原建議驅動不相容或不穩定，或為了使用第三方軟體（如 WebUSB）控制裝置。

可使用名為 Zadig 的工具輕鬆重新設定裝置驅動，選擇 WinUSB 以使裝置相容 WebUSB。請在了解影響後再操作。

大多數 Linux 安裝預設不允許「非特權」使用者存取 USB 裝置。此慣例源自多用戶遠端使用的 UNIX 類系統，且即使在個人電腦上也常見（例外如 Steam Deck 預設允許非特權存取）。

USB 裝置存取權限由 /dev/bus/usb 裡的裝置節點檔案系統權限控制，可用 ls -l 查看一般權限，getfacl 查看 POSIX ACL 權限。Linux 權限概念較複雜，OpenBSD 的 chmod 手冊是入門好資源。

實際更改權限較困難，因裝置節點會在 USB 插拔時刪除重建，權限會重置。大多數 Linux 桌面系統透過 udev 服務管理權限。

Linux 安裝高度可自訂，無單一通用設定，但常見做法有三種，推薦使用第三種。

這些選項差異在於特定情境，如遠端登入或快速切換使用者，對於現代個人電腦實體使用者影響有限。

設定第三種方法時，通常在 /etc/udev/rules.d/50-my-usb-device.rules 新增規則。

第一與第二種方法則透過 udev 規則中的 MODE= 與 GROUP= 指令設定。

可能需使用 root 權限執行 udevadm 指令重新載入或套用規則，或重新插拔裝置。

更多資訊請參考 Documentation/architecture.md 開始了解。