1. 项目概述：Spring Boot 3与FFmpeg能碰撞出什么

视频处理在业务系统里的权重越来越高，从用户上传的视频转码、封面截图、水印叠加，到内容平台的HLS切片、多码率自适应，几乎每个系统都会遇到“要不要自己处理视频”的问题。直接让用户上传原片给前端播放，不仅加载慢，兼容性也差；丢给第三方云服务，又涉及成本、数据合规和接口耦合。所以“本地自建一套视频处理服务”是很多团队都会走的路，而Spring Boot 3 + FFmpeg的组合，正是这条路上最务实、最灵活的一套方案。

这篇内容适合谁看？适合那些已经在用Spring Boot做后端、突然接到“帮视频加个封面”“把上传的视频转成mp4”“把m3u8下载下来”这类需求的开发同学，也适合想在自己项目里集成视频处理能力但不想被云厂商绑定的团队。我会把从FFmpeg安装、Spring Boot工程配置、核心功能实现，到各种疑难杂症的排查思路全都过一遍，尽量做到“看完就能照着落地”。

先聊一下核心技术栈：Spring Boot 3用的是Jakarta EE 9+规范，JDK要求17起步，整体是一个标准Web应用；FFmpeg则是命令行层的视频处理引擎，两者之间通过Java的ProcessBuilder建立通道，Java负责调度、传参、接收输出，FFmpeg负责具体的编解码、滤镜、封装工作。这种“Java管流程、FFmpeg管处理”的模式，拆得干净，也最容易排查问题。接下来我从项目设计讲起，一步步带你把这个能力搭起来。

2. 方案选型：为什么是“Java + 命令行FFmpeg”而不是其他库

2.1 几个常见的Java集成视频处理方案对比

做Java视频处理，业界常见的有三条路线：全Java实现的库、JavaCV封装FFmpeg API、直接用ProcessBuilder调FFmpeg命令行。我先说结论：如果追求稳定和长期可维护性，我推荐第三条路。

第一类全Java库，比如JCodec，优点是零外部依赖、纯JVM运行，部署简单。但缺憾很明显——支持的编码格式少得可怜，H.264解码都是半残状态，HEVC（H.265）几乎不可用，封装格式也就MP4、MOV这些基础款。你一旦遇到“把TS流转成MP4”“从视频里抽取某个音轨”“给视频加字幕滤镜”这类需求，基本就是巧妇难为无米之炊。

第二类JavaCV，它是对FFmpeg原生接口的Java封装，能力非常强，能做流级别的精细控制，是在Java里做视频实时处理、目标检测、流分析时的好选择。但它的问题是学习曲线陡：你需要理解AVFormatContext、AVPacket、AVFrame这一整套C语言的抽象概念，项目依赖体积也大，因涉及JNI调用，排起错来还得看native层的日志。

第三类ProcessBuilder调命令行，是我最常用的方案。它绕开了JNI和C语言抽象，直接把FFmpeg当外部进程来调度。优点是逻辑清晰、调试方便、FFmpeg升级不影响Java代码、遇到问题可以直接在终端里先跑一遍命令确认是FFmpeg本身的问题还是Java调用的问题。缺点也很实在：进程管理和并发控制需要自己做，但放在Spring Boot里用线程池包一层，完全够用。

方案	优点	缺点	适用场景
全Java库（JCodec）	无外部依赖、部署简单	编码格式支持有限	简单的格式转换、图像处理
JavaCV	功能全面、支持流级处理	学习成本高、JNI排错复杂	实时流分析、复杂视频处理
ProcessBuilder + FFmpeg	灵活、易调试、可控性强	需要管理进程与并发	大多数线上业务视频处理需求

2.2 为什么Spring Boot 3这个组合值得用

Spring Boot 3相比2.x最大的变化有两个：一是JDK 17+的基线，虚拟线程在17里已经可以体验，处理耗时型IO任务时能显著提升吞吐；二是Jakarta命名空间的迁移，很多老依赖都需要换坐标。如果项目从零开始，直接用Spring Boot 3是最省心的，因为新生态的依赖兼容性问题已经被社区趟平了。

回到视频处理场景，Spring Boot的价值在“调度层”：任务下发、状态记录、队列控制、接口暴露都需要一个Web容器和业务框架来承接。FFmpeg是“执行层”，干的是真正的转码、截图、切片。两层之间通过命令行参数沟通，这也意味着Spring Boot代码里几乎不需要引入任何与视频编码相关的依赖，Java侧只负责拼命令、起进程、消费输出流，架构上非常干净。

这套方案最核心的竞争力在于“出问题能定位”。比如FFmpeg转码失败，终端直接跑一遍原命令就能看到明确报错；编码器不支持，那就换参数；路径权限不对，看日志就能发现。换成JavaCV，同样的报错你可能要在JNI栈和native logs里翻半天。对于业务团队来说，省下来的排查时间非常可观。

3. 环境准备：FFmpeg安装与Spring Boot工程初始化

3.1 FFmpeg安装：Windows、Linux各来一遍

先做开发环境。Windows下最简单的安装方式是用官方编译好的静态包，不需要自己编译源码。去FFmpeg官网下载页找到“Windows Builds”入口，选release build，解压后把bin目录加到PATH环境变量里即可。装完在cmd里执行：

ffmpeg -version

能打印版本号就说明装好了。要注意的是，Windows路径有空格的话，Java传参时要额外处理引号，建议把ffmpeg.exe放到一个纯英文无空格的目录下，能避开很多坑。

生产环境常见的是Linux，以CentOS 7为例，我自己踩过一个坑：yum源里的ffmpeg版本老得离谱，装出来连libx264都不支持。最稳妥的做法是加一个RPM Fusion源：

sudo yum install epel-release
sudo rpm -Uvh https://mirrors.tuna.tsinghua.edu.cn/rpmfusion/free/el/rpmfusion-free-release-7.noarch.rpm
sudo yum install ffmpeg

装完验证一下编码器支持情况：

ffmpeg -encoders | grep 264

能看到libx264输出，说明转码能力齐全。如果你需要更完整的支持，比如H.265、AAC音频、RTSP拉流，建议从John Van Sickle的静态构建包下载，解压到 /usr/local/ffmpeg 并把bin目录软链到PATH里。这种方式的好处是静态编译把所有需要的库都打进去了，不会遇到动态链接缺失的问题。

还有一类场景是容器化部署，Dockerfile里直接这样写：

FROM maven:3.8.4-openjdk-17 AS build
WORKDIR /app
COPY . .
RUN mvn clean package -DskipTests

FROM openjdk:17-jdk-slim
RUN apt-get update && apt-get install -y ffmpeg
COPY --from=build /app/target/*.jar /app/app.jar
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

这是最省事的方案，镜像里带好FFmpeg，应用启动直接可用。部署到K8s时也不用额外初始化容器。

3.2 Spring Boot 3工程基础结构

创建工程有两种方式：直接用Spring Initializr网站生成，或者用IDEA的Spring Boot项目向导。关键点是JDK选17+、Spring Boot版本选3.x（当前比较普及的稳定版是3.1/3.2）。依赖方面，基础Web、Lombok、Configuration Processor就够了，视频处理不需要额外引入专门的starter。

工程结构我习惯按功能模块分：

com.example.videoprocess
├── controller        // HTTP接口层
├── service           // 业务逻辑层
├── config            // 配置类
├── dto               // 入参出参对象
└── util              // FFmpeg命令封装工具

配置类里定义FFmpeg路径和一些默认参数：

video:
  ffmpeg-path: /usr/local/bin/ffmpeg
  ffprobe-path: /usr/local/bin/ffprobe
  temp-dir: /tmp/video-process
  result-dir: /data/video-output
  timeout-seconds: 1200

这里重点说一下为什么需要temp-dir。FFmpeg处理大视频时会产生大量临时文件，如果直接用系统默认的/tmp，可能因为目录空间不足或清理策略导致任务失败。建议单独指定一个有容量保障的目录，比如挂载独立数据盘。同时，处理完的临时文件在finally块里必须清理，否则时间长了能把磁盘写满。

3.3 核心配置类与FFmpeg命令封装

配置类负责读取上述配置项：

@ConfigurationProperties(prefix = "video")
@Data
public class VideoProperties {
    private String ffmpegPath;
    private String ffprobePath;
    private String tempDir;
    private String resultDir;
    private int timeoutSeconds = 1200;
}

主类加上 @EnableConfigurationProperties(VideoProperties.class) 启用配置绑定。

接下来我封装一个通用的命令执行器，这一步是整个集成的基础。核心逻辑是：接收一个命令列表，用ProcessBuilder启动进程，异步读取标准输出和错误输出，等待进程结束时返回结果。注意，必须异步读取输出流，否则当输出数据量较大时，管道缓冲区满了会导致进程阻塞，job就卡死在那里了。

@Component
@Slf4j
public class FfmpegCommandRunner {
    
    @Resource
    private VideoProperties videoProperties;
    
    @Resource
    private ThreadPoolTaskExecutor taskExecutor;
    
    public ExecResult execute(List<String> command) {
        return execute(command, videoProperties.getTimeoutSeconds());
    }
    
    public ExecResult execute(List<String> command, long timeoutSeconds) {
        ProcessBuilder builder = new ProcessBuilder(command);
        builder.redirectErrorStream(false);
        long start = System.currentTimeMillis();
        try {
            Process process = builder.start();
            // 异步读取输出，避免管道阻塞
            CompletableFuture<String> stdoutFuture = readStream(process.getInputStream());
            CompletableFuture<String> stderrFuture = readStream(process.getErrorStream());
            boolean finished = process.waitFor(timeoutSeconds, TimeUnit.SECONDS);
            if (!finished) {
                process.destroyForcibly();
                throw new RuntimeException("FFmpeg命令执行超时: " + command);
            }
            int exitCode = process.exitValue();
            String stdout = stdoutFuture.get(10, TimeUnit.SECONDS);
            String stderr = stderrFuture.get(10, TimeUnit.SECONDS);
            return new ExecResult(exitCode, stdout, stderr);
        } catch (Exception e) {
            throw new RuntimeException("FFmpeg命令执行异常", e);
        }
    }
    
    private CompletableFuture<String> readStream(InputStream inputStream) {
        return CompletableFuture.supplyAsync(() -> {
            try (BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream, StandardCharsets.UTF_8))) {
                StringBuilder sb = new StringBuilder();
                String line;
                while ((line = reader.readLine()) != null) {
                    sb.append(line).append(System.lineSeparator());
                }
                return sb.toString();
            } catch (IOException e) {
                return "";
            }
        }, taskExecutor);
    }
}

线程池的配置也很关键。视频转码是CPU密集+IO密集的混合场景，线程数不建议直接照搬默认值。我一般用 core=2、max=8、queue=50 ，队列满时的拒绝策略选CallerRunsPolicy，这样能防止任务积压时直接丢弃请求，只是处理速度会下降但至少保证每个任务都被执行。

4. 核心功能实现：转码、截图、抽音轨、m3u8转MP4

4.1 视频转码：从MP4到HLS切片，兼顾兼容性

视频转码是最高频的需求。最基础的是“把用户上传的任意格式变成MP4（H.264 + AAC）”，这个组合是浏览器播放兼容性最好的选择。命令如下：

ffmpeg -y -i input.avi -c:v libx264 -c:a aac -pix_fmt yuv420p output.mp4

这里几个参数值得说清楚： -c:v libx264 指定视频编码器； -c:a aac 指定音频编码器； -pix_fmt yuv420p 是为了处理某些源视频像素格式（比如yuv444）在部分播放器上黑屏的问题。 -y 表示输出文件已存在时直接覆盖，如果你不自动覆盖，命令会停下来等待交互输入，在Java进程里那就是死等。

Spring Boot侧代码实现：

public MediaProcessResult convertToMp4(String sourcePath, String targetPath) {
    List<String> command = new ArrayList<>();
    command.add(properties.getFfmpegPath());
    command.add("-y");
    command.add("-i");
    command.add(sourcePath);
    command.add("-c:v");
    command.add("libx264");
    command.add("-c:a");
    command.add("aac");
    command.add("-pix_fmt");
    command.add("yuv420p");
    command.add(targetPath);
    ExecResult result = ffmpegCommandRunner.execute(command);
    if (result.getExitCode() != 0) {
        throw new VideoProcessException("转码失败: " + result.getStderr());
    }
    return new MediaProcessResult(targetPath, calculateDuration(sourcePath));
}

再进一步，如果要做HLS切片，为流媒体播放准备多码率分段文件，命令变成了：

ffmpeg -y -i input.mp4 -c:v libx264 -c:a aac -hls_time 10 -hls_list_size 0 -f hls output.m3u8

-hls_time 10 表示每个TS分片大约10秒， -hls_list_size 0 是让播放列表包含所有分片而不只保留最近几个。生产上如果要做多码率自适应，还需要额外生成不同分辨率的变体m3u8，并配置Master Playlist，这属于播放器侧的细节，但FFmpeg侧准备好分片后，用一套nginx的HTTP服务就能搭起一个私有化点播平台。

4.2 视频截图：从指定时间点抽帧选封面

视频截图是“获取视频封面”功能的核心，命令很简单，但藏着一个高频坑。最常看到新手写：

ffmpeg -i input.mp4 -vframes 1 output.jpg

这种写法默认截的是第0帧，也就是视频第一帧，很多视频的第一帧是黑屏或模糊的，出来的封面很难看。正确姿势是加 -ss 参数指定时间点：

ffmpeg -ss 00:00:10 -i input.mp4 -vframes 1 -q:v 2 output.jpg

这里 -ss 放在 -i 前面会启用“输入定位”模式，FFmpeg会先跳转到指定时间附近再开始解码，速度极快；放在 -i 后面则会先解码再丢弃帧，虽然精确但速度慢。对于批量截图场景， -ss 放在前面几乎总是更好的选择，除非你对那一帧的精确度有变态要求。

还有网友问过“ -vframes:v 1 与 -vframes 1 有什么区别”——这是之前某个流程里常见的错误写法。 -vframes 就是一个选项，不需要再带 :v 后缀。FFmpeg选项格式里带 :v 的通常是滤镜参数（比如 -vf 后的表达），混用时容易报错“the specified filename does not exist”。如果你确实在截图时遇到这个报错，请检查命令的最后一个参数是不是输出文件路径，并且确认中间没有把 -vframes 1 误放到输出的位置后面。

Java侧封装一个通用截图方法：

public String captureFrame(String inputPath, String outputDir, double seconds) {
    String timeStr = formatTime(seconds);
    String outputPath = outputDir + File.separator + UUID.randomUUID() + ".jpg";
    List<String> command = List.of(
        properties.getFfmpegPath(),
        "-ss", timeStr,
        "-i", inputPath,
        "-vframes", "1",
        "-q:v", "2",
        outputPath
    );
    ExecResult result = ffmpegCommandRunner.execute(command);
    if (result.getExitCode() != 0) {
        throw new VideoProcessException("截图失败: " + result.getStderr());
    }
    return outputPath;
}

-q:v 2 是JPEG的品质控制参数，范围1-31，数值越小质量越高。一般2-5之间目视差异不大，但文件体积差很多，按业务需求选。

4.3 音视频抽取与拼接

音视频抽取是另一个实用功能，比如从视频中提取音频用于语音识别或指纹匹配：

ffmpeg -i input.mp4 -vn -c:a libmp3lame output.mp3

-vn 表示不处理视频流，只保留音频； -c:a libmp3lame 是MP3编码器。如果你想保留原始音频格式不转码，用 -c:a copy ，速度快但输出格式得和源格式兼容。比如源文件音轨是AAC，输出MP3容器里放AAC是播放器不认的，必须转码。同样的逻辑，从视频里抽取视频流不带音频：

ffmpeg -i input.mp4 -an -c:v copy output.mp4

拼接场景：把多个MP4拼成一个视频，如果分段视频的编码参数完全一致，可以用：

ffmpeg -f concat -safe 0 -i filelist.txt -c copy merged.mp4

filelist.txt的内容格式：

file 'part1.mp4'
file 'part2.mp4'
file 'part3.mp4'

-c copy 意思是流拷贝，不重新编码，速度接近实时十倍以上。但前提是源视频的编码器、分辨率、帧率、像素格式必须一致，否则拼接处会出现花屏、音画不同步。如果不一致，只能老老实实重新编码：

ffmpeg -i part1.mp4 -i part2.mp4 -filter_complex "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1" -c:v libx264 -c:a aac merged.mp4

这个命令里 -filter_complex 的concat滤镜会把两个输入的视频流和音频流按顺序拼接起来， n=2 表示两个输入段。如果拼接后的视频有音画不同步问题，常见原因在于源视频的起始时间戳不为0，可以先加 -fflags +genpts 或者用 -avoid_negative_ts make_zero 来校准时间戳。

4.4 m3u8转MP4：处理网络流传的直播/点播回放

m3u8转MP4是另一个被高频搜索的热门场景。m3u8本质是一个播放列表文件，里面记录了分片TS文件的路径。FFmpeg直接支持读取这种文件：

ffmpeg -i https://example.com/playlist.m3u8 -c copy output.mp4

如果m3u8的TS分片是加密的（通常会带 #EXT-X-KEY 标签），就需要确认密钥是否能被FFmpeg自动读取，网络上的公开m3u8通常不带加密，但内部系统里的回放文件可能有加密。对于加密源，FFmpeg需要知道密钥文件的位置，或者使用HTTP请求头携带token。如果是后者，需要在m3u8文件所在目录放一个key文件，或者在URL里直接拼接参数。这个在公开课里属于进阶玩法，实际落地时最好和流媒体服务器团队确认一下鉴权方式。

Java侧处理网络m3u8时，需要注意网络超时和重试。FFmpeg默认遇到网络抖动会失败退出，可以用 -rw_timeout 和 -timeout 参数延长网络等待：

ffmpeg -rw_timeout 30000000 -i https://example.com/playlist.m3u8 -c copy output.mp4

-rw_timeout 单位是微秒，30000000微秒约等于30秒，30000毫秒是30秒，注意别把单位搞混了。如果你在任务执行中看到大量 Connection timed out 报错，优先检查网络策略和超时参数的设置。

4.5 视频添加文字水印与渐隐效果

水印场景分为两类：一类是图片水印，如品牌LOGO；一类是文字水印，在视频上叠加标题或跑马灯。图片水印用overlay滤镜：

ffmpeg -i input.mp4 -i logo.png -filter_complex "[0:v][1:v]overlay=10:10" -c:a copy output.mp4

这里是说主视频第0个输入叠加第1个输入的LOGO图， 10:10 是LOGO左上角相对视频左上角的偏移。如果想放在右下角并保留边距：

ffmpeg -i input.mp4 -i logo.png -filter_complex "[0:v][1:v]overlay=W-w-10:H-h-10" -c:a copy output.mp4

W 和 H 是主视频的宽高， w 和 h 是LOGO图的宽高，这条表达式就会自动计算右下角位置，还挺常用的。

文字水印用的是drawtext滤镜：

ffmpeg -i input.mp4 -vf "drawtext=text='My Watermark':fontcolor=white:fontsize=24:x=10:y=10:fontfile=/path/to/font.ttf" -c:a copy output.mp4

有个高频坑跟搜索热词“ffmpeg fade没有渐隐效果”相关。很多人在指定淡出效果时只在视频尾部加了fade滤镜，却没有意识到默认的fade滤镜作用于视频画面但需要设置正确的起始帧和时间。正确写法：

ffmpeg -i input.mp4 -vf "fade=t=in:st=0:d=1,fade=t=out:st=10:d=1" -c:a copy output.mp4

这里的 st 是开始时间（秒）， d 是持续时长。如果视频总长只有10秒而你把 st=10:d=2 ，那淡出区间已经超出视频末尾，自然不会看到渐隐效果。记住一个原则：淡出开始时间 + 持续时长 ≤ 视频总时长。还有一个常见情况是fade滤镜对音频无效，如果想做音频淡出需要单独加afade滤镜：

ffmpeg -i input.mp4 -vf "fade=t=out:st=8:d=2" -af "afade=t=out:st=8:d=2" -c:v libx264 -c:a aac output.mp4

5. 常见问题与实战排查

5.1 FFmpeg的-y参数到底什么意思，不加会怎样

-y 就是“自动覆盖已存在文件”的开关。FFmpeg默认不覆盖，当输出文件已存在时，它会暂停并在标准错误里输出：

File 'output.mp4' already exists. Overwrite? [y/N]

等用户输入。在Java的ProcessBuilder场景下，这个提示会进入stderr流，而你的程序只会傻傻等进程结束，结果就是任务卡死直到超时。所以线上代码里我强烈建议统一加 -y ，避免任何交互等待。如果出于安全考虑不想覆盖源文件，那就先判断目标文件是否存在，存在就换名或先删除，而不是让FFmpeg停下来问你。

还有一个不完全等价但容易被混淆的参数： -n ，它的含义是“不存在才执行，已存在直接失败”，适合做防止误覆盖的场景。

5.2 “the specified filename does not exist” 这类诡异报错怎么查

截图场景里，命令看着没问题却报“the specified filename does not exist”，这个报错很迷惑人，因为文件名明明写在那里。排查思路分三步：

第一步检查命令的output文件路径是否正确。如果是在Spring Boot代码里拼路径，看一下File.separator在Windows和Linux下的差异，别把反斜杠和正斜杠混用了。Windows下路径含空格时，ProcessBuilder不会自动加引号，但FFmpeg解析时会把空格当成参数分隔符，需要把路径用引号包起来。

第二步检查FFmpeg命令的选项顺序。比如写成：

ffmpeg -i input.mp4 -vframes 1 -ss 00:00:10 output.jpg

这里 -ss 放在输出文件之前会被解释为“对输出做切割”，而FFmpeg在某些版本下对输出定位配合 -vframes 的行为是异常的，典型报错就和“specified filename not exist”沾边。正确做法是 -ss 紧跟着 -i input.mp4 或者放在输入之前。

第三步看FFmpeg版本。某些静态构建包存在已知bug，特别是Windows下用特定版本编译出来的二进制，截图行为和其他平台不一致。遇到反复排查不出来的问题，换一个官方推荐的release版本，往往就能解决。

5.3 moviewriter ffmpeg unavailable与JavaCV相关集成问题

如果你搜到这个报错，大概率是在用JavaCV或JavaFX的MediaWriter时出现的。“moviewriter ffmpeg unavailable”的意思是JavaCV在本地库中无法加载FFmpeg原生库，通常发生在依赖版本不一致或缺少本地平台库。这正好印证了我前面说的方案选型理由——走原生API集成会遇到环境层面的问题，而命令行方案没有这种麻烦。

如果确实需要JavaCV，一个常见解法是显式指定平台的jar包，比如 org.bytedeco:ffmpeg-platform-gpl 或 org.bytedeco:javacv-platform ，并且保证JavaCV和FFmpeg两个artifact的版本号完全对应。在本地开发时，还需要确认JVM的java.library.path包含FFmpeg原生库所在目录。但这些配置经过跨平台部署后很容易再次翻车，所以我依然建议能用命令行解决的就不要引JavaCV。

5.4 用FFmpeg拉RTSP流与硬件加速

搜索热词里出现了“zlmediakit的ffmpeg拉取rtsp流”，这是流媒体服务场景的一部分。FFmpeg拉RTSP流最常用的两种用途：一是将RTSP流转封装为HLS供Web端播放，二是截图轮巡获取监控画面作为“一段时间内的一帧”。命令如下：

ffmpeg -rtsp_transport tcp -i rtsp://admin:pass@192.168.1.100:554/stream1 -c copy -f hls output.m3u8

-rtsp_transport tcp 很关键，如果不指定，FFmpeg默认使用UDP，而UDP在跨网段或网络不稳时会疯狂丢包，画面出现花屏或者直接卡住。TCP方式稳定得多，代价是占用带宽稍大。对摄像头接入场景，尽量用TCP。

另外，搜索热词里“nvidia gt630 ffmpeg mp4”说明有人想在老Nvidia显卡上做硬件编码。GT630属于Fermi架构，其NVENC能力很弱或者根本没有，是没法用 -c:v h264_nvenc 做硬件编码的。判断你的显卡是否支持NVENC，最直接的方式是执行：

ffmpeg -encoders | grep nvenc

能列出 h264_nvenc 才说明FFmpeg编译了该功能。但编译了不等于能跑，运行时还需要驱动和NVENC固件配合。如果你的显卡比较老，老老实实用libx264软编就行，对单路视频转码来说，性能完全够用。真要追求高并发硬编，找一张全新的NVIDIA T4或者A2这类专门做转码的卡，才是正道。

5.5 视频处理任务的稳定性与性能优化

线上跑视频处理任务，稳定性比功能完成更重要。我这里整理几类每批项目都会遇到的业务稳定要素，帮你提个醒。

一是任务异步化。视频处理动辄几秒到几十秒，不能放在HTTP请求里同步等待。正确的做法是：接口接收任务请求后立即返回任务ID，后台通过线程池或消息队列异步执行，前端通过任务状态接口轮询进度。就算某次转码失败，也能重试或记录脏数据，不影响主流程。

二是超时控制。ProcessBuilder默认没有超时时间，如果FFmpeg因为某个编码器问题挂在那里，进程会一直占着CPU和内存。所有执行方法都必须传入超时参数，超时后 destroyForcibly() 杀掉进程，并释放临时文件。

三是磁盘空间监控。转码过程会生成临时文件和输出文件，空间写满会导致任务失败甚至影响同一台机器上的其他应用。建议启动一个定时任务监控临时目录和输出目录的使用率，超过阈值自动告警。

四是并发控制。FFmpeg转码是CPU密集型，如果服务器CPU核数有限，开太多并发进程会互相抢占CPU导致所有任务都变慢。一个核跑一个转码进程是比较合理的经验值，可以用JVM的可用处理器数量做信号量限制。

五是日志记录。开发阶段看一次报错和读日志排查问题大家都能接受，但到了生产环境，尤其是做成一个平台或服务给别人用的时候，一定得有一个可查询、可回溯的完整链路日志：每个任务从收到请求、创建命令、执行完成到输出结果的每一步都记录清楚。FFmpeg的stderr输出也别丢了，往往最关键的编码错误信息就在里面。

6. 收尾：我在实战中的几点体会

这个项目做下来，最大的体会是“别把FFmpeg当成黑盒”。一开始我也想过用JavaCV那一套，觉得“面向对象”更高级，但真正遇到编码格式、滤镜时长这类问题后，才发现命令行方案反而最容易定位和验证。对于一个团队来说，FFmpeg命令行是全体成员（甚至运维同学）都能理解和复现的东西，而JNI层的抽象则只有少数人能调，这种可维护性上的差异在项目运行半年后会越来越明显。

最后分享一个小技巧：处理任何一个新的FFmpeg需求，先在终端里手工把命令跑通，确认输出正常，再翻译成Java的ProcessBuilder代码。不要直接跳过终端验证阶段，因为你最终在Java里调试时看到的信息量远不如终端上那么直接。FFmpeg的每次升级都可能带来默认行为的变化，保持关注官方changelog，尤其注意滤镜参数和编码器默认值的变化。

希望这篇指南能帮你把Spring Boot 3和FFmpeg的组合顺畅地用起来。如果后续有更多实战细节，比如HLS加密、自适应码率、批量任务调度等，我再单独写文展开。