近期我参与了部门底层库依赖的 FFmpeg 从 3.4 升级至 7.0.2 的工作，在此分享一些经验和遇到的 API 变动。
将 FFmpeg 升级到高版本后，编译过程中遇到大量报错是常态。这些错误通常源于 API 接口变更或结构体字段调整。此时不必惊慌，核心解决思路是将报错的接口或用法适配到新版本。
如何快速准确地找到新版本中的对应替代方案？ 以下是我找到的一些方法：
-
FFmpeg 官方文档 ：查找任何 API 用法和参数说明的最权威来源。
-
FFmpeg 废弃 API 文档：这是解决升级问题的有效资源。文档详细列出了当前版本（如 7.0）相比旧版本废弃的 API、结构体成员、宏等，并且明确指明了应该使用的新接口或替代方案。
-
互联网搜索与 AI 辅助：如果在官方文档中没有找到直接的答案（特别是对于一些隐晦的变更或行为差异），搜索引擎和开发者社区（Stack Overflow 等）是重要的补充。像 DeepSeek 这类 AI 助手也是高效的查询工具，能快速提供可能的替代方案或解释变更背景。
-
源码探索（最后手段）：如果以上途径都未能解决问题（这种情况极少遇到），最后的办法是深入源码。主要思路是先定位旧版本中相关 API/结构体的源码实现，然后在高版本 FFmpeg 源码的对应位置（或通过搜索相关功能关键词），查看新版本是如何实现相同功能的。这需要一定的源码阅读能力。
在完成本次升级后，我整理了遇到的一些API变动。以下表格概述了这些变更及其影响/替代方案（详细说明请参考官方文档和废弃列表）：
| 变更类型 | 旧版 API/字段 | 新版 API/字段 | 备注/参考 |
|---|---|---|---|
| Packet 初始化 | av_init_packet |
av_packet_alloc（内部调用 get_packet_defaults） |
参考 |
| 帧时间戳字段 | AVFrame::pkt_pts |
AVFrame::pts |
参考 |
| 编解码器参数类型 | AVCodec* |
const AVCodec* |
高版本函数普遍使用 const 修饰符 |
| 全局注册函数 | av_register_all |
自动注册 | 输入输出设备仍需 avdevice_register_all() 参考 |
| 声道布局表示 | channels 字段 |
ch_layout 结构体 |
更精确的声道描述方式 |
| 音频重采样上下文创建 | swr_alloc_set_opts |
swr_alloc_set_opts2 |
统一接口，支持更多参数 |
| 内存分配函数 | av_mallocz_array |
av_calloc |
参考 |
| 内存管理头文件 | <libavutil/mem.h> |
内部实现 （mem_internal.h） |
不再作为公共头文件导出 |
| 解复用器遍历 | 旧版迭代方式 | av_demuxer_iterate |
MLT 框架适配示例 参考 |
| 音频重采样接口 | audio_resample |
swr_convert |
参考 |
| 流创建参数 | avformat_new_stream 的 codec 参数 |
无效 | 参考 |
| 解码接口 | avcodec_decode_video2/audio4 |
avcodec_send_packet + avcodec_receive_frame |
参考 |
| 索引访问方式 | AVStream::nb_index_entries/index_entries |
avformat_index_get_entries_count() + avformat_index_get_entry() |
参考 |