ArcaneNibble/awawausb

来源：https://github.com/ArcaneNibble/awawausb

Firefox 的 WebUSB 扩展

本扩展通过利用原生消息传递（native messaging）为 Firefox 添加 WebUSB 功能。

若要使用本扩展，你需要同时在浏览器中安装该扩展，并在电脑上安装一个独立于浏览器之外的小程序。这个额外的程序被称为“原生存根（native stub）”。

功能支持

本扩展的目标是与 Chrome 的实现保持兼容。如果你遇到任何导致软件无法正常工作的差异，请向我们报告。

然而，与 Chrome 不同的是，此 API 仅在主页面中暴露，在 Web Workers（https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers）中不可用。

Android 不受支持，因为它不具备原生消息传递功能。

安装说明

你可以从 GitHub 右侧栏的“Releases”部分下载二进制文件来安装本扩展，也可以从源码自行构建。

安装扩展

要安装签名版本，请下载 .xpi 文件并在 Firefox 中打开。

要在 Firefox Developer Edition 中加载扩展的测试版本，请打开 about:debugging，在左侧列表中选择“This Firefox”，然后点击“Load Temporary Add-on…”，并浏览到 extension/ 目录中的 manifest.json。

安装原生存根

如果你使用的是预构建二进制文件，请解压全部文件，然后运行 ./install.sh（在 Linux 或 macOS 上）或 install.bat（在 Windows 上）。这些安装程序会尝试自动将相关文件复制到合适的位置，并配置原生清单（https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests），以便浏览器能够找到它。

以下平台提供预构建二进制文件：

• macOS x86_64 和 ARM64
• Linux x86_64 和 aarch64
• Windows AMD64 和 ARM64

如果你不使用预构建二进制文件，请参阅下文。

“非常规”配置

默认安装程序在以下非常规配置中已知存在问题：

• 在不同 CPU 架构的计算机之间共享 *nix 主目录
• 在不同 CPU 架构的计算机之间使用 Windows 漫游用户配置文件

其根本原因在于“原生清单”机制在设计时没有很好地考虑这些情况（例如，它使用了绝对路径）。如果你处于上述情况之一，很遗憾，你需要自行想一个临时解决方案。

系统要求

该原生存根尽量避免做任何过于“激进”的操作，但由于开发和测试资源有限，它主要面向“相当现代”的桌面平台。

macOS

需要 macOS 10.15 或更高版本，这与 Firefox 的系统要求一致。但较旧的系统没有经过充分测试。建议以 macOS 12 作为更合理的基线。

Windows

由于 Rust 平台支持的要求，需要 Windows 10 或更高版本。这也与 Firefox 的系统要求一致。理论上可能可以移植回 Windows 8/8.1，但更旧的系统预计无法工作（受限于 WinUSB）。

Linux

需要 Linux 内核版本 4.8 或更高版本。（更具体地说，强烈建议使用包含提交 5cce438 和 USBDEVFS_CAP_REAP_AFTER_DISCONNECT 的内核，且必须支持 USBDEVFS_DISCONNECT_CLAIM。）

你的系统必须挂载了 /dev 和 /sys。

为了检测 USB 设备的连接，需要一个带有 udev（https://man7.org/linux/man-pages/man7/udev.7.html）或兼容守护进程的用户空间。具体来说，需要一个在 NETLINK_KOBJECT_UEVENT 组 2 上广播 0xfeedcafe 格式消息的守护进程。

从源码编译

一般来说，该原生存根完全使用 Rust 编写，可以在 native-stub 目录中通过 cargo build 构建。支持交叉编译，并且默认已为受支持的平台进行了配置。

如果无法“直接工作”，以下提示可能会有所帮助：

macOS

这真的应该直接就能工作。仓库中包含了链接最终二进制所需的所有 .tbd 文件的 vendored 副本。如果这不知怎么导致了问题，请禁用 .cargo/config.toml 中的相应条目（之后你需要安装 macOS SDK）。

Linux

Linux 预构建二进制文件配置为使用 musl libc（https://www.musl-libc.org/），并采用 Rust 默认的静态链接。这样做的目标是生成可在任何发行版上运行的二进制文件。如果你不希望如此，可能需要修改相应的 RUSTFLAGS。

使用 glibc 构建应该可以工作，但未经测试。

Windows

Windows 预构建二进制文件配置为使用 mingw-w64（https://www.mingw-w64.org/）构建，目标为 UCRT。这对应于 Rust 中的 *-windows-gnullvm 目标。

Windows 版本主要在非 Windows 平台上通过交叉构建进行测试。在 Windows 上构建应该也能工作，但可能需要添加 rust-mingw 组件。更多详情请参阅 rustc 文档（https://doc.rust-lang.org/nightly/rustc/platform-support/windows-gnullvm.html#building-rust-programs）。

如果你在非 Windows 系统上构建，需要从某处获取 mingw-w64 的 .lib 文件（例如按照 Dockerfile 中的步骤操作）。.cargo/config.toml 中有一个硬编码的路径，需要检查或修改以便找到这些库。

使用 MSVC 工具链构建不受支持（并非原则上不可行，只是未经测试）。

配置原生清单

为了让浏览器找到你编译好的二进制文件，你需要在电脑的特定位置安装一个“清单”文件。该清单是一个简短的 JSON（JavaScript Object Notation）文件，根据操作系统的不同放在特定的位置（https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests#manifest_location）。文档中的相关路径如下：

macOS

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

~/Library/Application Support/Mozilla/NativeMessagingHosts/awawausb_native_stub.json（用户本地）

Linux

/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（用户本地）

Windows

清单文件可以放在任意位置，但必须设置一个注册表键来指向它。注册表键为：

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

HKCU\SOFTWARE\Mozilla\NativeMessagingHosts\awawausb_native_stub（用户本地）

以下截图展示了一个正确配置的注册表项：

reg

原生清单的内容

JSON 文件应包含以下内容：

{
  "name": "awawausb_native_stub",
  "description": "Allows WebUSB extension to access USB devices",
  "path": "/path/to/awawausb-native-stub",
  "type": "stdio",
  "allowed_extensions": ["[email protected]"]
}

但在 Windows 上，不需要完整路径（即仅 "awawausb-native-stub.exe" 就足够了）。

开发者文档

请参阅 Documentation/architecture.md 开始了解。