Android离线中文TTS集成：espeak-ng从交叉编译到JNI封装

说实话，第一次在 Android 里接 espeak-ng 时，我心里是有点犯嘀咕的。主要原因很简单：这玩意儿在 Linux 命令行里一条espeak "hello"就能出声，但要在 Android 上跑起来，牵扯到 NDK 交叉编译、JNI 封装、中文语音数据加载、音频播放链路，每一步都够让人焦头烂额。等真正跑通之后回头看，espeak-ng 反而是我目前用过的最省心的离线中文 TTS 方案——不需要开发者账号，不申请 API Key，不上报任何音频数据，一个.so文件加一份语音数据目录，就能在 App 里实现真正开箱即用的中文朗读。

这篇文章就把我从零到一的完整接入过程拆开讲，从方案选型、NDK 编译、JNI 封装、中文调优，到实际踩过的坑，全部记录下来。适合这几类人看：想在 App 里快速加入离线朗读功能但不想碰云服务的人，想给阅读类 App 配一个本地语音引擎的玩家，以及做嵌入式播报、无障碍辅助工具、车载提示这类对隐私和延迟有要求的场景。我不保证 espeak-ng 的音质能比得上各路神经网络 TTS，但它体积小、无授权限制、离线可用，这套特性在特定场景下是真的能打。

1. 为什么是 espeak-ng：四类离线中文 TTS 方案的取舍

先说结论再讲过程。我在选型的时候其实考虑了四类方案，最后才落到 espeak-ng 上，这个权衡过程本身对很多人就有参考价值。

1.1 市面上"离线中文 TTS"都有哪些选择

第一类是 Android 系统自带的TextToSpeechAPI。这是最省事的路径，不用引入任何库，代码就那么几行。但它的毛病在于依赖系统 TTS 引擎的安装情况，很多国产 ROM 里默认的中文语音引擎不是没装就是语音包缺失，你调用setLanguage(Locale.CHINESE)之后返回的LANG_MISSING_DATA和LANG_NOT_SUPPORTED真是能把人逼疯。而且它的音色、语速、回调时机都不受你控制，想要个性化几乎没有空间。另外有些设备上系统 TTS 引擎本身还会弹"正在下载语音数据"的交互，这对一个自动播报功能来说是致命的。

第二类是云厂商的 TTS SDK，比如各家语音平台。音质确实自然，但是要注册应用、申请 Key、配置签名、写权限说明，还受网络环境和免费配额限制。即便做离线语音包版本，授权逻辑也复杂，商业授权费用不低，而且 SDK 体积大，集成后包里塞进去几十上百 MB 很常见。对于一个小工具类 App 来说，为了一个朗读功能去背一个几 MB 的 SDK 加一堆商务流程，完全划不来。

第三类是开源神经网络 TTS，比如 Coqui TTS、VITS 这类。中文效果在开源圈子里确实还可以，但模型动辄几百 MB，移动端 CPU 推理速度看设备脸色，低端机上合成一句话可能要等好几秒，体验很难接受。除非你有专门的模型压缩团队，或者有 GPU 服务器做服务端合成，否则不建议在纯端侧场景用它。

第四类就是本文的主角 espeak-ng。它是 espeak 的升级分支，用 C 语言实现，库本体很小，编译出的.so大概在 2-3 MB 左右，语音数据目录也就十几 MB，内存占用和 CPU 占用都极低，在低端 Android 设备上也能流畅合成。它遵循 GPLv3 许可证，商用的话要注意开源合规问题，这是它唯一需要认真对待的坑，后面我会细说。

1.2 espeak-ng 的"确定性"是它最大的优势

跟黑盒的云服务相比，espeak-ng 的整个合成链路是可预测、可调试的。它内部是音素拼接式合成，不是统计参数或神经网络，所以你给它一段文本，它什么时候开始返回音频块、返回多少字节的 PCM 数据，这些行为都很稳定。我在代码里打开日志，可以看到每个回调拿到的样本数，也可以精确计算出一段文本的播放时长。这种确定性在做硬件联动、字幕同步、音频缓存这类需求时非常有用。

另外，espeak-ng 的架构特别适合 Android 集成。它本身支持通过espeak_Initialize指定数据目录，通过espeak_Synth同步或异步合成文本，然后通过回调把 16bit PCM 数据交给你。你不需要理会音频采集、设备枚举那些破事，拿到 PCM 之后想怎么处理都行——直接用 AudioTrack 播放、编码成 WAV 文件、或者流式传给录音机接口做后续处理，完全自主可控。

1.3 它不适合谁

音质党可以直接跳过 espeak-ng。它的中文发音带有明显的电子合成味，有点像早期的 GPS 导航语音，播报短句、口令、通知类文本还好，如果要朗读大段文学作品，听感确实一般。另外它的吐字清晰度虽然不错，但韵律和情感完全谈不上。如果你的场景是对外面向终端用户的高频语音播报，建议还是老老实实接云 TTS 或者商业离线 SDK。espeak-ng 的合理位置是"轻量工具型集成"，不是"消费级语音体验"。

2. 交叉编译与 SO 库准备：最容易被卡住的一步

选完型之后第一步就是把 espeak-ng 编译成 Android 能用的动态库。这一步坑比较密集，包括 NDK 版本、编译参数、数据目录路径，很多人就是在这里放弃的，所以我单独用一整章讲清楚。

2.1 环境准备与源码获取

我本地的环境是 macOS，Android Studio 自带 NDK 25.2.9519653。你需要先确认 NDK 已经通过 SDK Manager 装好，并记录下它的绝对路径，比如~/Library/Android/sdk/ndk/25.2.9519653。然后是源码：

git clone https://github.com/espeak-ng/espeak-ng.git cd espeak-ng

espeak-ng 的构建系统已经支持 CMake，这比老 espeak 的 autotools 省心不少。我的拉取版本大概在 1.51 或更新的 commit，不同的子版本在 CMake 配置项上略有差异，但整体流程是一致的。

2.2 用 NDK Toolchain 进行交叉编译

我不建议直接把 espeak-ng 源码塞进 Android 工程的 CMakeLists 里用add_subdirectory编译，虽然可行，但会导致整个应用工程构建变慢，而且出现问题不好定位。更稳妥的做法是预编译好各个 ABI 的.so文件，像对待一个普通第三方库那样集成。

针对 arm64-v8a 的编译命令如下：

export ANDROID_NDK_HOME=$HOME/Library/Android/sdk/ndk/25.2.9519653 cmake -S . -B build-android-arm64 \ -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \ -DANDROID_ABI=arm64-v8a \ -DANDROID_PLATFORM=android-23 \ -DCMAKE_BUILD_TYPE=Release \ -DBUILD_SHARED_LIBS=ON cmake --build build-android-arm64 --target espeak-ng -j8

重点是-DBUILD_SHARED_LIBS=ON，确保产出的是.so而不是静态库文件。编译完成之后，在build-android-arm64/src/目录下会找到libespeak-ng.so。armeabi-v7a、x86_64 同理，把ANDROID_ABI换掉重新跑一遍即可。目前主流设备基本是 arm64-v8a，如果你想覆盖老设备再编个 armeabi-v7a，我的建议是至少两个 ABI 都编上，避免在老旧机顶盒、车载设备上报错闪退。

2.3 构建产物里最关键的 espeak-ng-data 目录

这一步是大部分教程都没讲清楚的重点。espeak-ng 的引擎本体只是一个动态库，它真正发音时需要读取一套名为espeak-ng-data的数据文件，里面包含了lang、voices、phontab、intonation等等。在 PC 上安装 espeak-ng 之后，它会默认安装到/usr/share/espeak-ng-data这样的目录；但在 Android 上，文件系统路径是不可控的，你必须把这份数据打包进 App，并在代码里告诉引擎数据目录在哪。

我在编译完成后执行了一下make install到一个临时目录，或者直接从源码目录的espeak-ng-data子目录里拷贝整个数据目录，两种方法拿到的数据是一样的。关键是要保证整个目录结构完整，不要只拷一半：

espeak-ng-data/ ├── lang ├── voices ├── phontab ├── intonation └── ...

把这个目录放进 Android 工程app/src/main/assets/下面，后续在 App 启动时拷贝到私有目录，然后初始化时传给espeak_Initialize。

2.4 两种集成方案：预编译产物与 CMake 源码构建

这里给你两个方向参考，取决于你后续要不要改动 espeak-ng 的 C 源码。

第一种是我推荐的做法，预编译.so放进app/src/main/jniLibs/arm64-v8a/和app/src/main/jniLibs/armeabi-v7a/，Gradle 会自动把它们打入 APK，System.loadLibrary("espeak-ng")就能加载。优点是构建快、问题少，JNI 层完全由自己控制。缺点是你如果想修改 espeak-ng 底层源码，每次都要回到本地重新编译再拷贝。

第二种是把 espeak-ng 源码作为 Git submodule 放进工程，在 app 的 CMakeLists 里add_subdirectory。优点是可以共享构建流程，不需要手动拷贝产物；缺点是每次构建都要重新编译 espeak-ng，速度慢且对 NDK 版本敏感。我个人在正式项目里用的是第一种，简单可控，出了问题也好回退。

另外提醒一句：如果你用 CMake 源码方式，记得检查最终 APK 里是否包含了espeak-ng-data。很多朋友在电脑上跑通之后，APK 里没有数据目录，运行时就报错找不到中文语音，这个坑我放在第 5 章展开讲。

3. JNI 封装与播放链路：从调用 API 到听到声音

库和数据的准备工作完成之后，进入纯代码阶段。espeak-ng 的 C API 接口并不多，核心只有四个：espeak_Initialize、espeak_SetSynthCallback、espeak_Synth、espeak_Terminate，理解这几个函数之后，封装并不复杂。

3.1 Java 侧接口设计

我设计了一个很薄的 Java 层，让调用方只需要关心init、speak、stop、release四个动作。native 方法全部用包名com.example.espeak做前缀，方便 JNI 查找：

public class EspeakNgTts { static { // 注意加载顺序，依赖库先加载 System.loadLibrary("espeak-ng"); System.loadLibrary("espeakng_jni"); } public interface Callback { void onAudio(byte[] pcm); // 16-bit PCM 数据 void onDone(); // 本次合成结束 } private final ExecutorService executor = Executors.newSingleThreadExecutor(); private long sampleRate; public native long nativeInit(String dataParentDir, Callback callback); public native void nativeSpeak(String text, int rate, int pitch, int volume); public native void nativeStop(); public native void nativeRelease(); private AudioTrack audioTrack; public void init(final String dataParentDir, final Callback callback) { executor.execute(() -> { sampleRate = nativeInit(dataParentDir, callback); if (sampleRate <= 0) { throw new RuntimeException("espeak-ng init failed"); } }); } public void speak(String text, int rate, int pitch, int volume) { executor.execute(() -> nativeSpeak(text, rate, pitch, volume)); } }

这里所有的 native 调用都在同一个单线程池中执行，因为espeak-ng 的合成流程在同步模式下会阻塞当前线程直到合成结束，放到同一线程可以天然规避并发调用问题，也避免了在 Android 主线程里做耗时操作导致 ANR。

3.2 native 层初始化与参数传递

JNI 层核心在nativeInit里。espeak-ng 的espeak_Initialize的第一个参数是输出模式，我建议用AUDIO_OUTPUT_RETRIEVAL，也就是不自己播，而是通过回调把 PCM 数据返回来。第二个参数是缓冲区大小，传 0 表示用默认值。第三个参数就是数据目录的父目录，要的是espeak-ng-data所在的上一级目录。

#include <jni.h> #include <string.h> #include <espeak-ng/speak_lib.h> static JavaVM *g_jvm = NULL; static jobject g_callback = NULL; static jmethodID g_method_on_audio = NULL; static jmethodID g_method_on_done = NULL; JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *reserved) { g_jvm = vm; return JNI_VERSION_1_6; } static int synth_callback(short *wav, int numsamples, espeak_EVENT *events) { if (wav == NULL) { JNIEnv *env; (*g_jvm)->AttachCurrentThread(g_jvm, &env, NULL); (*env)->CallVoidMethod(env, g_callback, g_method_on_done); return 0; } JNIEnv *env; (*g_jvm)->AttachCurrentThread(g_jvm, &env, NULL); jbyteArray audio = (*env)->NewByteArray(env, numsamples * 2); jbyte *bytes = (*env)->GetByteArrayElements(env, audio, NULL); memcpy(bytes, wav, numsamples * 2); (*env)->ReleaseByteArrayElements(env, audio, bytes, 0); (*env)->CallVoidMethod(env, g_callback, g_method_on_audio, audio); (*env)->DeleteLocalRef(env, audio); return 0; } JNIEXPORT jlong JNICALL Java_com_example_espeak_EspeakNgTts_nativeInit(JNIEnv *env, jobject thiz, jstring data_parent_dir, jobject callback) { const char *dir = (*env)->GetStringUTFChars(env, data_parent_dir, NULL); int sr = espeak_Initialize(AUDIO_OUTPUT_RETRIEVAL, 0, dir, 0); (*env)->ReleaseStringUTFChars(env, data_parent_dir, dir); if (sr <= 0) { return 0L; } if (callback != NULL) { g_callback = (*env)->NewGlobalRef(env, callback); jclass clazz = (*env)->GetObjectClass(env, callback); g_method_on_audio = (*env)->GetMethodID(env, clazz, "onAudio", "([B)V"); g_method_on_done = (*env)->GetMethodID(env, clazz, "onDone", "()V"); } espeak_SetSynthCallback(synth_callback); return (jlong) sr; }

这里有个非常重要的细节：synth_callback会运行在哪个线程，取决于 Java 调用nativeSpeak所在线程。因为我在 Java 侧用单线程池，回调其实还是发生在同一个 native 调用线程里，所以用AttachCurrentThread没问题。但如果你把nativeSpeak拆分到 ThreadPool 的不同线程，回调所在线程就会漂移，必须用g_jvm做一次跨线程环境获取，这也是要在JNI_OnLoad里保存JavaVM*的原因。

3.3 nativeSpeak 的同步合成机制

espeak_Synth在AUDIO_OUTPUT_RETRIEVAL模式下，会一直阻塞到当前文本合成完毕，期间通过回调把 PCM 数据一块一块地送出来。所以 Java 侧的执行逻辑应该是：speak方法进线程池，阻塞调用 native，一轮合成完成后返回，再等下一次调用。这样设计的好处是调用方不需要考虑竞态和状态机，想停就nativeStop，把当前合成中断掉。

JNIEXPORT void JNICALL Java_com_example_espeak_EspeakNgTts_nativeSpeak(JNIEnv *env, jobject thiz, jstring text, jint rate, jint pitch, jint volume) { const char *utf8 = (*env)->GetStringUTFChars(env, text, NULL); espeak_SetParameter(espeakRATE, rate, 0); espeak_SetParameter(espeakPITCH, pitch, 0); espeak_SetParameter(espeakVOLUME, volume, 0); espeak_Synth(utf8, strlen(utf8) + 1, 0, POS_CHARACTER, 0, espeakCHARS_UTF8 | espeakENDPAUSE, 0, NULL); (*env)->ReleaseStringUTFChars(env, text, utf8); }

有几个参数需要解释一下。strlen(utf8) + 1是让引擎知道文本以 NUL 结尾；POS_CHARACTER表示文本位置类型按字符计算，适合中文；标志位espeakCHARS_UTF8告诉引擎输入是 UTF-8 编码，espeakENDPAUSE会在句末增加停顿，这对中文朗读的节奏感很重要，不要省略。

3.4 AudioTrack 播放与缓冲细节

回调拿到的 PCM 是 16bit 单声道数据，采样率就是espeak_Initialize返回的那个值。我在 Java 回调里第一次接收到音频数据时再初始化 AudioTrack，按实际采样率创建：

@Override public void onAudio(byte[] pcm) { if (audioTrack == null) { int minBuf = AudioTrack.getMinBufferSize((int) sampleRate, AudioFormat.CHANNEL_OUT_MONO, AudioFormat.ENCODING_PCM_16BIT); audioTrack = new AudioTrack.Builder() .setAudioAttributes(new AudioAttributes.Builder() .setUsage(AudioAttributes.USAGE_MEDIA) .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH) .build()) .setAudioFormat(new AudioFormat.Builder() .setEncoding(AudioFormat.ENCODING_PCM_16BIT) .setSampleRate((int) sampleRate) .setChannelMask(AudioFormat.CHANNEL_OUT_MONO) .build()) .setBufferSizeInBytes(minBuf * 2) .setTransferMode(AudioTrack.MODE_STREAM) .build(); audioTrack.play(); } audioTrack.write(pcm, 0, pcm.length); }

这里要注意一点：AudioTrack 的 buffer 如果太小，写入速度跟不上合成速度时会出现丢掉音频区块的问题，听起来就是一顿一顿的。我实测用minBuf * 2作为 buffer 大小比较稳妥，既能保证连续播放，又不会因为 buffer 过大导致停止响应延迟。在onDone回调里做stop和release，一轮合成结束之后，把 AudioTrack 清掉，避免上一个文本的残留声音串到下一段。

4. 中文发音的秘密：语言代码、音色与听感调优

espeak-ng 默认的英文发音还行，中文这块就有点特殊了：如果你什么都不设置，它可能用英文音素强行读中文，那效果真的没法听。所以中文这一步必须单独说。

4.1 zh、cmn、zhy 语言代码的差异

espeak-ng 的数据目录里，中文相关的语言文件分布在espeak-ng-data/lang和espeak-ng-data/voices中。你可能听过几种叫法：zh、cmn、zhy。它们其实是不同历史时期和不同标准下的命名，espeak-ng 里对普通话的态度是：优先使用cmn，因为这是 ISO 639-3 标准的官话代码，espeak-ng 对它支持最完善。而zh是老版本 espeak 沿袭下来的兼容别名，zhy则主要出现在一些方言变体中。

我的建议是初始化之后在代码里做两段式设置，先cmn，失败再回落zh：

if (espeak_SetVoiceByName("cmn") != EE_OK) { espeak_SetVoiceByName("zh"); }

注意espeak_SetVoiceByName的返回值要检查。常见的一种错误是调用者感觉"已经设置成功了"，但实际因为数据目录没加载，这个调用一直是失败的，于是它一直用默认语音读中文，效果自然很糟糕。

4.2 中文朗读的听感调参经验

espeak-ng 的默认参数是为英文设置的，直接拿到中文上会显得语速偏快、吐字发紧。我的实测调整方案是这样的：

这个表里的数值单位容易让人困惑，其实espeakRATE的单位是"每分钟单词数"，对中文来说就是个大概的语速档位，不需要深究，直接按值调就行。espeakPITCH的范围是 0 到 99，50 是中间线。

我在做短句播报时喜欢把语速调到 150 左右，播报口令、验证码、站名这类短文本很清楚；如果是长文朗读场景，140 以下会更耐听。这个完全看你的产品调性，没有标准答案。

4.3 进阶玩法：把 espeak-ng 封装成系统 TTS 服务

如果你不想在自己的 App 里写播放逻辑，而是想把 espeak-ng 做成一个全局可用的语音引擎，比如让"阅读 App"这类应用直接调用它，那就需要走 Android 的TextToSpeechService路线。espeak-ng 官方仓库里其实带了 Android 工程示例，espeak-ng/android目录下有一个EspeakService，继承了系统的TextToSpeechService抽象类，实现了onSynthesizeText、onIsLanguageAvailable、onLoadLanguage等回调。

把 espeak-ng 数据目录放进这个 Service 的私有目录，初始化时把数据路径指过去，然后在系统设置里把默认 TTS 引擎改成"Espeak"，大部分支持 TTS 的 App 就能直接使用。我实际在阅读类 App 里试过，它能把一段正文切成多句文本逐次调用合成接口，整本书朗读问题不大。唯一的短板仍然是音质，但作为本地免费引擎，已经是非常出色的方案了。这一步如果你感兴趣，可以基于官方 Android 工程改，它已经把 JNI 层和 Service 层的框架搭好了，省掉不少重复工作。

5. 实战踩坑记录：五条排查链路帮你少走弯路

这一章是我最想写的内容。espeak-ng 的 API 其实不难，难的是那些不报错、或者报错信息完全没有提示意义的问题。我整理出五条我实际踩过、也帮别人排查过的坑，每一条都是一个完整的排查链路，你可以照着这个思路去定位自己遇到的问题。

5.1 运行时找不到 espeak-ng-data 的完整排查

现象：espeak_Initialize返回 -1 或一个异常值，中文语音完全不可用。

排查链路：先用日志确认传入路径到底是什么。我在代码里打过日志，发现当时传入的是getFilesDir().getAbsolutePath()，也就是/data/data/com.example.app/files。如果espeak-ng-data是放在这个目录下，那路径是没问题的。但很多朋友会在 assets 里放一个espeak-ng-data目录，然后忘了在启动时拷贝——espeak-ng 在 Android 上只能从真实文件系统读取数据，assets 里的文件对它来说是不存在的。

根因：assets 目录不是普通文件系统路径。官方 API 或者一些老教程只说"设置数据路径"，但没说清楚 Android 的 assets 必须先解压到 files 目录才能用。

解决方案：App 启动时执行一次拷贝，把整个 assets 里的espeak-ng-data复制到context.getFilesDir()/espeak-ng-data，然后初始化时传context.getFilesDir().getAbsolutePath()。注意拷贝过程要递归创建目录，不能只拷贝文件。拷贝完成后再调用 nativeInit。

/data/data/com.example.app/files/ ├── espeak-ng-data/ │ ├── lang/ │ ├── voices/ │ ├── phontab │ └── ...

5.2 JNI 中文乱码的根因与修复

现象：Java 层传字符串"你好"，合成出来却变成乱码或者无效的哼哼声。

排查链路：先确认 Kotlin/Java 字符串在 JNI 里拿到的是什么编码。GetStringUTFChars返回的是修改版 UTF-8，而 espeak-ng 期望的是标准 UTF-8。普通中文文本在这两者之间的差异通常不大，但遇到特殊字符、生僻字、组合字符时就会出问题。我当时用一个包含 emoji 和中文标点的字符串测试，发现部分字符被错误解析成多个音素，听起来就是乱念。

根因：修改版 UTF-8 会把 U+0000 编码为0xC0 0x80，也会对代理对做特殊处理，espeak-ng 的 UTF-8 解析器不认识这种编码，导致个别字符乱掉。

解决方案：最稳妥的做法不是用GetStringUTFChars，而是在 JNI 里把 Java 的String转成byte[]，以 UTF-8 编码后传给 native 层：

byte[] bytes = text.getBytes(StandardCharsets.UTF_8); nativeSpeakBytes(bytes, rate, pitch, volume);

在 JNI 侧直接用GetByteArrayElements拿到字节数组，再把长度传进去。这样彻底绕开了修改版 UTF-8 的问题，实测用 emoji、中文、日文混合字符串都不会乱。

5.3 合成卡顿与 ANR：线程模型问题

现象：在界面上点"朗读"按钮之后，整个页面卡住几秒，然后系统弹出 ANR。

排查链路：一看日志，卡点就发生在 nativeSpeak 调用里，完全符合espeak_Synth同步阻塞的特性。我当时第一版代码是直接在onClick回调里调speak()，等于在主线程里跑完整段合成，当然会卡死。

根因：espeak-ng 的合成流程是 CPU 密集型，长文本合成耗时从几百毫秒到数秒不等，不能放在主线程。

解决方案：必须用后台线程或线程池执行 nativeSpeak，而且强烈建议用单线程池。还有一个隐蔽的问题：如果你在回调里做 UI 操作，比如更新进度条，记得切回主线程，因为合成回调默认运行在后台线程。AudioTrack 的写入没有线程限制，但 UI 刷新必须走主线程。

5.4 低音质与杂音：采样率和缓冲配置

现象：声音能出来，但有明显的爆音、卡顿或类似机器噪声。

排查链路：先确认 AudioTrack 的采样率有没有用对。espeak_Initialize的返回值就是实际采样率，一般在 Linux/Android 下是 22050。如果你在 Java 侧写死 44100，AudioTrack 会把 22050 的 PCM 数据按 44100 播放，听感就是音调变高、速度加快，听起来特别别扭。另外如果 AudioTrack 的 buffer 太小，也会出现断续声。

根因：两类问题混在一起。一类是采样率写死导致的重采样错误，一类是 buffer 不足导致的丢块。

解决方案：采样率一定用espeak_Initialize的返回值，不要写死。AudioTrack buffer 大小用getMinBufferSize乘 2。如果还有杂音，检查回调里拷贝 PCM 的字节数是不是numsamples * 2，有的人写成了numsamples，直接少拷一半数据，播放出来的就是严重的噪声。

5.5 不同 Android 版本与 CPU 架构的兼容性

现象：在开发机上一切正常，发布测试包之后用户的机器上闪退，崩溃信息指向System.loadLibrary。

排查链路：崩溃日志一般会写dlopen failed: library "libespeak-ng.so" not found，或者unexpected e_machine。前一种常见于只放了 arm64-v8a 的 so，但用户设备是老的 32 位系统，加载不到对应 ABI；后一种是把 x86 的 so 跑到 arm 设备上，或者是 NDK 版本太老导致的 ELF 格式问题。

根因：JNI 库的 ABI 不匹配，APK 里缺少目标设备的.so。

解决方案：至少同时编 arm64-v8a 和 armeabi-v7a 两个 ABI。如果你的测试机全是 arm64，很难发现 32 位设备的兼容问题。另外用相对新的 NDK 版本重新编译一次，老 NDK 编出来的 so 在部分 Android 14/15 的 ROM 上可能因为依赖了过时的 libc 符号而加载失败。

关于开源合规与最后一点小建议

前面提到 espeak-ng 是 GPLv3 许可证。如果你的 App 是个人项目、内部工具、或者开源项目，直接集成没有问题；但如果是商业闭源 App，想要直接把 espeak-ng 的代码和你的业务代码揉在一个进程里发行，就要认真评估 GPL 的传染性问题。比较稳妥的做法是：把 TTS 能力做成一个独立的 Module 或独立 App，通过进程隔离或系统 TTS 服务的方式与主应用解耦，降低合规风险。我不是法务，具体怎么操作还是要咨询专业人士，但这个坑确实要提前知道，别等产品上线了才着急。

我在实际项目里使用这套方案已经大半年了，启动速度快、内存稳定、不依赖网络，也不需要维护任何账号体系，确实符合"离线开箱即用"这个定位。如果你只想快速验证，建议先做一个小 Demo：把 so 文件和数据目录加进去，用几百行代码把朗读功能跑通，然后再考虑音频焦点、服务化封装、缓存优化这些进阶的事情。espeak-ng 的 API 设计得非常直白，留给开发者自己发挥的空间很大，熟悉之后你会觉得老牌开源库那种"克制而高效"的设计风格，其实很有味道。