Shell 安装器（Electron）¶

该 Shell 安装器支持 macOS（Apple Silicon 和 Intel）以及 Linux x64。在 Windows 上，请从 Releases 下载 VoiceStudio-…-win-x64.exe 安装程序（或在 Snapdragon/ARM PC 上下载 …-win-arm64.exe）。

或者使用 PowerShell。请使用 .ps1 URL：裸 /install URL 不保证能识别 PowerShell，并且可能返回 shell 脚本（#2973）：

irm https://voicestudio.sh/install.ps1 | iex
$env:VOICESTUDIO_VERSION='X.Y.Z'; irm https://voicestudio.sh/install.ps1 | iex
# Clear a previous version override before selecting main:
Remove-Item Env:VOICESTUDIO_VERSION -ErrorAction SilentlyContinue
$env:VOICESTUDIO_INSTALL_MODE='main'; irm https://voicestudio.sh/install.ps1 | iex

在 ARM64 Windows 上，脚本会安装原生 ARM64 构建产物；当某个版本没有 ARM64 构建时，则回退到 x64 构建。Windows 的 main 构建还需要 Visual Studio C++ 构建工具（ARM 上还需要 ARM64 构建工具）。该脚本会构建一个 NSIS 安装程序，打开其安装向导，并等待安装完成。环境变量覆盖设置会保留在终端中；删除它们即可恢复为最新发布版模式。

# Latest stable Electron release
curl -fsSL https://voicestudio.sh/install | sh

# A published Electron version, with or without a v prefix
curl -fsSL https://voicestudio.sh/install | sh -s -- --version X.Y.Z

# Clone main, build a desktop package, then install it
curl -fsSL https://voicestudio.sh/install | sh -s -- --main

--source 是 --main 的别名，不能与 --version 同时使用。发布包命名为 VoiceStudio-<version>-<os>-<arch>；安装程序仍能识别直到 v0.5.7-beta.3 版本所使用的 VoiceStudio-Electron-* 命名。下载脚本进行检查后，对应的本地命令分别是 sh scripts/install.sh、sh scripts/install.sh --version X.Y.Z 和 sh scripts/install.sh --main。

发布版本安装¶

如果 voicestudio.sh/install 无法访问或返回 404，请直接从仓库运行同一脚本，或克隆仓库后运行 scripts/install.sh：

curl -fsSL https://raw.githubusercontent.com/debpalash/VoiceStudio/main/scripts/install.sh | sh

需要 curl 以及 shasum（macOS 自带）或 sha256sum。安装程序会解析最新的 GitHub 发布标签，下载 Electron DMG 或 AppImage，并对照该版本的 SHA256SUMS.txt 校验其确切文件名。缺少包、缺少校验和以及校验和不匹配都会中止安装。不会使用固定的 latest.json Tauri 更新源。没有 Electron 包的版本无法通过此脚本安装。

在替换 VoiceStudio 之前，请完全退出 VoiceStudio（macOS 上按 Command-Q）。当 pgrep 可用时，Shell 安装器会拒绝替换或卸载正在运行的应用，并在替换文件之前再次检查。macOS 会刷新已安装应用的 Launch Services 注册信息，以便 Launchpad 能找到新版本。macOS 会将 VoiceStudio.app 安装到 /Applications；如果 /Applications 不可写，则安装到 ~/Applications。在 macOS 上，安装器还会清除 com.apple.quarantine 标志；当 codesign --verify --deep --strict 失败时（在构建改为 ad hoc 签名之前发布的版本，即 #2763），会以 ad hoc 方式重新签名该应用包，这样 Gatekeeper 就不会报告“已损坏”。有效的或经过公证的签名绝不会被改动。在 Intel Mac 上，它会提示本地后端需要 Apple Silicon。Linux 会将应用安装到 ~/.local/bin/VoiceStudio；请将 ~/.local/bin 加入你的 PATH。

当前的 Electron 源码构建还会读取归档的安装配置，以获取自定义数据/模型文件夹和可移植存储路径；显式的启动环境覆盖设置仍然优先。后端保留其已有的持久化 Settings 优先级。不会移动或复制任何文件。之前发布的安装程序保留其原有行为。只有在暂存成功之后，现有应用才会被替换。用户设置、项目、模型下载和后端环境不会被删除。降级后可能无法读取由更新版本创建的数据；请先备份重要项目。

如需进行隔离的 Shell 安装器测试，可通过 VOICESTUDIO_INSTALL_DIR 指定安装目录；该目录必须是绝对路径、已存在且可写。无效的覆盖设置会直接失败，而不会回退到其他位置。

卸载¶

先退出 VoiceStudio，然后运行：

curl -fsSL https://voicestudio.sh/install | sh -s -- --uninstall

在 macOS 上，这会从 /Applications 和 ~/Applications 中移除 Electron 应用；在 Linux 上，它会移除通过脚本安装的 ~/.local/bin/VoiceStudio AppImage。VOICESTUDIO_INSTALL_DIR 可将移除范围限制在自定义安装目录内。在 macOS 上，应用会被取消注册并移入废纸篓中一个唯一命名的文件夹；它绝不会作为隐藏应用保留在 /Applications 下（否则 Launchpad 仍可能发现它）。Linux 则使用一个隐藏的兄弟恢复目录。会打印出确切的恢复路径。将应用移回即可恢复，或删除该副本以回收磁盘空间。通过包管理器安装的应用必须使用相应的包管理器来卸载。归档的 Tauri 应用不会被移除。

Remove-Item Env:VOICESTUDIO_VERSION -ErrorAction SilentlyContinue
$env:VOICESTUDIO_INSTALL_MODE='uninstall'; irm https://voicestudio.sh/install.ps1 | iex

Windows 会跳过归档的 Tauri 注册表条目，并打开一个经过验证的 Electron 卸载向导。如需无人值守的 Windows 安装/卸载（例如 CI），请使用 -Silent 参数；默认仍为交互式安装。所有平台都会保留设置、项目、后端环境和模型。要删除应用数据，请在卸载之前使用 VoiceStudio 应用内的数据删除确认功能；CLI 不会猜测自定义存储位置，也不会删除共享的模型缓存。

构建 main 分支¶

在运行 --main 之前，请安装 Git、Node.js 22 或更高版本、Bun（根目录 package.json 中固定的版本）以及稳定的 Rust/Cargo。在 macOS 上，请安装 Xcode Command Line Tools（xcode-select --install）；在 Apple Silicon 上请使用原生 arm64 终端。在 Debian/Ubuntu 上，请安装 Electron 构建所需的原生依赖：

sudo apt-get install build-essential pkg-config libasound2-dev libxdo-dev \
  libxtst-dev libx11-dev libxkbcommon-dev libwayland-dev libssl-dev \
  binutils zsync

其他 Linux 发行版需要等效的开发包。运行该应用需要图形会话和常规的 Electron 运行时库。构建过程会下载依赖项，可能需要几分钟时间和数 GB 空间。

每次调用都会将 main 克隆到临时目录，打印其提交信息，安装锁定的 Bun 依赖项，打包 Electron 及其 Rust 原生辅助程序，然后安装结果。它绝不会更新或重置现有的源代码检出。临时文件无论成功或失败都会被删除。本地包未签名；可能会触发常规的操作系统安全提示。不会进行任何发布。

打开已安装的应用，配置其本地 Python 后端并选择模型。该脚本不会启动开发服务器，也不会下载模型权重。Intel Mac 可以使用 Electron UI 搭配远程后端；本地 Python/ML 支持仍取决于引擎的平台要求。

安装程序回归测试¶

在 electron/ 目录下，运行 node --test tests/shell-installer.test.mjs。这些测试会在临时目录中模拟下载和构建；它们不会安装应用或下载模型。真实的打包构建和首次运行冒烟测试是 Electron 发布流程中独立的检查项。

部署¶

deploy/install-worker/worker.mjs 打包经过测试的 shell 和 PowerShell 脚本，而不是在请求时获取可变的 main 内容。测试后，使用 bunx wrangler deploy --config deploy/install-worker/wrangler.jsonc 进行部署。voicestudio.sh/install* 两条路由都会保留。现有的 Worker 密钥会被保留。脚本更新需要部署才能生效。

Worker 路由测试：在 electron/ 目录下运行 node --test tests/installer-worker.test.mjs。PowerShell 流程测试：pwsh -NoProfile -File tests/powershell-installer.ps1。它们会模拟 Windows 安装执行过程；真实的 Windows 安装/构建仍然需要 Windows 机器。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 om/VoiceStudio