linux版本

项目源码： https://github.com/litongjava/java-native-media

---

一、问题现象

应用启动时报错：

os name: linux user.home: /root
Detected FFmpeg ABI: 58
copy from /lib/linux_amd64/libnative_media_av58.so to /root/lib/linux_amd64/libnative_media_av58.so
Resource does not exist: /lib/linux_amd64/libnative_media_av58.so
Loading native: /root/lib/linux_amd64/libnative_media_av58.so

Exception in thread "main" java.lang.reflect.InvocationTargetException
Caused by: java.lang.UnsatisfiedLinkError: Can't load library: /root/lib/linux_amd64/libnative_media_av58.so

---

二、问题根因

1）应用内置的 native 库依赖 FFmpeg 59

检查 .so 依赖：

readelf -d /root/lib/linux_amd64/libnative_media_av59.so | grep NEEDED

输出：

Shared library: [libavformat.so.59]
Shared library: [libavcodec.so.59]
Shared library: [libswresample.so.4]
Shared library: [libswscale.so.6]
Shared library: [libavutil.so.57]
Shared library: [libavfilter.so.8]

说明该库是 按 FFmpeg 5.x (ABI 59) 编译的

---

2）服务器实际安装的是 FFmpeg 4.x（ABI 58）

ldconfig -p | grep libavformat

输出：

libavformat.so.58 => /lib/x86_64-linux-gnu/libavformat.so.58

---

3）ldd 验证动态链接失败

ldd /root/lib/linux_amd64/libnative_media_av59.so

输出：

libavformat.so.59 => not found
libavcodec.so.59 => not found
libswresample.so.4 => not found
libswscale.so.6 => not found
libavutil.so.57 => not found
libavfilter.so.8 => not found

---

结论

项目	版本
native 库	FFmpeg 59
系统 FFmpeg	FFmpeg 58
结果	动态链接失败

因此 JVM 无法加载 .so 文件，触发：

java.lang.UnsatisfiedLinkError

---

三、java-native-media 的加载机制

库启动时会：

1. 检测系统 FFmpeg ABI
2. 自动选择对应 native 库

日志：

Detected FFmpeg ABI: 58
Loading native: libnative_media_av58.so

但 jar 包内只带 av59，没有 av58：

Resource does not exist: /lib/linux_amd64/libnative_media_av58.so

因此加载失败。

---

四、解决方案

有三种方案：

方案	推荐度	说明
升级系统 FFmpeg 到 59	⭐⭐	影响系统组件
静态链接 FFmpeg	⭐⭐	编译复杂
按服务器版本编译 native	⭐⭐⭐⭐	最安全

推荐：为服务器编译 av58 版本 native 库

---

五、编译适配服务器的 native 库

1）准备环境

Ubuntu / Debian：

sudo apt install build-essential -y
sudo apt-get install nasm -y
sudo apt-get install pkg-config -y
sudo apt install cmake -y
sudo apt-get install libavcodec-dev libavformat-dev libavutil-dev libavfilter-dev libswresample-dev libmp3lame-dev -y

确认版本：

ffmpeg -version

应包含：

libavformat 58.x

安装java

mkdir /opt/package/java -p &&cd /opt/package/java 
wget https://github.com/litongjava/oracle-jdk/releases/download/8u411/jdk-8u411-linux-x64.tar.gz
wget https://gitcode.com/ppnt/oracle-jdk/releases/download/8u411/jdk-8u411-linux-x64.tar.gz
mkdir /usr/java/ -p
tar -xf jdk-8u411-linux-x64.tar.gz -C /usr/java
export JAVA_HOME=/usr/java/jdk1.8.0_411
export JAVA_HOME=/usr/java/jdk1.8.0_411

---

2）下载源码

git clone https://github.com/litongjava/native-media.git
cd native-media

---

3）编译

编译

cmake -S . -B cmake-build-release -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build-release --target all

编译成功后生成：

libnative_media.so

---

六、部署 native 库

创建运行目录：

mkdir -p /root/lib/linux_amd64/

复制编译产物：

cp cmake-build-release/libnative_media.so /root/lib/linux_amd64/libnative_media_av58.so

权限：

chmod 755 /root/lib/linux_amd64/libnative_media_av58.so

---

七、验证

重新启动服务：

Detected FFmpeg ABI: 58
Loading native: /root/lib/linux_amd64/libnative_media_av58.so

若无 UnsatisfiedLinkError，说明成功。

---

八、原理总结

为什么不能跨 ABI 使用？

FFmpeg 每个大版本都会改变：

• 结构体大小
• 函数签名
• 枚举值
• 内存布局

例如：

ABI	FFmpeg
57	FFmpeg 3
58	FFmpeg 4
59	FFmpeg 5
60	FFmpeg 6

native 库是 强绑定 ABI 的

因此：

libnative_media_av59.so ≠ 可在 ffmpeg58 上运行

---

九、最佳实践建议

生产环境建议：

1）构建阶段与运行环境一致

Docker 构建示例：

构建机 FFmpeg版本 == 服务器 FFmpeg版本

否则必然出现 JNI 加载失败。

---

2）将 native 编译纳入 CI

建议：

CI 为每种 Linux 发行版编译对应 so

例如：

libnative_media_av58_ubuntu20.so
libnative_media_av59_ubuntu22.so

---

3）不要依赖 jar 内置 native

原因：

• Linux 发行版 FFmpeg 版本差异极大
• 云服务器经常是旧版 LTS

应改为：

启动时优先加载外部 native

---