10分钟打通FFmpeg构建镜像FFmpeg-Builds编译配置核心 vars.sh 全解析【免费下载链接】FFmpeg-Builds项目地址: https://gitcode.com/gh_mirrors/ff/FFmpeg-Builds./makeimage.sh linux64 GPL报出Invalid target/variant日志只有一行看不出参数在哪一步被判死。这个错误源头是 FFmpeg-Builds 编译配置的总入口 util/vars.sh全文 148 行。读完你能独立回答三个问题一组参数会生成什么镜像标签、版本号插件如何切换源码分支、以及如何把你的自定义链接选项注入最终 Dockerfile。 util/vars.sh 在项目里的位置命令行到 Dockerfile 的翻译层这个文件是整个构建流程中唯一的参数解析层。三个入口脚本 makeimage.sh、generate.sh、download.sh 的第一件事都是source util/vars.sh随后依赖它导出的变量TARGET、VARIANT、ADDINS、IMAGE、FFVER等。它本身不写一行 Dockerfile——generate.sh 里每条to_df写入的内容都引用它定义的变量。可以把它理解成契约命令行参数在这被翻译成镜像标签 编译选项串scripts.d 和 variants 下的上百个脚本全部依赖这份契约工作。 如何指定目标架构TARGET 与 VARIANT 的双重校验TARGET 和 VARIANT 是前两个必传参数二者拼接成的文件名必须真实存在否则直接退出。问题背景项目覆盖 linux64/win64/arm64 等 7 种架构每种又分 gpl/lgpl/nonfree 与 static/shared 共 6 种变体合法组合超过 40 个。vars.sh 用文件是否存在代替硬编码白名单TARGET$1 VARIANT$2 shift 2 if ! [[ -f variants/${TARGET}-${VARIANT}.sh ]]; then echo Invalid target/variant exit -1 fi校验即文档variants/ 目录里有什么组合就支持什么组合新增变体无需改动本文件。如果你要改它注意变体文件的写法是两行 sourcesource $(dirname $BASH_SOURCE)/linux-install-static.sh source $(dirname $BASH_SOURCE)/defaults-gpl.sh打包方式和协议选项被拆成正交维度defaults-gpl.sh 里才真正写着--enable-gpl --enable-version3。不要把选项塞进单一文件否则 shared 版本会互相污染。 addin 插件机制命令行参数如何变成镜像标签第 3 个及之后的参数都是 addin每个必须对应 addins/ 下同名脚本按传入顺序拼进镜像标签。版本号分支、debug 符号、LTO 都是正交需求写死在主流程里会让参数组合爆炸。vars.sh 的做法ADDINS() ADDINS_STR while [[ $# -gt 0 ]]; do [[ -f addins/${1}.sh ]] || { echo Invalid addin: $1; exit -1; } ADDINS( $1 ) ADDINS_STR${ADDINS_STR}${ADDINS_STR:-}$1 shift done IMAGE${REGISTRY}/${REPO}/${TARGET}-${VARIANT}${ADDINS_STR:-}${ADDINS_STR}:latest${ADDINS_STR:-}保证第一个 addin 前不多出连字符。addins/8.0.sh 全文只有一行GIT_BRANCHrelease/8.0却同时影响源码分支和标签后缀。镜像标签命名规则最终标签 registry 仓库 TARGET-VARIANT 连字符拼接的全部 addin :latest。例如linux64 gpl 8.0 debug得到ghcr.io/btbn/ffmpeg-builds/linux64-gpl-8.0-debug:latest。仓库前缀取GITHUB_REPOSITORY环境变量缺省 btbn/ffmpeg-buildsregistry 取REGISTRY_OVERRIDE缺省 ghcr.io。如果你要改它注意 addin 的传入顺序只影响标签不影响逻辑——generate.sh 对每个 addin 在独立子 shell 里 source互不干扰。️ FFmpeg 版本选择ffbuild_ffver 的版本码映射ffbuild_ffver 从 ADDINS_STR 反推出数字版本码未传版本 addin 时返回 99999999代表 master 最新。generate.sh 要把 FFVER 写进镜像 ENV下游阶段脚本用它做新旧分支的选项兼容判断ffbuild_ffver() { case $ADDINS_STR in *7.0*) echo 700 ;; *7.1*) echo 701 ;; *8.0*) echo 800 ;; *8.1*) echo 801 ;; *9.0*) echo 900 ;; *) echo 99999999 ;; esac }99999999 大于任何发行版本号下游用[[ $FFVER -gt 700 ]]这类比较即可判断新旧不需要字符串解析。如果你要改它注意匹配对象是拼接后的 ADDINS_STR8.0 debug同样命中*8.0*。新增版本 addin 时必须同步补一个 case 分支否则会静默落入默认分支、被当成最新版编译。 如何注入自定义编译选项12 个钩子函数vars.sh 末尾定义了 12 个空钩子configure/unconfigure、cflags/uncflags、cxxflags/uncxxflags、ldexeflags/unldexeflags、ldflags/unldflags、libs/unlibsgenerate.sh 汇总各依赖的输出后写进镜像。问题背景每个依赖包要向 FFmpeg 主 configure 贡献几个选项行又不允许改 FFmpeg 源码。以 scripts.d/50-x264.sh 为例ffbuild_configure() { echo --enable-libx264; } ffbuild_unconfigure() { echo --disable-libx264; } ffbuild_enabled() { [[ $VARIANT lgpl* ]] return -1 return 0 }generate.sh 侧的汇总逻辑for SCRIPT in ${SCRIPTS[]}; do FF_CONFIGURE $(get_output $SCRIPT configure) FF_CFLAGS $(get_output $SCRIPT cflags) FF_LIBS $(get_output $SCRIPT libs) done启用的包调ffbuild_configure被禁用的包调ffbuild_unconfigure——这正是 lgpl 镜像没有 x264 的机制enabled 检查返回失败汇总进选项串的反而是--disable-libx264。如果你要改它注意钩子只负责 echo 字符串、不执行构建逻辑构建在各脚本的 ffbuild_dockerbuild 里。想加一个--extra-libs就在对应脚本的 ffbuild_ldflags 里加一行 echovars.sh 的空实现保证任何脚本被 source 时函数都有定义不会报未定义。组合演练三条命令覆盖全部入口在仓库根目录clone 地址https://gitcode.com/gh_mirrors/ff/FFmpeg-Builds依次执行./generate.sh linux64 gpl 8.0 debug # 只生成 Dockerfile不构建 ./makeimage.sh win64 nonfree 7.1 # 完整流程基础镜像→下载→Dockerfile→最终镜像 ./download.sh # 仅预下载全部依赖源码到 .cache/downloads参数产物 / 效果linux64 gpl选项含--enable-gpl --enable-version3静态链接基于 base-linux64 镜像8.0GIT_BRANCHrelease/8.0FFVER800标签后缀-8.0debug追加--optflags-Og --disable-stripping产物体积约增加 250MB不传版本 addinFFVER99999999从 master 最新编译lgpl变体x264/x265 被主动禁用最终 ffmpeg 无 libx264 编码器避坑清单现象Invalid target/variant。原因大小写或分隔符与文件名不符文件是variants/linux64-gpl.shGPL、gpl_shared都失败。处理ls variants/后逐字符对照。现象最终镜像ffmpeg -encoders查不到 libx264。原因变体是 lgpl*50-x264.sh 的 ffbuild_enabled 拒绝启用汇总进选项的是--disable-libx264。处理换 gpl 或 nonfree 变体。现象镜像 ENV 里 FFVER 是 99999999疑似异常。原因没传版本 addin该值就是master 最新的正常表示。处理需要固定发布分支就补传8.0之类参数。现象镜像标签前缀不是 ghcr.io/btbn/ffmpeg-builds。原因设置了GITHUB_REPOSITORY或REGISTRY_OVERRIDEvars.sh 优先取环境变量。处理执行前env | grep -E GITHUB_REPOSITORY|REGISTRY确认。vars.sh 本身不做任何编译它是把命令行三组参数翻译成镜像标签与选项串的契约下游所有脚本都在履行这份契约。延伸阅读README.mdtargets/variants/addins 完整清单与官方构建保留策略scripts.d/50-x264.sh单个依赖从构建到钩子的完整范例makeimage.sh从基础镜像到最终镜像的 buildx 构建流程【免费下载链接】FFmpeg-Builds项目地址: https://gitcode.com/gh_mirrors/ff/FFmpeg-Builds创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考