企业官网建设流程全解析

Vocalinux是一款面向 Linux 的免费、开源、100% 离线语音输入（voice dictation）工具：按住快捷键说话，识别出的文字会直接落到当前焦点窗口。它内置 whisper.cpp、OpenAI Whisper、VOSK、Parakeet 等本地引擎，支持 Vulkan GPU 加速，同时兼容 X11 与 Wayland。目前官方提供9 种安装方式，本文从适用系统、GPU 支持、更新机制、权限配置 4 个维度逐一横评，帮你在 1 分钟内选到最合适的那一种。

快速选型：哪种安装方式适合你？

📌 基础要求：Linux + X11 或 Wayland + 麦克风；install.sh 与 PyPI 路线要求发行版自带Python 3.11+（Ubuntu 22.04 / Debian 11 不满足，可选 AppImage 或 Flatpak）。磁盘约 200MB，内存 4GB 起。完整支持矩阵见 docs/DISTRO_COMPATIBILITY.md。

9 种安装方式逐一横评：步骤、GPU 支持、更新机制

1️⃣ install.sh 安装脚本（官方推荐，新手首选）

适合：Ubuntu 24.04+、Debian 12+、Fedora 42+、Arch、openSUSE Tumbleweed 等支持 Python 3.11+ 的发行版。

脚本会自动完成全套工作：检测发行版与 GPU/Vulkan（AMD、Intel、NVIDIA 均可）、安装默认引擎 whisper.cpp（约 1–2 分钟，无需庞大的 PyTorch 依赖）、下载约 74MB 的 tiny 模型（带校验和验证）、按需安装 Silero 神经 VAD，并写好桌面菜单项与启动器。

# 克隆仓库后直接运行（推荐先审阅脚本内容） ./install.sh # 交互模式 ./install.sh --auto # 全自动，默认 whisper.cpp ./install.sh --auto --engine=vosk # 低内存机型可选

• 🟢 体验最完整：依赖、模型、桌面集成一次到位；更新时重跑脚本即可，配置和模型会保留
• 🔴 唯一门槛：发行版必须自带 Python 3.11+

2️⃣ AppImage 便携安装（老系统与"零污染"首选）

适合：不想装系统包、想拷贝到 U 盘随身用，或系统 Python 版本不够 3.11 的用户。

从 Releases 下载Vocalinux-*-x86_64.AppImage（或aarch64），赋予执行权限即可运行：

chmod +x Vocalinux-*-x86_64.AppImage ./Vocalinux-*-x86_64.AppImage

• 🟢 自带Vulkan 版 whisper.cpp并直接调用宿主机 GPU 驱动，是较老系统上唯一能吃到 GPU 加速的方式
• 🟢 兼容性门槛低：glibc 2.35+ 即可（Debian 12+、Ubuntu 22.04+、Fedora 36+、Arch、Tumbleweed）
• 🔴 宿主机仍需文本注入工具（X11 用xdotool，Wayland 用wtype/ydotool等）
• 🔴 无自动更新：每次发新版都要手动下载新文件替换

3️⃣ .deb / .rpm 发行版原生包（Debian、Ubuntu、Fedora）

适合：习惯用apt/dnf管理软件的用户。.deb支持 Debian 12+、Ubuntu 24.04+，.rpm支持 Fedora。

sudo apt install ./vocalinux_*_amd64.deb # Debian / Ubuntu sudo dnf install ./vocalinux-*.x86_64.rpm # Fedora

• 🟢 "薄包"设计：Python、GTK、PyGObject 全部来自发行版，包内仅内置pywhispercpp和pynput，依赖由apt/dnf自动解析，干净无冲突
• 🔴 包内 whisper.cpp 为CPU 版（无 Vulkan 构建），无自动更新，目前也没有 PPA / COPR 仓库
• ⚠️ Wayland 下全局快捷键走 evdev，需要把用户加入input组（sudo usermod -aG input $USER后重新登录），安装包不会替你执行这一步

4️⃣ AUR 一条命令安装（Arch / Manjaro）

Arch 系用户的最短路径，详见 docs/AUR.md：

yay -S vocalinux # 最新 release yay -S vocalinux-git # 社区包，跟踪 main 分支

• 🟢 与系统包管理器完全融合，yay -Syu时顺带升级
• ⚠️ AUR 中的python-pywhispercpp系列仍是 1.4.x 且没有 Vulkan 构建包——想要 GPU 加速请改用 install.sh 或 AppImage
• ⚠️vocalinux、vocalinux-bin（AppImage 变体）、vocalinux-git三者互相冲突，只装其一

5️⃣ Flatpak 安装（沙盒隔离 + 自动更新）

适合不可变系统、非主流发行版，以及追求"装完就不管"的用户。Vocalinux不在 Flathub，而是走官方自托管的 VocaHQ 远程仓库，首次添加远程后即可：

flatpak install vocahq com.vocalinux.Vocalinux flatpak update # 每次发新版都会自动收到

• 🟢 内置 whisper.cpp + Vulkan + Silero VAD；官方远程支持flatpak update自动更新（Releases 里 sideload 的.flatpak捆绑包则不能）
• 🟢 配置与模型独立存放在~/.var/app/com.vocalinux.Vocalinux/，卸载即干净
• ⚠️ Wayland 下内置快捷键需要/dev/input设备权限；若不想给设备权限，可在Settings → Shortcuts开启 External Activation，绑定桌面快捷键调用 D-BusToggle（仅支持 toggle 模式）
• 细节见 packaging/flatpak/README.md，清单文件为 packaging/flatpak/com.vocalinux.Vocalinux.yml

6️⃣ Snap 安装（Ubuntu Snap Store，--edge 渠道）

sudo snap install vocalinux --edge

安装后按需在终端手动放行权限（也可在 GUI 权限页操作）：

sudo snap connect vocalinux:audio-record # 麦克风 sudo snap connect vocalinux:raw-input # 全局快捷键（evdev） sudo snap connect vocalinux:hardware-observe # 枚举键盘

• 🟢 商店统一管理，snap refresh vocalinux完成更新
• 🟢 Wayland 下打字走 RemoteDesktop 门户，首次听写时合成器只询问一次
• ⚠️ 当前配方不含uinput插件（商店拒绝了该高权限授予），因此没有 ydotool 兜底；KDE Plasma 用户若遇到 KWin 门户大小写错乱，请在系统设置里把 Virtual Keyboard 设为 "IBus Wayland"
• 配方见 snap/snapcraft.yaml

7️⃣ Nix flake 安装（NixOS / Nix 用户官方途径）

标准 install.sh 并不支持 NixOS，Nix flake 才是官方答案：

nix run github:VocaHQ/vocalinux # 直接试运行 nix profile install github:VocaHQ/vocalinux # 安装到 profile

NixOS 用户引入vocalinux.nixosModules.vocalinux模块后，一行programs.vocalinux.enable = true;即可完成声明式安装（模块还会自动启用hardware.uinput）；Home Manager 用户有对应的homeManagerModules.vocalinux。

• 🟢 GTK、PyGObject 来自 nixpkgs，pywhispercpp由 PyPI sdist 构建，所有注入工具（xdotool、wtype、ydotool、剪贴板工具等）都挂进 PATH，开箱即用
• 🟢 内置 whisper.cpp（Vulkan 便携构建）+ 神经 VAD；nix profile upgrade更新
• 🔴 未打包 vosk / OpenAI Whisper / Parakeet / Faster Whisper 引擎

8️⃣ PyPI 安装（pip / pipx，高级用户完全控制）

适合想自己掌握依赖细节、或走 pip-only 工作流的用户，完整步骤见 docs/INSTALL_MANUAL.md。

关键前提：GTK、PortAudio、文本注入工具这类系统库 pip 装不了，必须先用apt/dnf/zypper装好（各发行版完整清单见 scripts/distro-package-map.yaml），然后：

python3 -m venv ~/.local/share/vocalinux-pypi/venv --system-site-packages source ~/.local/share/vocalinux-pypi/venv/bin/activate pip install vocalinux # 可选 extras: pip install "vocalinux[vad]" # 神经 VAD / [vosk] / [faster_whisper] / [parakeet] vocalinux

• 🟢 引擎组合自由，可只装需要的 extras；也支持pipx install vocalinux
• 🔴 模型需安装后在 Settings 里手动下载；桌面集成需自行配置

9️⃣ 源码安装（贡献者与自定义构建）

克隆仓库（官方镜像地址）：

git clone https://gitcode.com/gh_mirrors/vo/vocalinux cd vocalinux ./install.sh --engine=whisper_cpp # 可自由指定引擎 ./install.sh --dev # 开发模式：可编辑安装 + 测试工具

适合需要改代码、跑测试或做自定义构建的开发者，流程见 CONTRIBUTING.md。

装完之后：更新机制对比与常用操作

Vocalinux 还会在后台定期检测新版本，托盘菜单出现Update Available...入口，Settings → About 页面可查看当前版本、渠道与最新 Release：

装好后第一次听写，按住默认快捷键（新安装默认为Right Alt推键说话）即可，识别文本会实时注入焦点窗口：

日常使用中最常用的是Settings → Speech Model页面：简单模式下选语言与速度/精度，展开Advanced可切换引擎（whisper.cpp / Whisper / VOSK / Parakeet 等）、模型大小与量化规格：

卸载与迁移：源码头安装可用./uninstall.sh --keep-config --keep-data（保留配置与模型）；其余方式分别用apt/dnf remove、flatpak uninstall、snap remove vocalinux即可。各方式的配置文件默认在~/.config/vocalinux/config.json、模型在~/.local/share/vocalinux/（Flatpak 在~/.var/app/com.vocalinux.Vocalinux/下），想换安装方式时留意这两处即可。

FAQ：Vocalinux 安装常见问题

Q1：哪些方式有 GPU 加速？install.sh、AppImage、Flatpak、Nix 四种都内置Vulkan 版 whisper.cpp（AMD / Intel / NVIDIA 均可，vulkaninfo --summary可自检）；.deb / .rpm 是 CPU 版；AUR 目前暂无 Vulkan 构建包。

Q2：Ubuntu 22.04 / Debian 11 能用吗？Python 版本低于 3.11 门槛，install.sh 与 PyPI 路线不可用；可选AppImage（glibc 2.35 门槛以下也不行时，用 Flatpak）或 Flatpak。

Q3：Wayland 下快捷键没反应？

• 系统包 / 源码安装：确认用户已加入input组并重新登录
• Flatpak：需要/dev/input设备权限，或改用 External Activation 桌面快捷键
• Snap：执行sudo snap connect vocalinux:raw-input
• 排查清单见 docs/TROUBLESHOOTING.md

Q4：可以装完后换一种方式吗？可以。先卸载旧方式（保留配置目录），再按新方式安装即可；模型文件较大，迁移时可直接从旧位置拷贝到对应数据目录。

相关文档与源码参考

• 安装总指南：docs/INSTALL.md
• 手动安装 / PyPI 详细步骤：docs/INSTALL_MANUAL.md
• AUR 打包说明：docs/AUR.md
• Flatpak 打包（远程仓库、无设备权限运行）：packaging/flatpak/README.md
• Nix flake 与 NixOS / Home Manager 模块：packaging/nix/README.md
• 更新与发行说明：docs/UPDATE.md
• 发行版兼容性矩阵：docs/DISTRO_COMPATIBILITY.md
• 各发行版系统依赖清单：scripts/distro-package-map.yaml
• 安装脚本源码：install.sh · 卸载脚本：uninstall.sh