常见问题

为什么不能在 Expo Go 里跑？

Expo Go 内置的原生模块集合是固定的，无法加载任意原生代码。本 SDK 依赖 ONNX Runtime，而它是原生的。你需要 Development Build（npx expo run:ios / npx expo run:android）。没有任何配置能让 Expo Go 跑起来。

安装时遇到 401 或 403

你的 npm token 缺失、过期，或未被授权访问 @optimalai scope。按顺序排查：

1. 你的 npm 用户名已在 sdk-beta-readers 团队中。
2. 你的 token 是包含 @optimalai scope 的细粒度只读 token。
3. NPM_TOKEN 已在 shell 中导出，或在 CI / EAS 中配置为 secret。
4. .npmrc 里是 ${NPM_TOKEN} —— 不是写死的 token，也不是过期的那个。

CLI 报 "base URL not configured"

生产模型 CDN 的 URL 由 OptimalAI 在发布时注入，npm 包里不含任何占位域名。在该 URL 上线之前，请显式传入：

npx @optimalai/model-tools@beta add kokoro-82m-v1.1-zh-int8 \
  --base-url https://your-staging-host

或设置 OPTIMALAI_MODELS_BASE_URL。

load() 抛 MODEL_NOT_FOUND

这通常是 Metro 或资产解析的问题，而不是模型真的不见了：

• 你用 withOptimalAI 包裹 Metro 配置了吗？没有它，.onnx、.bin、.txt 不会被注册为资产。
• 干净 checkout 之后重新跑过模型安装器吗？模型文件是构建产物，不会提交进 Git。
• 改动原生依赖之后重新构建过 Development Build 吗？
• 生成的 optimalai-models.ts 在吗，被 import 了吗？

load() 抛 MODEL_CORRUPT

资产解析到了，但字节长度或哈希校验失败。磁盘上的文件与 manifest 描述的不一致 —— 下载被截断，或目录被删了一部分。删除模型目录后重装：

npx @optimalai/model-tools@beta add kokoro-82m-v1.1-zh-int8

CLI 是故意不覆盖校验失败的目录的，所以你需要自己先清掉它。

遇到 BUSY

那个 client 上已有加载或合成在进行。SDK 一次只允许一个。await 掉进行中的调用， 然后重试。要并行就得用多个 client —— 每个都会独立加载模型并占用各自的内存。

英文文本报 INVALID_TEXT

该单词不在内置词典中，而 Beta 版没有 eSpeak 回退。这是刻意设计。请尽早用你的 真实内容去测词典覆盖，并在合成前清洗用户输入。见错误处理。

能在不重载模型的前提下换音色吗？

可以。给 synthesizeToFile 传一个不同的 voiceId 即可。ONNX session 保持加载 状态，只有 style embedding 会变。见切换音色与语速。

WAV 存到哪里？谁来删？

默认落在应用的缓存目录下，文件名自动生成。如果想指定位置，传 outputPath。 无论哪种方式，文件都属于你 —— SDK 从不删除它。如果会反复合成，请自行清理 目录。

传入已存在的 outputPath 会怎样？

合成会以 OUTPUT_EXISTS 失败。请先删除文件，或让 SDK 生成新名字。同一个路径传 两次不会静默覆盖。

有流式接口吗？

没有。本 Beta 没有，近期路线图里也没有。

能用在裸 React Native（不用 Expo）上吗？

不能。本 Beta 明确针对 Expo SDK 57。裸 React Native 支持不在本次发布范围内。

怎么反馈问题？

请附上错误 code、TtsError.details 内容、设备与系统版本、以及 model id。 这些信息通常足以复现。