鲸海语记（JingNote）App 模拟海外场景 ASR 测试指南
type
status
date
slug
summary
tags
category
icon
password
wechat_gate
背景
SpeechNote 根据设备地区（
Locale.current.regionCode）自动选择 ASR 引擎：地区 | 默认引擎 | 备用引擎 |
中国大陆（CN） | 腾讯云 QCloud / SenseVoice | SenseVoice（限额超出时） |
海外（非 CN） | Groq Whisper | Apple Speech（本地兜底） |
在中国大陆开发环境中，默认走国内路径。以下方法可强制触发海外（Groq）路径，用于功能验证和回归测试。
方法一：修改设备地区（推荐，适用真机/模拟器）
步骤：
- 打开 设置 → 通用 → 语言与地区 → 地区
- 将「中国大陆」改为「美国」（或任意非 CN 地区）
- 运行 app，此时
Locale.current.regionCode返回"US"，自动走 Groq 路径
- 测试完成后改回「中国大陆」
适用场景： 完整 E2E 测试，包括真机录音上传全链路。
注意： 修改地区会影响系统语言排序，建议测试后及时还原。
方法二：Xcode Scheme 启动参数（推荐，不影响设备日常使用）
步骤：
- Xcode → Product → Scheme → Edit Scheme...
- 选择左侧 Run → Debug
- 点击顶部 Arguments 标签
- 在 Arguments Passed On Launch 区域点击
+
- 输入
AppleLocale en_US（注意有 前缀）
- 确保勾选该条目后关闭
适用场景： 真机和模拟器均有效，只在从 Xcode 启动时生效，不影响设备日常使用。
常见错误： 不要将AppleLocale放在 Environment Variables 区域，该方式仅对模拟器生效，真机无效。
方法三：代码级 Debug 开关（适用于自动化测试）
在
ViewController.swift 的 resolveRecognitionStartPlan() 方法中临时添加：在测试代码或启动参数中设置：
适用场景： UI 自动化测试、CI 流水线中需要覆盖海外路径的测试用例。
注意： 此修改不应提交到主分支，仅用于本地测试分支。
验证方法
启动 app 后检查 Xcode 控制台，确认以下日志出现：
以及录音结束后：
如果看到
Non-CN:preferred=groq，说明已成功进入海外路径。各方法对比
方法 | 真机有效 | 模拟器有效 | 需改代码 | 影响设备系统 |
修改设备地区 | ✅ | ✅ | 否 | 是（临时） |
Xcode 启动参数 | ✅ | ✅ | 否 | 否 |
代码 Debug 开关 | ✅ | ✅ | 是 | 否 |
已知行为
- 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