鲸海语记(JingNote)App 海外场景 ASR 测试指南

SpeechNote 海外场景 ASR 测试指南

背景

SpeechNote 根据设备地区（Locale.current.regionCode）自动选择 ASR 引擎：

在中国大陆开发环境中，默认走国内路径。以下方法可强制触发海外（Groq）路径，用于功能验证和回归测试。

方法一：修改设备地区（推荐，适用真机/模拟器）

步骤：

1. 1. 打开 设置 → 通用 → 语言与地区 → 地区
2. 2. 将「中国大陆」改为「美国」（或任意非 CN 地区）
3. 3. 运行 app，此时 Locale.current.regionCode 返回 "US"，自动走 Groq 路径
4. 4. 测试完成后改回「中国大陆」

适用场景： 完整 E2E 测试，包括真机录音上传全链路。

注意： 修改地区会影响系统语言排序，建议测试后及时还原。

方法二：Xcode Scheme 启动参数（推荐，不影响设备日常使用）

步骤：

1. 1. Xcode → Product → Scheme → Edit Scheme…
2. 2. 选择左侧 Run → Debug
3. 3. 点击顶部 Arguments 标签
4. 4. 在 Arguments Passed On Launch 区域点击 +
5. 5. 输入 -AppleLocale en_US（注意有 - 前缀）
6. 6. 确保勾选该条目后关闭

Arguments Passed On Launch:
  ✅  -AppleLocale en_US

适用场景： 真机和模拟器均有效，只在从 Xcode 启动时生效，不影响设备日常使用。

常见错误： 不要将 AppleLocale 放在 Environment Variables 区域，该方式仅对模拟器生效，真机无效。

方法三：代码级 Debug 开关（适用于自动化测试）

在 ViewController.swift 的 resolveRecognitionStartPlan() 方法中临时添加：

private func resolveRecognitionStartPlan() -> RecognitionStartPlan {
#if DEBUG
    let regionCode = UserDefaults.standard.string(forKey: "debugRegionOverride")
        ?? Locale.current.regionCode ?? ""
#else
    let regionCode = Locale.current.regionCode ?? ""
#endif
    // ... 后续逻辑不变
}

在测试代码或启动参数中设置：

// 强制海外路径
UserDefaults.standard.set("US", forKey: "debugRegionOverride")

// 恢复真实地区
UserDefaults.standard.removeObject(forKey: "debugRegionOverride")

适用场景： UI 自动化测试、CI 流水线中需要覆盖海外路径的测试用例。

注意： 此修改不应提交到主分支，仅用于本地测试分支。

验证方法

启动 app 后检查 Xcode 控制台，确认以下日志出现：

ASR start plan resolved: Non-CN:preferred=groq

以及录音结束后：

GroqASR: Uploading audio file vad_0_xxxx.wav (xxxxx bytes)
GroqASR: Transcription succeeded, text length xx
VADTranscriber: 切片 #0 成功 → "..."

如果看到 Non-CN:preferred=groq，说明已成功进入海外路径。

各方法对比

已知行为

• • Groq (Whisper) 自动语种检测：对中英混合语音，Whisper 会自动切换识别语言，属正常行为，无需处理。
• • 切片兜底机制：Groq 单片失败超过重试上限后，自动降级为 Apple Speech 本地识别。
• • VAD 分片：静音超过 0.6s 触发切片，单片上限 30s，超出后强制切片。

一个问题：测试后，如果不删除 -AppleLocale en_US，上线到正式环境，会有影响吗

不会影响正式环境

-AppleLocale en_US 是在 Xcode Scheme 的 LaunchAction 下的 CommandLineArguments 中配置的，这类参数只在 Xcode 调试运行时生效，有以下特点：

• • 仅影响开发调试：这是 Xcode 模拟器/设备调试启动时传入的命令行参数，用于强制 App 以海外环境运行（方便测试英文 UI）。
• • 不影响 App Store 构建：通过 Archive → 导出 IPA → 上线 App Store 的流程，这些参数完全不会包含在最终的 App 包中。
• • 用户设备上不存在：正式用户安装 App 后，会根据设备的系统语言设置来显示对应语言，不受此参数影响。

简而言之，这个参数是纯开发工具配置，上线后对用户零影响。

2026.04.20 15:49
沪·汇金路KFC