← 返回文档

macOS 安装指南

本指南将指导您在 macOS 系统上安装 Sokuji。Sokuji 以未签名的 .pkg 安装包形式提供，其中包含用于增强音频处理功能的虚拟音频驱动程序。

下载 macOS 版本

系统要求

  • macOS 13 (Ventura) 或更高版本（v0.42.2 起；macOS 12 可继续使用 v0.42.1）
  • Apple Silicon (M1/M2/M3/M4) 或 Intel (x86_64) 处理器
  • 最低4GB内存（推荐8GB）
  • 200MB可用磁盘空间
  • 管理员权限（安装虚拟音频驱动程序所需）
  • 用于AI翻译服务的互联网连接
  • 麦克风和扬声器/耳机

安装步骤

步骤 1：下载 Sokuji

访问 官方 GitHub 发布页面 下载最新的 macOS 版本 Sokuji。

下载 PKG 安装包

  • Sokuji-x.x.x-arm64.pkg - 适用于 Apple Silicon Mac (M1/M2/M3/M4)
  • Sokuji-x.x.x-x64.pkg - 适用于 Intel Mac
  • 每个安装包均包含 Sokuji 应用程序和虚拟音频驱动程序
  • 文件大小约为 150-200MB

提示：不确定下载哪个版本？点击苹果菜单（）→"关于本机"查看芯片类型。如果显示"Apple M1/M2/M3/M4"，请选择 arm64 版本。如果显示"Intel"，请选择 x64 版本。

PKG 安装包未签名，这意味着您需要采取特殊步骤来安装它（将在下一步中介绍）。

步骤 2：准备安装

由于 PKG 安装包未签名，macOS 默认会阻止它。您需要在安装前移除隔离属性。

移除隔离属性（必需）

  1. 打开终端（应用程序 → 实用工具 → 终端）
  2. 输入或粘贴以下命令（将 x.x.x 替换为您的版本号）：

    sudo xattr -d com.apple.quarantine ~/Downloads/Sokuji-x.x.x-arm64.pkg

    Intel Mac 请使用：sudo xattr -d com.apple.quarantine ~/Downloads/Sokuji-x.x.x-x64.pkg

  3. 按回车键，在提示时输入管理员密码
  4. 命令会静默完成（没有输出表示成功）

这是做什么的？此命令移除 macOS 添加到下载文件的隔离标志。这对于未签名的 PKG 安装包是安全且必要的。

此步骤至关重要！如果不移除隔离属性，PKG 安装包将无法打开或安装。

步骤 3：安装 PKG

现在您已经准备好安装包，可以安装 Sokuji 及其虚拟音频驱动程序了。

安装过程

  1. 在下载文件夹中找到已下载的 .pkg 文件（如 Sokuji-x.x.x-arm64.pkg 或 Sokuji-x.x.x-x64.pkg）
  2. 双击 PKG 文件开始安装
  3. macOS 安装器将打开 - 点击"继续"继续
  4. 查看安装详情并点击"安装"
  5. 在提示时输入管理员密码（安装驱动程序需要）
  6. 等待安装完成（通常需要 1-2 分钟）
  7. 安装完成后点击"关闭"

安装内容

  • Sokuji.app - 安装到 /Applications
  • SokujiVirtualAudio.driver - 虚拟音频驱动程序安装到 /Library/Audio/Plug-Ins/HAL
  • 安装器会自动重启 CoreAudio 以加载驱动程序
需要管理员密码是因为安装器需要安装系统级音频驱动程序。虚拟音频驱动程序实现了高级音频处理功能。

步骤 4：首次启动

安装后，您可能需要授予 Sokuji 运行权限，因为它是从 App Store 外下载的。

首次打开 Sokuji

  1. 导航到您的应用程序文件夹
  2. 在列表中找到 Sokuji
  3. 右键单击（或按住 Control 单击）Sokuji
  4. 从上下文菜单中选择"打开"
  5. 当安全对话框出现时，点击"打开"确认

注意：如果您正确完成了步骤 2，可能不会看到任何安全警告。

替代方法

如果 macOS 仍然阻止 Sokuji：
  1. 打开系统偏好设置 → 安全性与隐私
  2. 转到通用选项卡
  3. 您应该看到关于 Sokuji 被阻止的消息
  4. 点击"仍要打开"
此安全警告仅在首次启动时出现。之后，您可以从启动台或应用程序正常打开 Sokuji。

步骤 5：配置 Sokuji

现在 Sokuji 正在运行，让我们进行首次使用配置：

初始设置

  1. 当 macOS 提示时授予麦克风权限
  2. 选择您喜欢的界面语言
  3. 选择您的 AI 提供商（OpenAI、Google Gemini 等）
  4. 输入所选提供商的 API 密钥
  5. 选择翻译的源语言和目标语言
  6. 选择您的麦克风，并在语音区块中把默认播放设备设为您的扬声器或耳机。Sokuji 不会在这里列出它自己的虚拟音频设备：对方听到的翻译会把您的翻译送进这个设备，也就是会议应用里要选择的虚拟麦克风
  7. 测试您的麦克风和扬声器设置
恭喜！Sokuji 现在已准备就绪。虚拟音频驱动程序已安装并可在您的音频设备列表中使用。点击麦克风按钮开始实时翻译。

故障排除

"软件包已损坏，无法打开"或 PKG 无法安装

当未从 PKG 文件移除隔离属性时会发生这种情况：
  1. 打开终端（应用程序 → 实用工具 → 终端）
  2. 运行：sudo xattr -d com.apple.quarantine ~/Downloads/Sokuji-*.pkg
  3. 在提示时输入密码
  4. 再次尝试安装 PKG
这是未签名 PKG 安装包最常见的安装问题。

无法打开 Sokuji，因为它来自身份不明的开发者

如果您在安装前没有运行 xattr 命令会发生这种情况：
  1. 在应用程序中右键单击 Sokuji 应用
  2. 从菜单中选择"打开"
  3. 在出现的对话框中点击"打开"
您只需要执行一次此操作。更好的方法：在移除隔离属性后卸载并重新安装。

麦克风不工作

如果 Sokuji 无法访问您的麦克风：
  1. 打开系统偏好设置 → 安全性与隐私 → 隐私
  2. 从左侧边栏选择麦克风
  3. 确保列表中的 Sokuji 已勾选
  4. 如果未列出，请重启 Sokuji 并在提示时授予权限

无音频输出

如果您听不到翻译的音频：
  1. 打开系统偏好设置 → 声音 → 输出
  2. 选择您的首选输出设备
  3. 检查输出音量是否未静音
  4. 在 Sokuji 的语音区块中，检查您想听到的那一行所选的设备：您自己的翻译看我也听（默认关闭），对方的翻译看我听到的翻译，其他声音看默认播放设备

在 Intel Mac 上崩溃或性能问题

请确认您下载了正确的安装包：
  • Apple Silicon (M1/M2/M3/M4)：使用 Sokuji-x.x.x-arm64.pkg
  • Intel：使用 Sokuji-x.x.x-x64.pkg
  • 查看芯片类型：苹果菜单（）→"关于本机"
  • 如果使用了错误的安装包，请从发布页面下载正确的版本
  • 如果使用正确的安装包仍然崩溃，请检查控制台应用中的崩溃日志并在 GitHub 上报告

虚拟音频驱动程序未显示

如果您在音频设备中看不到"SokujiVirtualAudio"：
  1. 先让 Sokuji 自己修：驱动已安装但 macOS 没有加载时，Sokuji 启动后会提示“虚拟麦克风已安装，但 macOS 没有加载它”，点击修复，输入管理员密码，Sokuji 会重启 Core Audio 加载驱动，无需重启 Sokuji
  2. 检查驱动程序是否已安装：ls /Library/Audio/Plug-Ins/HAL/
  3. 如果不存在，您可能需要重新安装 Sokuji
  4. 如果存在而修复无效，尝试重启 CoreAudio：sudo killall coreaudiod，或重启 Mac
  5. 检查系统设置 → 声音以查看设备是否出现

安装需要管理员密码

这是正常且必需的：
  • PKG 安装器需要安装系统级音频驱动程序
  • 系统音频驱动程序需要管理员权限才能安装
  • 在提示时输入密码 - 这是安全且预期的
  • 如果您没有管理员访问权限，请联系系统管理员