更新记录

1.2.25（2026-10-27）

• 新增 Android 系统语音引擎诊断，可通过 getCapabilities 查看已安装引擎、默认引擎、目标语言可用性及联网音色数量；新增 openTtsSettings 打开实际可用的系统语音设置，其他平台明确返回不支持。
• 修复示例页面和辅助模块使用相对引入路径的问题，统一通过 @/uni_modules/ 引用插件内文件，复制页面到其他目录时无需另行复制辅助代码。
• 修复 Android、iOS、Harmony 和小程序公开云端入口的初始化配置继承、HTTP / 自定义合成、响应字段解析与有序失败回退，保留业务参数、音色和缓存结果。
• 修复云端请求取消、准备期暂停、旧回调与停止未确认时可能影响后续任务的问题；普通任务排队并各自结算，已经开始发声的失败任务不会自动重读。
• 修复 URL 缓存跨响应字段、自定义合成器等配置复用错误；自定义 synthesize 需要显式 cache.namespace 才复用 URL，更换提供者时同时更换命名空间。
• 修复多端开始事件提前派发、分段重复和能力查询路由不一致的问题，开始事件以底层实际开始为准。
• 修复小说示例跳段、换章、迟到响应和停止失败后的状态，补齐 uni-app x 章节段落、音色选择和刷新；统一两项目的功能顺序、操作分组、禁用状态与说明。
• Android / iOS 原生代码有更新，请重新制作并安装对应自定义基座或安装包；Harmony 更新安装包，Web / 小程序重新构建。

1.2.24（2026-09-24）

• 修复 Android 调用 on/off/onTtsEvent/offTtsEvent 提示 method not found 的问题；现有事件订阅和取消调用方式无需调整，升级后需要重新制作并安装 Android 自定义基座或安装包。
• 修复 iOS 调用 stop({}) 时默认保留待播队列，以及省略 clearQueue 可能导致应用退出的问题；现在省略该字段会安全清空队列，显式设置 clearQueue: false 仍会保留队列，升级后需要重新制作并安装 iOS 自定义基座或安装包。
• 修复 iOS 云打包时播报队列、事件监听和参数转换导致的编译失败；保留原有排队、插播及按回调取消监听的调用方式，需要重新制作并安装 iOS 自定义基座或安装包。
• 修复 iOS 云打包时系统语音内部初始化方法与系统类方法重名导致 Swift 编译失败的问题；无需修改现有 API 调用，升级后需要重新编译 iOS 原生部分并更新自定义基座或安装包。
• 修复 iOS、Web 连续提交时丢失任务回调，以及长时间播报、暂停恢复后超时判断不准确的问题；普通请求按顺序播报，显式设置 interrupt: true 才插播。
• 修复 Harmony 和小程序的公开 API 入口，以及停止后旧音频监听、迟到合成响应影响后续播报的问题；初始化的云端配置可继续复用。
• 修复云端合成一直等待、恢复播报后失去超时保护和缓存条数限制失效的问题；无需修改现有调用代码。
• 修复 Harmony 构建安装包时严格类型校验失败的问题；自定义云合成继续支持直接返回音频地址或结果对象，也支持异步返回。
• 修复播报结束事件中调用 stop 并立即提交下一条时，新任务可能等待的问题。
• iOS 升级后需要重新编译原生部分并更新自定义基座或安装包；Web 和小程序重新构建发布，Harmony 更新安装包。
• 修复 Android 系统语音连续提交时互相打断、部分播报无法收到完成回调的问题；普通播报按顺序执行，显式设置 interrupt: true 时才打断当前任务。
• 修复系统语音引擎长时间无响应后任务一直等待的问题；超时会返回失败，后续任务尝试重新初始化引擎，已失败的原文不会自动重复播放。
• 修复暂停、停止和旧任务迟到回调可能影响后续播报的问题；保留当前分段恢复、队列清理和任务优先级控制。
• 失败详情补充超时阶段和系统提供的原始错误码，便于排查无声；无需修改现有初始化和播报调用代码。
• 升级后需要重新编译 Android 原生部分，并重新制作、安装自定义基座或正式安装包。

1.2.23（2026-09-21）

• 新增紧凑的系统 TTS、云端 TTS、离线 TTS 三 Tab 综合示例，常用操作直接展示，更多设置和运行记录按需展开；保留独立离线页和小说听书入口。
• 修复 Android 离线播报尚未结束就返回完成、停止操作可能未生效的问题；播完后再触发成功，合成或播放失败会返回错误，暂停后不会自动播放后续分段。
• 修复完成回调中开始下一条播报、或停止后的旧回退结果造成新任务丢失的问题；停止会返回实际执行结果，未成功时可重试。
• 修复示例停止或切换模式后，迟到的云端响应和操作结果仍继续播放或覆盖当前状态的问题；停止失败后可以重试。
• 优化中文与西班牙语离线模型文件检查、平台可用提示和首次使用说明；初始化示例改为成功后再播报。
• 升级后无需修改现有 API 调用；App 项目需要重新编译原生部分并更新安装包或自定义基座，再使用更新后的示例。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-smart-tts

介绍

lizhao-smart-tts 是面向 uni-app / uni-app x 的文字转语音（TTS）插件。传入一段文字，插件就能把它读出来，适合订单提醒、消息通知、导航提示、课程朗读、小说听书等场景。

插件提供三条播报路线：直接使用手机或浏览器自带的系统 TTS、在 Android 设备上加载离线模型、调用云端服务生成高质量语音。第一次接入建议先用系统 TTS，确认基本播报正常后，再根据业务需要增加离线或云端能力。

功能特色

适合哪些场景

下载与导入

保留完整插件目录，从插件根入口导入；按使用宿主注册下方示例页面。文中含类型声明的脚本片段适用于 uni-app x / UTS；<script setup> 完整页需 Vue 3。普通 uni-app 使用无类型的 JavaScript 写法，Options API 示例兼容 Vue 2 / Vue 3。

将插件导入项目的 uni_modules/lizhao-smart-tts，只从插件根目录导入 API，不直接导入平台实现。Android、iOS 或 Web 可先用下面的系统 TTS 示例：

import { initTTS, speak } from '@/uni_modules/lizhao-smart-tts'

// 将此函数绑定到“开始朗读”按钮；Web 首次播报由点击触发。
function startReading() {
  initTTS({
    lang: 'zh-CN',
    fallbackChain: ['native'],
    success() {
      // 必须等待初始化成功，再提交第一句。
      speak({
        text: '订单已完成，请及时处理',
        success(res) { console.log('播报完成', res.taskId) },
        fail(err) { console.log('播报失败', err.errCode, err.errMsg) }
      })
    },
    fail(err) { console.log('初始化失败', err.errCode, err.errMsg) }
  })
}

调用顺序始终是：先执行 initTTS()，成功后再执行 speak()。如果页面会连续播报多句话，只需要初始化一次。

完整示例

• 示例页面配置与使用步骤（uni_modules/lizhao-smart-tts/example/readme.md）
• uni-app 系统 / 云端 / 离线三 Tab 示例（uni_modules/lizhao-smart-tts/example/uniapp/tts.vue）
• uni-app Android 离线 TTS 示例（uni_modules/lizhao-smart-tts/example/uniapp/ttsOffline.vue）
• uni-app 小说听书示例（uni_modules/lizhao-smart-tts/example/uniapp/ttsNovel.vue）
• uni-app x 三 Tab 综合示例（uni_modules/lizhao-smart-tts/example/uniappx/index.uvue）

从基础到进阶：按业务模块使用

模块一：系统 TTS

系统 TTS 的最小示例见“快速开始”。它使用设备已有的语音引擎；部分音色需要先下载语言包或联网，不能仅凭“系统 TTS”判断是否完全离线。

初始化成功后提交短句；成功表示本次播报完成，失败保留真实错误。

speak({
  text: '订单已完成',
  timeout: 30000,
  success(res) { console.log('播报完成', res.taskId) },
  fail(err) { console.error(err.errCode, err.errMsg, err.details) }
})

任务排队、暂停计时及停止失败规则见本页的“系统播报任务与超时边界”。

模块二：查询并选择系统音色

音色名称由操作系统或浏览器决定。先调用 getVoices() 获取真实列表，再把其中的 name 传给 voiceName。

import { getVoices, speak } from '@/uni_modules/lizhao-smart-tts'

getVoices({
  success(voices) {
    console.log('当前设备可用音色', voices)

    if (voices.length === 0) {
      return
    }

    speak({
      text: '这是一段指定音色的播报',
      lang: voices[0].lang,
      voiceName: voices[0].name
    })
  }
})

Web 用户需要区分两个参数：

Web 指定音色示例：

speak({
  text: '你好，这是普通话测试',
  lang: 'cmn',
  voiceName: 'Chinese (Mandarin)+Belinda'
})

如果指定名称不存在，插件会按 lang 选择同语言音色；目标语言完全不可用时返回错误，不会偷偷换成其他语言。浏览器只能提供音色名称、语言和是否为本地音色等信息，不能判断哪一个声音最自然，最终仍应在目标电脑上逐个试听。

音色名称不会改变底层语音引擎的发音能力；Linux 上切换同一引擎的音色变体也不保证普通话更自然。

选择普通话音色时，可以按以下顺序处理：

1. 优先筛选 zh-CN 或 cmn，它们表示普通话。
2. 优先试听名称中明确写有普通话或中文语音引擎的音色。
3. 确认满意后，保存完整的 name 并传给 voiceName。
4. 如果不同设备必须保持相同声音，应改用云端 TTS。

模块三：暂停、继续、停止和监听进度

import {
  pause,
  resume,
  stop,
  onTtsEvent,
  offTtsEvent
} from '@/uni_modules/lizhao-smart-tts'

const handleProgress = (event) => {
  console.log('播报进度', event.taskId, event.progress)
}

onTtsEvent('progress', handleProgress)

// 分别绑定三个按钮，按需调用，不连续执行。
function pauseReading() { pause({}) }
function resumeReading() { resume({}) }
function stopReading() { stop({ clearQueue: true }) }

// 在页面离开时调用，使用原函数引用取消监听。
function disposeReading() {
  stop({ clearQueue: true })
  offTtsEvent('progress', handleProgress)
}

Android 系统 TTS 没有真正的暂停接口。插件采用 restart-segment 降级方式：暂停后继续时，会从当前分段开头重新读。

多次调用 speak() 时，任务会进入队列。常用控制规则如下：

模块四：直接使用内置播报按钮

不想自己写按钮和状态文字时，uni-app Vue 页面可以直接使用内置组件：

<template>
  <lizhao-smart-tts
    text="欢迎使用智能语音播报"
    button-text="开始播报"
    :options="ttsOptions"
    :disabled="false"
    @ready="handleReady"
    @success="handleSuccess"
    @error="handleError"
  />
</template>

<script>
export default {
  data() {
    return {
      ttsOptions: {
        lang: 'zh-CN',
        fallbackChain: ['native', 'cloud']
      }
    }
  },
  methods: {
    handleReady(res) {
      console.log('TTS 已就绪', res)
    },
    handleSuccess(res) {
      console.log('播报完成', res)
    },
    handleError(err) {
      console.log('播报失败', err)
    }
  }
}
</script>

组件本身提供按钮和状态展示；需要完全自定义界面，或使用 uni-app x 页面时，直接调用上面的纯 API。

模块五：Android 完全离线播报

离线 TTS 适合设备不能联网、但仍必须稳定播报的场景。默认插件包不包含 Sherpa-ONNX AAR、SO 和大模型，因此只使用系统 TTS 或云端 TTS 的项目可以跳过整个模块。

离线能力包含两类资源：

如果需要控制安装包体积，推荐采用“只把 arm64-v8a 运行库放进基座，模型在运行后下载”的方式。

方式一：模型随基座打包

下载并放置资源：

以下 AAR 和模型目录需由使用者自行下载、解压并准备，不是插件内置交付文件。

中文模型初始化示例：

import { initTTS, speak } from '@/uni_modules/lizhao-smart-tts'

initTTS({
  lang: 'zh-CN',
  fallbackChain: ['offline-ai'],
  offline: {
    engine: 'sherpa-onnx',
    modelDir: 'sherpa-onnx/zh-pro',
    speakerId: 0
  },
  success() {
    speak({
      text: '这是一段完全离线的语音播报',
      success() { console.log('离线播报完成') },
      fail(err) { console.log('离线播报失败', err.errCode, err.errMsg) }
    })
  },
  fail(err) { console.log('离线初始化失败', err.errCode, err.errMsg) }
})

严格离线使用 ['offline-ai']；需要系统兜底时可改为 ['offline-ai', 'native']，但系统音色可能依赖网络。

模型会增加自定义基座体积。中文模型约 180MB 时，不适合有 60MB 左右包体限制的项目。

方式二：模型在 App 运行后下载

制作基座前，只把目标设备需要的原生运行库放入：

uni_modules/lizhao-smart-tts/utssdk/app-android/libs/sherpa-onnx-1.13.2-arm64-v8a.aar（用户准备，非随插件交付）

App 运行后，把模型压缩包下载并解压到 App 私有目录，例如：

_doc/lizhao-smart-tts/sherpa-onnx/zh-pro

模型目录至少需要包含：

model.onnx 或其他 .onnx 文件
tokens.txt
lexicon.txt 或 espeak-ng-data/
模型自带的 dict/、phone.fst、date.fst、number.fst 等文件

把 _doc 路径转换成 Android 绝对路径后，传给 offline.modelPath：

import { initTTS, speak } from '@/uni_modules/lizhao-smart-tts'

// 请替换为下载和解压工具返回的真实 Android 绝对目录。
const modelPath = '/data/user/0/你的包名/files/sherpa-onnx/zh-pro'

initTTS({
  lang: 'zh-CN',
  fallbackChain: ['offline-ai'],
  offline: {
    engine: 'sherpa-onnx',
    modelPath,
    speakerId: 0
  },
  success(res) {
    console.log('离线模型加载成功', res.capabilities.details)
    speak({
      text: '模型下载完成后，不联网也可以播报',
      success() { console.log('离线播报完成') },
      fail(err) { console.log('离线播报失败', err.errCode, err.errMsg) }
    })
  },
  fail(err) {
    console.log('离线模型加载失败', err.errCode, err.errMsg, err.details)
  }
})

uni-app App 页面可以使用 plus.io.convertLocalFileSystemURL() 转换 _doc 路径；uni-app x 请使用下载和解压工具返回的真实绝对路径。modelPath 必须指向已解压的模型目录，不能指向压缩包。示例的“模型目录说明”只解释文件要求，不会下载模型。

放入或更换 AAR/SO 后，必须重新制作并安装 Android 自定义基座；只更换运行后下载的模型，而且当前基座已经包含正确的 AAR/SO 时，不需要重新制作基座。

模块六：使用云端 TTS 获得固定音色

云端 TTS 会把文字发送到你的服务端，服务端合成音频并返回一个可播放的 audioUrl。它适合固定音色、高音质、多端一致、Harmony、小程序和小说听书。

云端接口默认返回以下结构：

{
  "audioUrl": "https://example.com/audio/demo.wav",
  "cacheHit": false,
  "durationMs": 1200,
  "provider": "custom",
  "voice": "zh-CN-XiaoxiaoNeural"
}

如果服务返回的音频地址字段不是 audioUrl，使用 cloud.responseField 指定真实字段名。

import { initTTS, speak } from '@/uni_modules/lizhao-smart-tts'

initTTS({
  lang: 'zh-CN',
  fallbackChain: ['cloud', 'native'],
  cloudOnly: true,
  cloud: {
    provider: 'custom',
    endpoint: 'https://你的域名/v1/tts',
    method: 'POST',
    responseField: 'audioUrl',
    cache: {
      enabled: true,
      namespace: 'tts-demo',
      maxAgeMs: 86400000,
      maxItems: 100
    }
  },
  success() {
    speak({
      text: '这是一段云端 TTS 测试',
      voiceName: 'zh-CN-XiaoxiaoNeural',
      cacheKey: 'demo:cloud:001',
      cloudOnly: true,
      success() { console.log('云端播报完成') },
      fail(err) { console.log('云端播报失败', err.errCode, err.errMsg) }
    })
  },
  fail(err) { console.log('云端初始化失败', err.errCode, err.errMsg) }
})

cloudOnly: true 表示本次只测试云端路线，避免系统 TTS 初始化结果影响排查。生产项目也可以移除它，并使用 fallbackChain: ['cloud', 'native'] 在云端失败时回退到系统 TTS。

密钥和 Token 必须保存在服务端，不能写在 App、Web 页面或插件配置中。

模块七：小说、课程和长文本播报

长文本建议先按章节或自然段拆分。每段使用稳定的 cacheKey，服务端就可以复用已经生成的音频；voiceRole、emotion 和 metadata 可用于区分旁白、角色或业务场景。

speak({
  text: '雨声落在旧城的青石路上。',
  scene: 'novel',
  cacheKey: 'book-100:chapter-1:paragraph-1',
  voiceRole: 'narrator',
  emotion: 'calm',
  metadata: {
    bookId: 'book-100',
    chapterId: 'chapter-1'
  },
  fallbackChain: ['cloud', 'native']
})

小说听书通常还需要在业务页面保存当前章节和段落位置。插件负责播报、队列和事件，章节列表、断点记录以及“上一段/下一段”界面由业务页面管理。完整实现可参考 小说听书示例（uni_modules/lizhao-smart-tts/example/uniapp/ttsNovel.vue）。

模块八：选择一种云端服务

插件不绑定某一家云服务，只要求服务端最终返回可播放的音频地址。

Edge TTS uniCloud 测试模板

模板位置：

uni_modules/lizhao-smart-tts/templates/uniCloud/cloudfunctions/edge-tts

使用步骤：

1. 在 HBuilderX 中为项目创建或绑定 uniCloud 云空间。
2. 把模板复制到项目根目录的 uniCloud/cloudfunctions/edge-tts。
3. 在项目根 uniCloud 视图中找到 edge-tts，安装依赖并上传部署。
4. 在 uniCloud 控制台开启云函数 URL 化。
5. 把生成的 HTTPS 地址填入 cloud.endpoint。

插件提供的默认地址只用于测试，不应当作自己的长期生产服务：

https://env-00jxu7ha8amh.dev-hz.cloudbasefunction.cn/tts

CosyVoice Docker 服务

服务模板位置：

uni_modules/lizhao-smart-tts/static/server/cosyvoice-cloud-tts

启动示例（PowerShell）：

cd uni_modules/lizhao-smart-tts/static/server/cosyvoice-cloud-tts
copy .env.example .env
powershell -ExecutionPolicy Bypass -File .\build-image.ps1
docker compose up -d

常用接口：

真机不能通过 127.0.0.1 访问电脑上的服务。局域网测试时应改成电脑局域网 IP；正式环境应配置 HTTPS 域名，并确保返回的 audioUrl 能被 App 或小程序直接访问。

第三方商业 TTS 代理

服务端代理模板位置：

uni_modules/lizhao-smart-tts/static/server/commercial-tts-proxy

把云厂商密钥保存在代理服务中，再让业务统一请求自己的 cloud.endpoint。这样更换云厂商时，App 端调用方式不需要跟着改变。

模块九：检查 Android 引擎和语音设置

设备没有中文音色、首次使用系统引擎，或需要区分本地音色与联网音色时，先按“快速开始”初始化系统 TTS，再读取能力信息：

import { getCapabilities } from '@/uni_modules/lizhao-smart-tts'

getCapabilities({
  success(res) {
    console.log('当前路线', res.adapter)
    console.log('设备引擎和语言诊断', res.details)
  },
  fail(err) { console.log('查询失败', err.errCode, err.errMsg) }
})

Android 系统路线的 details.engines 返回已安装引擎的 name / label，defaultEngine 返回默认引擎名称。diagnosticsReady 表示能否查询当前引擎；languageAvailable 为 null 表示未知，不能当作已支持。voiceCount / networkVoiceCount / localVoiceCount 分别表示全部、需要联网和本地音色数量，未知时为 null。音色数量不表示当前网络或语言包一定可用。

将下面的函数绑定到“系统语音设置”按钮，供用户切换引擎或下载语言包；返回示例页后重新初始化并刷新音色：

import { openTtsSettings } from '@/uni_modules/lizhao-smart-tts'

function openVoiceSettings() {
  openTtsSettings({
    success(res) { console.log('已打开设置', res.opened) },
    fail(err) { console.log('请在手机设置中查找文字转语音', err.errCode) }
  })
}

只有实际打开设置才返回 opened: true；设备没有可用入口，或在其他平台调用时返回 9011004。打开设置不代表引擎或语言包已经配置完成。

API 用途速查

详细参数、默认值、回调与返回字段见本节下方的参数表和返回值说明。

参数与回调

通用回调

异步 API 都支持以下回调：

speak.success 表示整条播报任务已经完成，不只是进入了队列。发生失败时，建议同时记录 errCode、errMsg 和 details。

initTTS(options)

默认路线为：Android / iOS 使用系统 TTS，Web 使用浏览器系统 TTS，Harmony 和小程序使用云端音频。App 需要失败后尝试云端时，显式配置 fallbackChain: ['native', 'cloud'] 和 cloud。尚未开始发声才尝试下一路线，已经开始的任务失败不会自动整句重读。Web 当前不会根据 cloud.endpoint 自动切换到云端。

speak(options)

离线配置 SmartTtsOfflineOptions

云端配置 SmartTtsCloudOptions

cloud.synthesize 可以同步或通过 Promise 返回音频地址、{ audioUrl, cacheHit, durationMs, provider, voice }；异常会进入 fail 回调。scene / cacheKey / voiceRole / emotion / metadata 以及语言、音色、语速等参数一起传入合成请求。

HTTP 合成默认缓存返回的音频地址，默认有效期 24 小时、最多 100 条；cache.enabled: false 关闭缓存，maxAgeMs / maxItems 调整时限和数量。这是内存 URL 缓存，不下载音频文件，过期的签名地址应配置更短有效期。

自定义 synthesize 默认不复用 URL；需要缓存时显式设置 cache: { enabled: true, namespace: '业务与服务版本' }，更换合成提供者或函数行为时同时更换 namespace。正文、音色、角色、情绪、响应字段和请求参数仍会参与缓存隔离。

内置组件属性

内置组件事件

常用配置

更多可选项见后面的 API 参数表。

选择接入方式

主要返回值

播报结果 SpeakResult

运行能力 SmartTtsCapabilities

运行事件

取消监听时，必须传入注册时的同一个回调函数。

错误码说明

错误主题 errSubject 为 lizhao-smart-tts；失败时保留 errCode 和 errMsg，按下表处理。

注意事项

支持平台

uni-app 综合示例的 Web 云端 Tab 由页面请求服务并播放音频；这不代表插件 Web API 会自动切换云端。uni-app x 示例的 Web 云端操作会提示平台限制。

• iOS 请使用 HBuilderX 5.11 或以上版本；Android / iOS 使用包含当前插件原生代码的自定义基座或安装包。
• 系统音色由设备决定，插件不能保证所有手机和电脑拥有相同声音。
• Web 首次发声最好由用户点击触发，避免浏览器自动播放策略拦截。
• 云端密钥、Token 和生产配置只能保存在服务端。
• 长文本应合理分段，并在页面销毁时取消事件监听。
• 只使用系统 TTS 或云端 TTS 时，不要额外加入 Sherpa-ONNX 大资源。
• 离线模型代码授权与模型授权需要分别确认。
• 当前离线模型路线仅支持 Android；iOS 请使用系统或云端 TTS。

常见问题

第一次接入应该选择哪一种方式

先使用系统 TTS，也就是 fallbackChain: ['native']。它不需要服务器、模型或额外依赖。确认初始化和播报都成功后，再根据业务需要增加离线或云端路线。

Android 首次播报为什么弹出系统声明或条款

这是手机系统文字转语音引擎的行为，不是插件弹窗。同意系统条款后即可继续使用。不同品牌设备的界面可能不同。

Android 日志提示 textToSpeech init failed

通常是设备没有安装、启用或正确设置系统 TTS 引擎。进入系统的“文字转语音输出”设置，安装并选择可用引擎后重试。业务上也可以配置云端 TTS 作为回退路线。

Android 暂停后为什么从当前段落开头继续

Android 系统 TTS 没有真正的暂停接口。插件会停止当前分段，并在继续时从该分段开头重新播报。这是 restart-segment 的正常表现。

Web 指定音色为什么没有生效

先用 getVoices() 获取当前浏览器的音色列表，再把返回项的 name 传给 voiceName。不要把浏览器音色名称传给 voiceRole，后者只用于云端业务角色。

Ubuntu 音色列表中的 cmn / yue / hak 是什么

cmn 表示普通话，yue 表示粤语，hak 表示客家话。插件会把普通话 zh-* 尝试匹配到 cmn，把 zh-HK 尝试匹配到 yue。

Windows 是女声，Ubuntu 为什么变成男声

Web 音色由操作系统、浏览器和已经安装的语音引擎共同决定。插件会优先匹配同语言以及名称中带 Xiaoxiao / Jenny / Belinda / female / 女声 等标记的音色，但系统没有对应女声时只能使用可用音色。要求不同电脑声音一致时，应使用云端 TTS。

Ubuntu 把 v2v 读成“V 二 V”怎么办

Web 路线会把独立出现的 v2v 按 V to V 播报，不会替换普通数字 2。如果文本不是独立的 v2v，建议在业务侧按期望读法提供展示文本和播报文本。

能看到 Google 普通话音色，为什么一直没有声音

localService: false 表示该音色可能依赖浏览器在线语音服务。音色出现在列表中，不代表服务在当前网络一定可用。

排查顺序：

1. 在站点设置中允许“声音”，它不是麦克风权限。
2. 让用户第一次点击按钮时直接触发播报，不要在页面加载或无用户手势的定时器中自动播放。
3. 确认标签页、系统音量和音频输出设备没有静音。
4. 使用最新版 Chrome 或 Edge 测试。
5. 打印完整失败对象和 [lizhao-smart-tts][Web] 日志。

可以临时缩短超时时间，快速得到诊断结果：

speak({
  text: '你好，这是普通话测试',
  lang: 'zh-CN',
  voiceName: 'Google 普通话（中国大陆）',
  timeout: 10000,
  fail(err) {
    console.error('TTS 完整错误', err)
    console.error('TTS 诊断详情', err.details)
  }
})

details.browserError 为 voice-unavailable 表示目标语言音色不可用；speech-timeout 且 phase 为 waiting-start 表示浏览器没有开始播放；waiting-end 表示已经开始但没有在超时时间内结束。插件会取消静默挂起的任务，并触发 fail 和 complete。

发布到 Nginx 后还需要麦克风权限吗

不需要。浏览器系统 TTS 使用 window.speechSynthesis，不是录音功能。需要检查的是站点声音播放权限、用户手势和当前设备的浏览器音色。

购买插件后是否还需要云函数或服务器

只使用系统 TTS 时不需要。插件授权不包含 uniCloud 云空间、第三方 TTS 账号或持续运行的合成服务。只有固定音色、高音质、Harmony、小程序或跨设备一致等场景需要另外部署云端服务。

云端服务不限于 uniCloud，也可以使用自建 CosyVoice、商业 TTS 代理或其他能够返回 HTTPS audioUrl 的服务。

配置 cloud.endpoint 后，Web 会自动回退云端吗

不会。当前 Web 入口只使用浏览器 SpeechSynthesis，不会读取 cloud.endpoint。Web 需要云端声音时，应由业务层请求合成接口，拿到 HTTPS audioUrl 后使用 Web 音频播放器播放，并处理同源代理或 CORS。

Harmony 为什么查询不到系统音色

Harmony 当前走云端音频路线，不宣称支持系统原生 TTS 音色。请配置可访问的 cloud.endpoint，并确保返回的音频地址能在目标设备播放。

使用 offline-ai 为什么返回 9011006

默认插件包没有携带大体积离线模型。请确认已经准备 AAR/SO，并检查 modelDir 或 modelPath 指向的目录是否包含 .onnx、tokens.txt 以及 lexicon.txt 或 espeak-ng-data/。

下载模型后为什么仍然不能离线播报

模型文件可以在 App 运行后下载，AAR/SO 不可以。AAR/SO 必须在制作 Android 自定义基座之前放入插件目录，并参与原生联编。只更新 wgt 或 appResource 无法把原生运行库补进已有基座。

加入离线资源后是否需要重新制作 Android 自定义基座

加入或更换 AAR/SO 时必须重新制作并安装 Android 自定义基座。当前基座已经包含正确的 AAR/SO，仅替换运行后下载的模型文件时不需要重新制作。

云端接口已经返回成功，为什么还是播放失败

请确认返回体中的字段名与 cloud.responseField 一致，并且 audioUrl 是目标 App、小程序或浏览器可以直接访问的完整地址。真机不能访问电脑的 127.0.0.1；小程序还需要配置合法域名；正式环境建议使用 HTTPS。

Edge TTS 云函数出现 Unexpected server response: 403

通常是 Edge 在线接口握手参数发生变化，或者部署的云函数模板较旧。更新插件中的模板并重新上传部署，然后再次测试云函数日志和返回结果。

如何查看当前到底用了哪一种播报路线

调用 getCapabilities() 查看当前 adapter 和支持矩阵；播报成功后也可以查看 SpeakResult.adapter。例如 native-android 表示 Android 系统 TTS，offline-ai-android 表示 Android 离线模型，cloud-audio-android 表示 Android 云端音频路线。

系统播报任务与超时边界

连续提醒只需初始化成功一次，再按原来的 speak({ text, success, fail }) 方式提交。Android、iOS、Web、Harmony 和小程序的普通请求会排队，只有 interrupt: true 才会打断当前播报。

如果系统引擎长时间没有开始或结束播报，当前任务会通过 fail 和 complete 返回错误；后续任务会尝试使用重新建立的引擎。已失败的原文不会自动重复播放。timeout 默认每个阶段 30000 毫秒，长句或慢语速可以调大，暂停期间不计时。

iOS 使用系统完成事件判断播完，Web 同样保留暂停后的剩余等待时间。Harmony 和小程序会拦截停止后的旧合成结果；云端合成没有返回时也会报超时。如果引擎拒绝停止，后续任务会明确失败，需等待旧任务结束或再次成功调用 stop 后重试，避免声音重叠。

排查无声时，请保留成功和失败日志，并在失败日志中输出 err.details。Android 的 phase 用于区分初始化、等待开始和等待结束等阶段，nativeErrorCode 在系统提供时保留原始错误码。若播报正常完成但听不到声音，还需检查媒体音量、蓝牙输出和系统 TTS 试听。

作者系列 UTS 插件

以下为作者已上架的 UTS 插件，详情见各市场页面或作者主页。