简介：这是一份面向移动开发者的Opus音频编码库跨平台编译资源，目标是帮助在Android和iOS应用中集成高质量、低延迟的语音通话与音频压缩能力，尤其适用于VoIP、实时音视频等场景。资源基于Opus 1.1.4版本，整套压缩包共4106个文件，整体约50.17MB，包含大量C/C++源文件（.c/.h）、自动生成与编译中间文件（.d/.o）、Android构建脚本（.mk）及跨平台工程文件（.vcxproj/.sln），也收录了SO动态库、JAR包、APK、Gradle配置和自动化编译脚本等，方便开发者对照参考完整构建流程。目前已有896人学习下载。通过压缩包可以了解Opus源码结构、NDK/JNI集成方式、Xcode静态库链接方法，以及不同网络条件下编码参数的调整思路；包内还保留了Makefile、configure等构建配置与头文件接口定义，适合需要自行编译或二次封装Opus的Android/iOS开发者快速上手。 作为一个常年和跨平台音频打交道的人，我太清楚“android ios opus语音编码压缩库编译”这件事有多容易让人卡住了。网上零零散散的旧教程一大堆，但很多都停留在老版本 NDK 或者旧版 Xcode 的时代，照着做要么报错，要么编译出来的库根本没法直接拖进工程。这篇文章我不打算讲 Opus 的音频算法原理，纯粹从一名开发者的角度，把这半年我在 Android 和 iOS 两侧把 Opus 从源码编译到可集成产物的完整过程、踩坑记录和最终脚本方案写出来，希望能让你少走几趟弯路。
1. 为什么语音类App最终都逃不过自己编Opus
1.1 Opus是什么，它到底解决了什么问题
Opus 是一个开源的、有损的音频编解码格式，由 IETF 标准化，特别针对语音和实时通信做了大量优化。它最大的特点是低延迟加高压缩率，在同样码率下，音质往往比传统 AMR、AAC 或 Speex 好得多，而且它本身同时支持语音和音乐两种场景，采样率可以从 8kHz 一路到 48kHz，码率范围也相当宽。现在的 VoIP、实时语音房、游戏语音、会议系统，几乎都把 Opus 当成了首选编解码器。
如果你是做 Android 或 iOS 端的音频采集、传输、播放，想在 App 里把 PCM 数据压缩成 Opus 再走网络，或者收到 Opus 后解码成 PCM 播放，那你就绕不开一个现实问题：怎么把 Opus 的 C 源码编译成 Android 的 .so 或者 iOS 的 .framework。
1.2 官方仓库给的现成东西，为什么不够用
Opus 官方仓库虽然维护很活跃，但它本质上只提供了源码，不负责帮你编译成各个移动平台的可用产物。Android 上如果通过 Gradle 引用第三方预处理过的 Opus 库，版本往往停留在旧版本，更新不及时，还可能带了无关的依赖；iOS 上虽然有用 CocoaPods 打包的 Opus 库，但遇到需要自定义裁剪、需要固定浮点模式、或者想同时支持模拟器和真机多架构的时候，就很被动。
还有一个更常见的场景是：你手头本来就有一套音频前处理流程，希望在编码前先做回声消除、降噪等操作，这时候必须拿到 Opus 库里更底层的 API，或者希望把编码器配置成 VBR、DTX、FEC 这些参数。这些需求都直接指向同一个结论：自己维护一份编译脚本，从源码编出真正可控的库，才是最稳妥的方案。
2. 编译前的选型：NDK版本、CMake与configure脚本怎么选
2.1 环境清单与版本建议
开始之前，先把环境整理一下。我的开发机是 macOS，所以下面的路径和命令都基于 macOS，Linux 上思路完全一致，只是路径需要替换。Android 侧我用的 NDK 是 r25c，CMake 是 3.22.1，Android Studio 版本在 Hedgehog 之后都自带 CMake，可以直接用。iOS 侧我用的是 Xcode 14.3，SDK 版本对应的 iPhoneOS 17 和模拟器 SDK 也会在编译时自动匹配。
有一点很重要：Opus 的源码非常干净，官方仓库用 C 语言编写，理论上任何支持 C99 的编译器都能编，不需要额外的第三方依赖库。这意味着你只要把交叉编译的环境变量配置正确，基本就不会有编译失败的意外情况。需要重点检查的只有两点：NDK 里是否有与你目标 ABI 匹配的 clang 工具链，Xcode 的 Command Line Tools 版本是否完整。
2.2 configure 与 CMake 两条路线的取舍
Opus 同时提供了传统的 configure 脚本和 CMakeLists.txt。我个人的经验是：Android 优先用 CMake，iOS 优先用 configure 脚本。原因有两个。
Android 侧，官方已经在 NDK 里内置了 CMake 工具链文件，你只要指定CMAKE_SYSTEM_NAME=Android，CMake 就会自动调用 NDK 里的 clang，并帮你把每个 ABI 对应的编译参数都设置好。这样你不用手动维护一堆-march参数，也不会出现选错 sysroot 的低级错误。
iOS 侧，Opus 的 configure 脚本对交叉编译支持得很好，而且你可以直接用xcrun定位到 Xcode 的 SDK 路径，把-arch arm64和-isysroot传进去，编出来的静态库可以直接用于后续合并。CMake 在 iOS 上也能用，但如果你不熟悉CMAKE_OSX_SYSROOT、CMAKE_OSX_ARCHITECTURES的配合方式，反而容易出现编译通过但架构不对的问题。所以更稳妥的路线是 configure。
2.3 Opus版本锁定
Opus 源码在 GitHub 上提供 release tag，比如 1.4、1.5。编译前一定要先 checkout 到具体 tag，不要直接编译 main 分支。main 分支的工具脚本和代码结构可能会因为正在开发新功能而变动，今天能编过的命令，下个月可能就失效了。我习惯把版本锁定在某个稳定 release 上，比如 1.5.2，这样可以保证团队里所有人重新执行脚本时，产物行为一致。
3. Android侧：用CMake+NDK一套脚本编译出四种ABI的so
3.1 最小可用 CMake 编译脚本
在 Android 侧，我推荐直接写一个脚本循环跑四个 ABI。先进入 Opus 源码根目录，然后创建一个 build-android.sh：
#!/bin/bash export ANDROID_NDK_HOME=/path/to/your/ndk export API_LEVEL=21 ABIS=("arm64-v8a" "armeabi-v7a" "x86_64" "x86") for ABI in "${ABIS[@]}"; do rm -rf build-android-$ABI cmake -S . -B build-android-$ABI \ -DCMAKE_SYSTEM_NAME=Android \ -DCMAKE_ANDROID_NDK=$ANDROID_NDK_HOME \ -DCMAKE_ANDROID_ARCH_ABI=$ABI \ -DCMAKE_ANDROID_NDK_TOOLCHAIN_VERSION=clang \ -DANDROID_PLATFORM=android-$API_LEVEL \ -DBUILD_SHARED_LIBS=ON \ -DOPUS_BUILD_TESTING=OFF \ -DOPUS_BUILD_PROGRAMS=OFF \ -DCMAKE_BUILD_TYPE=Release cmake --build build-android-$ABI -j4 done这里有几个关键变量必须说明。CMAKE_ANDROID_ARCH_ABI直接决定生成的架构目录，cmake 会自动把 libopus.so 生成到build-android-$ABI/libopus.so，你不用自己去翻 clang 路径。OPUS_BUILD_TESTING和OPUS_BUILD_PROGRAMS是为了关掉测试用例和命令行工具，不然编译时间会变长，而且会生成一堆你用不到的二进制文件。
3.2 ABI选择与API Level的注意点
现在 Android 主流的真机架构基本是 arm64-v8a，但 armeabi-v7a 仍然有大量存量设备，尤其是物联网、车载、国产政企定制机，所以四个 ABI 一起编是最保险的。x86 和 x86_64 主要用于模拟器调试，如果你的工程只用真机调试，可以只保留 arm64-v8a 和 armeabi-v7a，减少产物体积。
API Level 我一般选 21，这基本覆盖了 Android 5.0 以上的所有设备。很多教程会写 API 16 或 19，但 Opus 里并没有使用特别老旧的系统调用，设 21 对音频场景完全没有影响，还能让 OpenSL ES、AAudio 这些新接口在运行时更容易被识别。如果你只面向 Android 8.0 以上设备，也可以直接把 API_LEVEL 提到 26，编译出来的 so 会更精简一些。
3.3 老生常谈的strip问题
编译完成后，你很快会发现 arm64-v8a 的 libopus.so 可能有好几 MB。这个大小对于语音库来说明显偏大，原因是 CMake 默认的 Release 模式没有帮你把调试符号表完全去除。在 NDK 里其实带了llvm-strip，路径在$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-strip，拷贝完四个 so 之后，对每个 so 执行：
for ABI in arm64-v8a armeabi-v7a x86_64 x86; do $ANDROID_NDK_HOME/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-strip \ build-android-$ABI/libopus.so -o libopus-${ABI}.so donestrip 之后，arm64-v8a 的 so 通常能降到 300KB 以内，对整个 App 体积来说非常友好。
4. iOS侧：configure配合xcrun交叉编译，多架构合并成framework
4.1 真机arm64版本的编译命令
iOS 侧我用 configure 脚本。首先确保你已经进入 Opus 源码根目录，并且通过xcrun --sdk iphoneos --show-sdk-path拿到了真机 SDK 的路径。然后执行：
export SDK_PATH=$(xcrun --sdk iphoneos --show-sdk-path) export PREFIX=$(pwd)/ios-arm64 ./configure \ --host=arm-apple-darwin \ --prefix=$PREFIX \ --disable-shared \ --enable-static \ --disable-doc \ --disable-extra-programs \ CFLAGS="-arch arm64 -isysroot $SDK_PATH -miphoneos-version-min=12.0" \ LDFLAGS="-arch arm64 -isysroot $SDK_PATH" make clean make -j4 make install这里--host=arm-apple-darwin是告诉 configure 脚本当前是一个 ARM 平台的交叉编译环境，-miphoneos-version-min=12.0是设定最低支持 iOS 12。如果你要支持更老的系统，可以改成 11.0，但要注意 Opus 编译产物对系统版本并没有强依赖，这里只是影响链接时的兼容性标记。
4.2 模拟器版本的坑：Intel和Apple Silicon都要覆盖
模拟器侧的情况要复杂一些。Intel Mac 上，模拟器架构是 x86_64；Apple Silicon Mac 上，模拟器架构是 arm64。所以严格来说，如果你想让团队里不同芯片的同事都跑得起来，模拟器版本需要同时准备 x86_64 和 arm64。
先编 x86_64 版本：
export SDK_PATH=$(xcrun --sdk iphonesimulator --show-sdk-path) export PREFIX=$(pwd)/ios-simulator-x86_64 ./configure \ --host=x86_64-apple-darwin \ --prefix=$PREFIX \ --disable-shared \ --enable-static \ --disable-doc \ --disable-extra-programs \ CFLAGS="-arch x86_64 -isysroot $SDK_PATH -mios-simulator-version-min=12.0" \ LDFLAGS="-arch x86_64 -isysroot $SDK_PATH"再编 arm64 模拟器版本，只需要把--host和 CFLAGS、LDFLAGS 里的架构改成arm64，SDK 路径仍然用iphonesimulator。
这里最容易踩的坑是：如果你试图用lipo -create把真机 arm64 和模拟器 arm64 合并成一个 fat 库，会直接报错fat file with duplicate architecture。原因很好理解，两个 arm64 架构代码相同，lipo 无法区分它们究竟属于哪个 SDK。这就是大家在老教程里没见过的新问题，老教程只合并了 arm64 真机 + x86_64 模拟器，绕过了重复架构。
4.3 推荐用XCFramework替代lipo合并
传统做法是用lipo -create -output把真机 arm64 和模拟器 x86_64 合并成一个 libopus.a。如果只考虑 Intel Mac 的模拟器，这样做完全够用。但如果团队里有人用 Apple Silicon 跑模拟器，模拟器 arm64 的存在会让 lipo 合并非常别扭。
所以我建议直接用 Xcode 的 XCFramework 打包方式，把三个版本分别放到独立目录里，然后用命令生成：
xcodebuild -create-xcframework \ -library ios-arm64/lib/libopus.a -headers ios-arm64/include \ -library ios-simulator-x86_64/lib/libopus.a -headers ios-simulator-x86_64/include \ -library ios-simulator-arm64/lib/libopus.a -headers ios-simulator-arm64/include \ -output Opus.xcframework这样做的好处是 Xcode 在构建时会自动根据当前运行目标选择对应架构的库，不存在重复架构的问题，而且头文件也一并打包好了，拖进项目就能用。
5. 贯穿两个平台的常见坑，以及我当年的排查链路
5.1 CMakeCache里残留宿主机构架
第一次在 Android 侧编译时，我在同一个 Source 目录里先用 CMake 编了 macOS 版本，然后又执行了 Android 的 CMake 命令，结果报出来的错误非常诡异，比如 clang 找不到 sysroot，或者链接 undefined symbols。
排查后发现问题出在 CMakeCache.txt 上。CMake 在已经生成缓存的情况下，默认不会重新判断系统名字和编译器，它会继续沿用第一次配置出的宿主工具链。解决办法很简单：每次切换目标平台时，一定要先删掉之前的 build 目录，或者使用完全独立的 build 目录，不要让 CMake 复用缓存。
5.2 iOS configure报出"C compiler cannot create executables"
这是 iOS 侧最典型的报错。很多人会在 configure 时直接用系统默认的 clang，然后指定--host=arm-apple-darwin，但并没有把-isysroot传给 CFLAGS。这时候 configure 试着编译一段测试代码并链接成一个可执行文件，因为目标平台是 iOS，但 sysroot 仍然是 macOS，链接器找不到 iOS 的系统库，就会直接报C compiler cannot create executables。
排查思路：检查 configure 生成的 config.log，你会看到 clang 报的错是 sysroot 不对。解决方式就是开头脚本里的-isysroot $SDK_PATH，必须显式指定。另外建议每次执行前用xcrun --show-sdk-path确认一下当前默认 SDK，如果是 macOS 而不是 iphoneos，说明你的 Xcode 当前选中的 SDK 类型不对。
5.3 路径里有空格导致 make install 失败
如果你的源码目录放在了带空格的路径下，比如/Users/me/My Project/opus，make install 时很有可能会出现奇怪的问题。configure 会把 prefix 里的路径写进头文件，如果路径里带空格又被引号处理不当，生成的opus_config.h会对不上实际路径。
排查链路的尽头也很普通：把整个 opus 源码目录重命名成没有空格的路径，重新 configure。这一点也许看起来过时，但团队里确实容易因为下载压缩包后默认文件夹名产生坑，提前避开最省事。
5.4 编译出的libraries太大，带了一堆无用符号
这个问题在 Android 和 iOS 上都会遇到。前面提过用llvm-strip可以处理 Android 的 so，iOS 侧则可以用 Xcode 自带的strip -x工具去弱符号。编译阶段也尽量加上-Os而不是默认的-O2，对 Opus 这种纯计算型库来说，-Os在绝大多数设备上不会造成可感知的性能损耗，但能显著减小产物体积。
我踩过一次更深的坑是发现自己编译的 arm64 静态库竟然包含 i386 的 slice。排查发现 configure 脚本在未指定 CFLAGS 时会自检出系统默认的架构，而当时 Xcode 默认的 ARCHS 配置比较混乱。后来我在 configure 之前加了export ARCHS=arm64，并且清空了环境变量里的CFLAGS、LDFLAGS，再重新执行，产物就干净了。
5.5 直接引用.so却找不到符号
Android 集成时还有一次，JNI 层调用 opus_encoder_create 会报UnsatisfiedLinkError。用nm -D查看 libopus.so，发现函数名变成了一堆没有导出符号的形态。原因是我在 CMake 里开启了OPUS_BUILD_SHARED_LIBS=ON之后，还额外设置了隐藏符号的编译参数，导致 so 里没有导出 opus 开头的公共 API。
Opus 默认的 CMake 配置会把必要的编解码 API 标记为导出属性，但如果你在 CFLAGS 里手动加入了-fvisibility=hidden且没有同时处理OPUS_EXPORT宏，就会出现"编译通过但链接失败"的诡异问题。所以尽量不要额外加隐藏可见性的参数，要加就要统一处理opus_export.h。
5.6 集成时libopus.a与工程里其他库冲突
iOS 工程里另一个比较常见的坑是，工程里如果原先已经有libopus.a（比如某个第三方 SDK 内置了一份），你再拖一份同名的静态库进去，链接器会随机选一个，很难排查到底跑的是哪个版本。我建议编译 iOS 时把产物改名为libopus_standalone.a，再配合 XCFramework 里的 header 路径使用，能避免这种同名冲突。
6. 编译完后建议立刻做的事：验证库确实可用
6.1 Android里用JNI做一个最小验证
拿到四个 so 之后，先在 Android Studio 工程里建一个最简单的 JNI 项目，只调用opus_get_version_string()，能返回字符串就说明 so 导入正常。接下来再跑一次完整的编码解码循环，用最原始的 PCM 数据，经过 Opus 编码再解码，比较输出数据能否和输入匹配。测试时可以故意不填充一帧完整的数据，比如只给 10ms 的音频，看返回码是不是符合预期，这样可以顺便验证库是不是真的支持短帧。我实际测过 Opus 对 2.5ms 到 60ms 帧的支持都很好，如果你的产品场景需要极低延迟，编译时无需额外开关，直接传够帧长即可。
6.2 iOS里用Swift的桥接验证
iOS 侧验证也很快。把 Opus.xcframework 拖进 Xcode 工程，然后在 target 的 Framework Search Paths 里指定正确路径，写一段 Objective-C++ 或 C 桥接代码调用opus_encoder_create。真正的验证重点在于检查模拟器和真机分别运行一次。在模拟器上运行时，Xcode 会自动选用 simulator 对应的架构，在真机上跑会选用真机架构，能跑通就说明 XCFramework 里的架构分离是正确的。如果遇到library not found for -lopus之类的错误，先去 Build Settings 里看 Library Search Paths 有没有被 Xcode 自动添加，没有就手动加。
6.3 对比官方工具链验证压缩率
最后我还会用 ffmpeg 里的opusenc或者官方提供的opus_demo工具做一次横向对比。找个十几秒的 WAV 文件，分别用系统自带的 Opus 编码工具和移动端刚编译出的库去编码，对比输出文件的大小和码率。Opus 编码器是确定性算法，理论上相同码率配置下，输出文件应该几乎一致，如果发现差异很大，就要回头检查编译参数是否开启了--enable-intrinsics或者fixed-point这些影响编码结果的选项。
7. 我压缩成本的一套定制脚本思路
上面这些步骤你都可以手动执行，但如果要交付给团队，我更建议把 Android 和 iOS 的编译流程统一封装成一套脚本，放到一个单独的仓库里。不要直接把配置写在项目工程里，否则每次换人、换电脑都要重新踩一遍环境变量的问题。
一个很实用的做法是，在 Opus 源码目录外面建一个build/文件夹，里面集中放build-android.sh、build-ios.sh、build-ios-xcframework.sh，统一通过一个Makefile来触发。每次升级 Opus 版本时，只需要改脚本里的OPUS_TAG变量，然后依次执行make android和make ios，就能在dist/下看到最终产物。这样可以把所有坑都固化成流程，而不是靠某个人脑子里的经验。我自己后来在带团队时，还会要求把最终产物连同opus_config.h、opus_version.h一起归档，因为这些头文件内容会因为编译参数不同而变化，只留 .a 或 .so 不带头文件，下次接 SDK 的人一定会在类型映射上再卡一次。
8. 最后一个经验之谈
Opus 编译这件事，本质上并没有特别高深的技术难点，它考验的是对交叉编译流程的熟悉程度和对细节的敏感度。我第一次编的时候也绕了很多弯路，尤其是 iOS 用 CMake 踩了半天的架构坑，换成 configure 脚本之后顺利很多。后来帮别人排查问题时发现，几乎所有人都卡在那几个同样的点上：CMakeCache 没有清理、sysroot 指错、模拟器 arm64 被 lipo 拒绝、产物没 strip 导致包太大。如果你已经看完前面这些内容，我相信你避开这些坑是完全没有问题的，剩下就只需要静下心来把脚本跑一遍，拿一个真实音频文件测试一次，你对整个链条的掌控感就完全不一样了。
本文还有配套的精品资源，点击获取
