適用範圍

本文適用於需要在 Linux 系統上安裝和運行 OneKey App 的用戶。

不同 Linux 發行版的依賴和權限策略可能不同。本文以 Ubuntu / Debian 系統為主要示例，同時提供通用的 udev 規則設定方法。

安裝前準備：設定 udev 規則

在 Linux 系統中，udev 規則用於讓系統正確識別 OneKey 硬件錢包。無論你使用 Snap 還是 AppImage，都建議先完成此步驟。

下載並安裝 OneKey udev 規則：

sudo curl -fsSL https://data.onekey.so/onekey.rules -o /etc/udev/rules.d/99-onekey.rules

如果系統未安裝 curl，可以先運行：

sudo apt update 
sudo apt install curl

重新載入 udev 規則：

sudo udevadm control --reload-rules sudo udevadm trigger

安裝 Snap：
```
sudo apt update 
sudo apt install snapd
```
如果你使用的是其他 Linux 發行版，可參考 Snap 官方文件安裝 snapd。
安裝 OneKey App：
```
sudo snap install onekey-wallet
```
你也可以打開 Snap 商店頁面安裝：https://snapcraft.io/onekey-wallet
允許 OneKey App 訪問 USB 設備：
```
sudo snap connect onekey-wallet:raw-usb
```
打開 OneKey App，並選擇連接硬件錢包。

如果啟動時出現類似錯誤：

error while loading shared libraries: libgbm.so.1: cannot open shared object file

通常表示當前 Snap 包內缺少圖形庫依賴。

由於 Snap 使用沙箱隔離機制，即使在宿主機系統中安裝 libgbm1，Snap 應用也不一定能讀取宿主機中的圖形庫。

如遇到該問題，建議暫時改用 AppImage 版本，或等待 OneKey 更新 Snap 安裝包後再使用 Snap 版本。

在 Ubuntu 24.04 及以上版本中，系統預設啟用了更嚴格的非特權用戶命名空間限制。部分 AppImage 應用可能會因為 Electron / Chromium 沙箱初始化失敗而無法啟動。

如果運行 AppImage 時出現類似錯誤：

The SUID sandbox helper binary was found, but is not configured correctly

或提示 chrome-sandbox 權限異常，可嘗試使用以下命令啟動：

./OneKey-Wallet-*.AppImage --no-sandbox

請確保命令在 AppImage 文件所在目錄中運行。

如果運行時遇到缺少 X Server 或 $DISPLAY 的錯誤，通常表示當前系統缺少圖形桌面環境或相關組件。

對於 Ubuntu / Debian 系統，可以安裝圖形環境相關組件後再嘗試運行。

請依次檢查：

如果你使用 Snap 版本，請確認已經運行：

sudo snap connect onekey-wallet:raw-usb