更新记录

1.2.22（2026-09-06）

• 修复 uni-app x Android 示例的云端响应解析：统一读取 response.data，并兼容 JSON 文本、嵌套 data 和 URL 别名。

1.2.21（2026-08-13）

• Web 增加统一中文诊断日志，输出初始化、请求参数、实际音色、localService、网络与页面状态、speechSynthesis 状态及 onstart / onend / onerror 生命周期；日志不打印播报原文。
• 修复 Ubuntu 浏览器能够枚举 zh-CN / Google 普通话，但语音后端静默挂起时 success / fail / complete 均不触发的问题；按 timeout 分别监控等待开始和等待结束阶段，超时返回 details.browserError = "speech-timeout" 与 details.phase，并取消挂起任务。
• Web start 事件和失败详情补充实际音色是否为本地服务等诊断字段；说明 localService: false 的在线音色出现在列表中不代表当前电脑一定能够连接合成服务。

1.2.20（2026-08-13）

• 修复 Web 端云端女声音色名在 Ubuntu 不存在时丢失性别偏好的问题；Xiaoxiao / Jenny / Belinda / female / 女声 会优先匹配同语言女性音色，Yunxi / Guy / male / 男声 会优先匹配男性音色，无匹配时再回退基础同语言音色。
• Web 播报会把独立技术缩写 v2v 归一化为 V to V，避免 Ubuntu 普通话引擎读成“V 二 V”；不全局替换数字 2，不影响普通数字、日期、数量和型号。
• Web start 事件增加 selectedVoiceName / selectedVoiceLang，便于确认最终选中的浏览器音色。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-smart-tts

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

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

这个插件能解决什么问题

• 把普通文字直接读出来，不需要自己处理原生语音 API。
• 查询并选择设备上已有的中文、英文等系统音色。
• 暂停、继续、停止播报，并管理多条播报任务。
• 在 Android 无网络环境中使用 Sherpa-ONNX 模型播报。
• 通过 Edge TTS、CosyVoice 或商业 TTS 服务获得固定音色和更自然的声音。
• 为小说、课程等长文本分段播报，并传递缓存键、角色和情绪信息。
• 同时提供纯 API 和 uni-app 内置按钮组件两种接入方式。

支持平台

先选择接入方式

不确定时直接选择系统 TTS。它不需要模型和服务器，最适合先验证插件是否接入成功。

下载与导入

把插件放入项目的 uni_modules/lizhao-smart-tts 目录，然后只从插件根目录导入：

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

不要直接导入 utssdk/index.uts 或某个平台目录中的文件。

按业务模块使用

下面从最简单的系统播报开始，再逐步介绍音色、播放控制、离线模型和云端服务。只使用其中一个模块也可以，不需要把所有能力都配置一遍。

模块一：用系统 TTS 播报一句话

系统 TTS 直接使用设备已经安装的语音引擎。Android 使用系统 TextToSpeech，iOS 使用 AVSpeechSynthesizer，Web 使用浏览器 SpeechSynthesis。

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

// 页面进入后先初始化一次。
initTTS({
  lang: 'zh-CN',
  fallbackChain: ['native'],
  success(res) {
    console.log('TTS 初始化成功', res.capabilities.adapter)
  },
  fail(err) {
    console.log('TTS 初始化失败', err.errCode, err.errMsg)
  }
})

// 初始化成功后，可以多次调用 speak。
speak({
  text: '订单已完成，请及时处理',
  rate: 1.0,
  pitch: 1.0,
  volume: 1.0,
  success(res) {
    console.log('播报完成', res.taskId)
  },
  fail(err) {
    console.log('播报失败', err.errCode, err.errMsg)
  },
  complete(res) {
    console.log('本次播报已结束', res)
  }
})

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

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

音色名称由操作系统或浏览器决定。先调用 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 选择同语言音色；目标语言完全不可用时返回错误，不会偷偷换成其他语言。浏览器只能提供音色名称、语言和是否为本地音色等信息，不能判断哪一个声音最自然，最终仍应在目标电脑上逐个试听。

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

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)

pause({})
resume({})

// 停止当前任务，并清空还没有开始的任务。
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 运行库放进基座，模型在运行后下载”的方式。

方式一：模型随基座打包

下载并放置资源：

中文模型初始化示例：

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

initTTS({
  lang: 'zh-CN',
  fallbackChain: ['offline-ai', 'native'],
  offline: {
    engine: 'sherpa-onnx',
    modelDir: 'sherpa-onnx/zh-pro',
    speakerId: 0
  }
})

speak({
  text: '这是一段完全离线的语音播报'
})

模型会增加自定义基座体积。中文模型约 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 绝对路径后，传给 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', 'native'],
  offline: {
    engine: 'sherpa-onnx',
    modelPath,
    speakerId: 0
  },
  success(res) {
    console.log('离线模型加载成功', res.capabilities.details)
  },
  fail(err) {
    console.log('离线模型加载失败', err.errCode, err.errMsg, err.details)
  }
})

speak({
  text: '模型下载完成后，不联网也可以播报'
})

可以使用 plus.io.convertLocalFileSystemURL() 把 _doc 路径转换为 Android 绝对路径。modelPath 必须指向已经解压的模型目录，不能指向 zip 或 .tar.bz2 压缩包。

放入或更换 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
    }
  }
})

speak({
  text: '这是一段云端 TTS 测试',
  voiceName: 'zh-CN-XiaoxiaoNeural',
  cacheKey: 'demo:cloud:001',
  cloudOnly: true
})

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']
})

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

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

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

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

启动示例：

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 端调用方式不需要跟着改变。

常用 API 与配置

API 用途总览

通用回调

异步 API 都支持以下回调：

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

initTTS(options)

默认路线大致为：App 使用系统 TTS 后再考虑云端；Web 使用浏览器系统 TTS；Harmony 和小程序使用云端音频。Web 当前不会根据 cloud.endpoint 自动切换到云端。

speak(options)

离线配置 SmartTtsOfflineOptions

云端配置 SmartTtsCloudOptions

cloud.synthesize 应返回可播放的音频地址或统一结果对象；异常会进入 fail 回调。

内置组件属性

内置组件事件

主要返回值

播报结果 SpeakResult

运行能力 SmartTtsCapabilities

运行事件

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

错误码

完整示例

• uni-app 系统与云端 TTS 示例
• uni-app Android 离线 TTS 示例
• uni-app 小说听书示例
• uni-app x 综合示例

常见问题

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

先使用系统 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 云端音频路线。

注意事项

• 系统音色由设备决定，插件不能保证所有手机和电脑拥有相同声音。
• Web 首次发声最好由用户点击触发，避免浏览器自动播放策略拦截。
• 云端密钥、Token 和生产配置只能保存在服务端。
• 长文本应合理分段，并在页面销毁时取消事件监听。
• 只使用系统 TTS 或云端 TTS 时，不要额外加入 Sherpa-ONNX 大资源。
• 离线模型代码授权与模型授权需要分别确认。
• iOS 离线能力需要单独准备原生框架和模型；本文的离线资源步骤只适用于 Android。

联系方式

信-微：l-z-1-8-7-1512-5421（-去掉，不这样写会被和谐）

作者系列 UTS 插件

以下插件已在 DCloud 插件市场上架，可按业务需要组合使用。