更新记录

1.2.16（2026-07-31）

• 修复 uni-app x 示例日志样式在 HarmonyOS 编译时使用不受支持的 white-space: pre-wrap 导致构建失败的问题，改用平台支持的 normal 并保留自动换行。
• 清理默认市场包中的本地 Sherpa-ONNX 测试资源记录，并将 README 中仓库级脚本命令改为客户可执行的手动资源接入和真机验证说明。
• 修复 pages_init.json 指向已不存在小说示例页的问题，并补齐队列事件与组件文档。
• 本版本只修改示例样式和发布元数据，不改变 TTS 初始化、合成、播放控制或平台原生实现，无需因此重新制作自定义基座。

1.2.15（2026-07-22）

• 修复 HBuilderX 5.15 / 新版 Android SDK 对旧系统 Locale(String, String) 兼容分支产生的 deprecated 诊断；Android 5+ 继续使用 Locale.forLanguageTag，Android 4.4 兼容路径保持不变。
• 修复 uni-app x Web 编译时分平台入口未公开公共类型的问题：utssdk/web/index.uts 重新导出 interface.uts，并补齐 onTtsEvent/offTtsEvent 事件别名。
• Edge TTS 云函数迁移到 templates/uniCloud/cloudfunctions/edge-tts；需要时手动复制到项目根 uniCloud，避免未启用 uniCloud 的项目仅因安装插件就出现控制台提示。
• 非 App 错误实现改为普通字段对象并补齐 cause，避免 Web/小程序解析全局 UniError；App 端仍保留标准 UniError 实现。
• 本次未修改共享接口声明和 Android、iOS、Harmony 原生实现；uni-app 与 uni-app x 继续共用一致的插件代码。

1.2.14（2026-06-25）

• 修复 uni-app x Android 编译 error18：示例页不再用插件内部 SmartTtsCloudResult 描述云端 HTTP 返回，改为页面本地 CloudAudioData 类型，避免页面端找不到该类型名称。
• 修复 uni-app x Android 编译 error17：example/uniappx/index.uvue 的 API 和类型统一从插件根目录导入，并显式构造 SmartTtsCloudOptions，避免 cloud 配置被推断为 UTSJSONObject 或页面侧命名空间类型。
• 修复云端播放 URL 读取时 audioUrl 可空字符串访问不安全的问题，避免 Android class 编译阶段返回 String?。
• 已通过 app-android 单文件 LSP 和 Android 自定义基座编译检查；本版本只调整 uni-app x 示例页、版本元数据和文档记录，不修改公共 API 或平台原生实现。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-smart-tts 智能语音播报 TTS 插件

lizhao-smart-tts 是面向 uni-app / uni-app x 的 TTS 语音播报插件。推荐按由浅入深的方式接入：先使用系统 TTS；需要完全离线时接入离线 TTS 资源包；需要固定音色、高音质或统一多端效果时再接入云端 TTS。

接入方式选择

安装与导入

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

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

不要直接 import utssdk/index.uts 或平台目录文件。

平台支持

系统 TTS 接入

系统 TTS 是最轻的接入方式，不需要额外模型、服务器或原生依赖。Android 使用系统 TextToSpeech，iOS 使用 AVSpeechSynthesizer，Web 使用浏览器 SpeechSynthesis。

最小示例

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

// 初始化系统 TTS。App Android / iOS 会优先使用 native 系统引擎。
initTTS({
  lang: 'zh-CN',
  fallbackChain: ['native'],
  success(res) {
    console.log('系统 TTS 初始化成功', res.capabilities.adapter)
  },
  fail(err) {
    console.log('系统 TTS 初始化失败', err.errCode, err.errMsg)
  }
})

// 提交一段普通播报。
speak({
  text: '订单已完成，请及时处理',
  rate: 1.0,
  pitch: 1.0,
  volume: 1.0,
  success(res) {
    console.log('系统 TTS 播报完成', res)
  },
  fail(err) {
    console.log('系统 TTS 播报失败', err.errCode, err.errMsg)
  }
})

查询系统音色

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

getVoices({
  success(voices) {
    console.log('可用音色', voices)

    // Android / iOS 会尝试按 voiceName 选择音色，不支持时回退系统默认音色。
    speak({
      text: '这是一段指定音色的系统 TTS 测试',
      voiceName: voices.length > 0 ? voices[0].name : '',
      rate: 1.0
    })
  }
})

控制播报

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

pause({})
resume({})
stop({ clearQueue: true })

Android 系统 TTS 没有真正的 pause API，插件会用 restart-segment 降级语义处理：暂停后继续会从当前分段开头恢复。

系统 TTS 常见现象

离线 TTS 接入

离线 TTS 用于无网播报。默认发布包不提交 Sherpa-ONNX Android AAR 和模型大资源；需要离线 TTS 的项目按下方资源结构准备专业资源包，再重新打 Android 自定义基座。模型文件仍建议按项目情况随基座打包或运行后下载。

注意：如果项目不需要离线 TTS，只使用手机系统 TTS 或云端 TTS，不要把 uni_modules/lizhao-smart-tts/utssdk/app-android/libs/ 和 assets/sherpa-onnx/ 带入发布包，这样可以明显减小插件目录和 Android 自定义基座体积。未放入 AAR/SO 时不要使用 fallbackChain:['offline-ai']；系统 TTS 仍可正常使用 fallbackChain:['native']。

Android 离线能力分成两类资源：

如果关注 60M 打包限制，推荐使用“arm64 运行库进基座 + 模型运行后下载”的方式：打基座前只放入 arm64-v8a AAR，不放模型；安装基座后下载模型，传入 modelPath 初始化。

默认包行为

未放入离线资源时，显式使用 offline-ai 会返回：

9011006 offline model missing

这不是故障，只表示默认轻量包没有携带离线模型和推理库。

方案一：模型随基座打包

从 Sherpa-ONNX 官方发布页下载并安装以下资源：

然后使用 modelDir 初始化：

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

// 模型已经随 Android 自定义基座进入 assets 时，使用 modelDir。
initTTS({
  lang: 'zh-CN',
  fallbackChain: ['offline-ai', 'native', 'cloud'],
  offline: {
    engine: 'sherpa-onnx',
    modelDir: 'sherpa-onnx/zh-pro',
    speakerId: 0
  }
})

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

这种方式最简单，但模型约 180MB，会显著增加自定义基座包体，不适合 60M 限制场景。

如需把西班牙语模型随 assets 打进基座，将官方 vits-piper-es_ES-miro-high 模型解压到 utssdk/app-android/assets/sherpa-onnx/es-es-miro/，然后初始化时使用 lang: 'es-ES' 和 modelDir: 'sherpa-onnx/es-es-miro'。

方案二：模型运行后下载

只准备业务设备需要的原生 ABI（通常为 arm64-v8a），不要把模型放进自定义基座。将裁剪后的 AAR 安装到：

uni_modules/lizhao-smart-tts/utssdk/app-android/libs/sherpa-onnx-1.13.2-arm64-v8a.aar

完成后重新打 Android 自定义基座。App 运行后，由业务代码下载并解压模型到 App 私有目录，目录内至少需要包含：

推荐把模型 zip 下载到 App 私有目录后解压，例如：

https://env-00jxu7ha8amh.normal.cloudstatic.cn/tts/sherpa-onnx.zip

注意：上面的地址是云静态托管示例地址。如果客户访问失败，或需要使用自己的模型分发链路，可以替换为自己的长期有效 CDN / 云存储下载地址。

建议解压到 App 私有目录，例如：

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

在 App Android 中可使用 plus.io.convertLocalFileSystemURL('_doc/lizhao-smart-tts/sherpa-onnx/zh-pro') 或 plus.io.convertLocalFileSystemURL('_doc/lizhao-smart-tts/sherpa-onnx/es-es-miro') 转成 Android 绝对路径，然后传给 offline.modelPath。

model.onnx 或 *.onnx（例如 es_ES-miro-high.onnx）
tokens.txt
lexicon.txt 或 espeak-ng-data/
dict/
phone.fst / date.fst / number.fst（模型包内存在时保留）

然后把解压后的 Android 绝对路径传给 offline.modelPath：

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

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

// modelPath 是运行时模型加载入口；填写后优先于 modelDir。
initTTS({
  lang: 'zh-CN',
  fallbackChain: ['offline-ai', 'native', 'cloud'],
  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: '模型不进基座，也可以运行后加载并离线播报'
})

这种方式是当前推荐方案：原生运行库仍需要进基座，但模型不进基座，可以明显降低云打包体积。客户也可以把上面的 zip 下载地址替换成自己的云存储地址，只要最终解压目录内包含 model.onnx / tokens.txt / lexicon.txt 等必要文件即可。

西班牙语 Piper 模型的目录结构与中文模型不同，通常包含 es_ES-miro-high.onnx / tokens.txt / espeak-ng-data。插件 Android 离线桥接会自动识别 model.onnx 或目录下第一个 .onnx 文件，并允许 lexicon.txt 与 espeak-ng-data 二选一。

资源准备原则

• AAR 必须在制作 Android 自定义基座前放入 utssdk/app-android/libs/。
• 随基座打包的模型放入 utssdk/app-android/assets/sherpa-onnx/<model-dir>/。
• 运行后下载的模型应解压到 App 私有目录，再把绝对目录传给 offline.modelPath。
• 只保留业务需要的 ABI，并分别核对 Sherpa-ONNX 代码授权与模型授权。

手动放置资源

如果用户不使用脚本，也可以手动下载并放到以下位置：

uni_modules/lizhao-smart-tts/
└─ utssdk/
   └─ app-android/
      ├─ libs/
      │  └─ sherpa-onnx-1.13.2.aar
      └─ assets/
         └─ sherpa-onnx/
            └─ zh-pro/
               ├─ model.onnx
               ├─ tokens.txt
               ├─ lexicon.txt
               └─ ...
            └─ es-es-miro/
               ├─ es_ES-miro-high.onnx
               ├─ tokens.txt
               ├─ espeak-ng-data/
               └─ ...

如果模型随基座打包，模型目录必须与代码中的 modelDir 保持一致，例如中文 sherpa-onnx/zh-pro、西班牙语 sherpa-onnx/es-es-miro。如果模型运行后下载，不需要放到 assets，只要把解压后的绝对目录传给 modelPath。

重新打 Android 自定义基座

只更新 wgt / appResource 不能把 AAR / SO 热更新进原生基座。放入或替换 Sherpa-ONNX Android AAR 后，必须重新运行 Android 原生联编或重新打 Android 自定义基座。

如果只替换运行后下载的模型文件，并且 AAR / SO 已经在当前自定义基座里，不需要重新打基座，重新下载模型后再次调用 initTTS({ offline: { modelPath } }) 即可。

项目测试页和插件内示例页已经注册：

uni_modules/lizhao-smart-tts/example/uniapp/ttsOffline
uni_modules/lizhao-smart-tts/example/uniapp/ttsOffline

测试步骤：

1. 从官方发布页下载并手动放置 AAR。
2. 重新打 Android 自定义基座。
3. 如果模型没有进 assets，先把模型下载并解压到 App 私有目录。
4. 打开 uni_modules/lizhao-smart-tts/example/uniapp/ttsOffline，或打开插件示例 uni_modules/lizhao-smart-tts/example/uniapp/ttsOffline。
5. 在示例页选择中文或西班牙语，使用 modelDir 或填写 modelPath，点击“初始化离线引擎”，再点击“离线播报”。
6. 点击“能力查询”，确认 supportMatrix.offlineAi=true，details.modelReady=true。

业务代码接入

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

// 二选一：assets 模型使用 modelDir；运行时下载模型使用 modelPath。
const offlineModel = {
  engine: 'sherpa-onnx',
  modelPath: '/data/user/0/你的包名/files/sherpa-onnx/zh-pro',
  speakerId: 0
}

initTTS({
  lang: 'zh-CN',
  fallbackChain: ['offline-ai', 'native', 'cloud'],
  offline: offlineModel,
  success(res) {
    console.log('离线 TTS 初始化成功', res.capabilities.adapter)
  },
  fail(err) {
    console.log('离线 TTS 初始化失败', err.errCode, err.errMsg)
  }
})

speak({
  text: '这是一段离线 TTS 语音播报',
  fallbackChain: ['offline-ai', 'native', 'cloud'],
  offline: offlineModel
})

getCapabilities({
  success(res) {
    console.log('离线能力', res.supportMatrix.offlineAi, res.details)
  }
})

西班牙语运行时模型示例：

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

const spanishModel = {
  engine: 'sherpa-onnx',
  modelPath: '/data/user/0/你的包名/files/sherpa-onnx/es-es-miro',
  speakerId: 0
}

initTTS({
  lang: 'es-ES',
  fallbackChain: ['offline-ai', 'native', 'cloud'],
  offline: spanishModel
})

speak({
  text: 'Hola. Esta es una prueba de voz sin conexion.',
  fallbackChain: ['offline-ai', 'native', 'cloud'],
  offline: spanishModel
})

离线包注意事项

• Sherpa-ONNX AAR / SO 不能运行后下载补进自定义基座；能运行后下载的是模型文件。
• modelPath 必须是解压后的模型目录，不是 .tar.bz2 压缩包路径。
• 9011006 通常表示模型目录缺少 model.onnx 或 *.onnx / tokens.txt / lexicon.txt 或 espeak-ng-data；9011007 可能表示 AAR / SO 未进入当前自定义基座，或 Sherpa 初始化失败。
• Android 不要一次性塞入所有 ABI，优先只保留业务需要的 arm64-v8a。
• 发布前必须删除本地 Sherpa 大资源，尤其是 utssdk/app-android/assets/sherpa-onnx、utssdk/app-android/libs 和 .sherpa-downloads，避免默认插件包超出 DCloud 插件市场体积限制。
• 发布插件前应直接检查插件目录，确认上述 AAR、模型和下载缓存均未进入默认市场包。
• Sherpa-ONNX 代码授权与模型授权不是一回事，上线前必须分别确认。
• iOS 离线资源需要单独准备 .xcframework 和模型目录，本 README 当前只提供 Android 资源脚本。

云端 TTS 接入

云端 TTS 适合固定音色、高音质、多端一致、小程序和 Harmony 音频链路。插件向云端服务提交文本，服务返回可播放的 audioUrl，App 端用音频播放器播放。

云端接口约定

默认约定云端接口返回：

{
  "audioUrl": "https://example.com/audio/demo.wav",
  "cacheHit": false,
  "durationMs": 1200,
  "provider": "edge-tts",
  "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 用于 App 端云端测试，避免系统 TTS 初始化失败影响云端播放。

Edge TTS uniCloud 免费测试代理

插件内置 Edge TTS uniCloud 免费测试代理模板，目录：

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

模板不放在插件根 uniCloud 目录，避免未启用 uniCloud 的项目仅因安装插件就出现控制台提示。需要使用时，把模板复制到项目根 uniCloud 后由 HBuilderX 按实际绑定的云空间处理。它不是 CosyVoice 私有化模型服务，而是通过 WebSocket 请求 Edge 在线 TTS，生成音频后上传到 uniCloud 云存储，再返回 audioUrl。该方案适合测试和演示，不建议作为长期商业生产核心链路。

默认测试地址：

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

部署步骤：

1. 在 HBuilderX 中为项目创建或绑定 uniCloud 云空间。
2. 把 uni_modules/lizhao-smart-tts/templates/uniCloud/cloudfunctions/edge-tts 复制到项目根 uniCloud/cloudfunctions/edge-tts。
3. 在项目根 uniCloud 视图中找到 edge-tts，按需安装依赖后右键上传并部署云函数。
4. 在 uniCloud 控制台开启云函数 URL 化，复制 URL 作为 cloud.endpoint。

URL 化位置示意：

Edge TTS 测试页路径：

uni_modules/lizhao-smart-tts/example/uniapp/tts.vue

该页面提供“切换云端测试”“切换系统 TTS”“打开系统 TTS 设置”“播放云端测试”“系统 TTS 一键自检”等按钮。云端测试会使用 uni.request 请求云函数，并用 uni.createInnerAudioContext 播放返回的 audioUrl。

手机系统 TTS 测试路线：点击“切换系统 TTS”，探测成功后点击“使用系统 API：普通播报”或“系统 TTS 一键自检”。

uni-app x 示例路径：

uni_modules/lizhao-smart-tts/example/uniappx/index.uvue

该示例按 App 自定义基座真机调试整理，覆盖云端 TTS、系统 TTS、离线 Sherpa-ONNX、小说听书、暂停/继续/停止和运行日志。示例只从插件根目录导入通用 API 和类型，iOS 打包不会解析 Android 原生 TextToSpeech 依赖，Android 编译也不会把 SmartTtsCloudOptions / SmartTtsCloudResult 解析到页面侧命名空间。页面加载后会执行一次只读 USB 自检，仅查询当前 App 平台 TTS 能力，不自动播报、不请求云端、不加载离线模型；首屏出现 USB 自检成功即可确认插件 API 在 uni-app x App 中可调用。

如果 Edge TTS 云函数日志出现 Unexpected server response: 403，通常是在线接口握手参数变更或云函数模板未更新。请更新模板后重新上传部署。

CosyVoice Docker 真实模型服务完整部署

如果需要私有化高音质云端 TTS，可以使用插件附带的 CosyVoice Docker 服务模板：

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

默认模型：

iic/CosyVoice-300M-SFT

默认音色：

中文女 / 中文男 / 英文女 / 英文男

快速启动：

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

常用接口：

生产环境建议配置 HTTPS 反向代理，让手机、小程序和 App 都能访问返回的 audioUrl。Nginx 示例位于：

uni_modules/lizhao-smart-tts/static/server/cosyvoice-cloud-tts/nginx.example.conf

云端服务启动后，先请求 /health 和 /voices，再从真机调用 POST /v1/tts，确认返回的 audioUrl 可由目标 App 或小程序访问和播放。

第三方商业 TTS 代理

如果不想自建模型服务，可以把商业 TTS 厂商接口放到服务端代理里。密钥只放服务端，不要写入 App、插件或 README 示例。

模板目录：

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

业务侧仍然只接统一的 cloud.endpoint：

initTTS({
  fallbackChain: ['cloud', 'native'],
  cloud: {
    provider: 'custom',
    endpoint: 'https://你的服务/v1/tts',
    method: 'POST',
    responseField: 'audioUrl'
  }
})

场景字段

云端链路会透传以下业务字段，服务端可用它们做缓存、角色音色和业务路由：

scene/cacheKey/voiceRole/emotion/metadata

示例：

speak({
  text: '欢迎回来',
  scene: 'order',
  cacheKey: 'order:welcome:v1',
  voiceRole: 'narrator',
  emotion: 'warm',
  metadata: {
    source: 'home'
  },
  cloudOnly: true
})

API 说明

API 列表

initTTS(options)

说明 初始化 TTS 运行时。

参数

speak(options)

说明 提交一段文本播报。

参数

SmartTtsOfflineOptions

SmartTtsCloudOptions

cloud.synthesize 适合接入已有业务网关：函数需返回可播放的音频地址或统一结果对象，异常应交给 fail 回调处理。

队列控制与事件

stop({ clearQueue: true }) 会停止当前任务并清空待播队列。可通过 on(eventName, callback) 订阅事件，通过 off(eventName, callback) 取消订阅；常用事件包括 start、progress、end、error 和 queueChanged。

组件属性

组件事件

返回值字段

能力字段

错误码

验证建议

发布默认轻量包前，确认插件目录不含本地 AAR、模型、下载缓存、测试报告或资源清单。Edge TTS、商业代理和自建云端分别使用真实测试环境验证健康检查、音色列表、合成、播放与失败回调；离线能力必须在包含目标 AAR 的 Android 自定义基座上验证。不要把真实密钥、Token 或生产私密配置写进插件仓库。

联系方式

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

作者系列UTS插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。