1. 项目的真实起点:为什么非要自己造一个视频合并 CLI
先说结论:这个工具不是一时兴起写着玩的,它解决的是我日常工作中一个非常具体、反复出现、又找不到完美现成方案的问题——给视频统一加片头和片尾,然后批量处理多个视频文件。
做视频内容的人应该都有这种经历:手里有几十个原始视频片段,可能是录屏、可能是课程切片、也可能是活动拍摄的素材,发布之前都需要统一加上一个两三秒的片头(比如工作室 LOGO、课程标题页)和一个片尾(比如二维码、下期预告、联系方式)。如果只是三五个视频,用剪映、Premiere 手动拖一拖也就完事了。但数量一上来,比如三五十个甚至上百个,手动操作就变成了一场灾难:每个视频都要重复"导入、拖片头、拖片尾、导出"这套流程,一个视频少说三五分钟,五十个视频就是两三个小时,而且这种重复劳动特别容易出错——漏加片头、导出设置不统一、文件命名乱掉,事后检查更痛苦。
一开始我尝试过直接用 FFmpeg 命令行硬拼。FFmpeg 本身确实能完成这个事,核心命令也不复杂,用 concat 协议或者 filter 都能把视频拼起来。但问题是,FFmpeg 的命令行参数太多太杂,每次都要写一长串:
bash复制ffmpeg -i intro.mp4 -i main.mp4 -i outro.mp4 \
-filter_complex "[0:v][0:a][1:v][1:a][2:v][2:a]concat=n=3:v=1:a=1[outv][outa]" \
-map "[outv]" -map "[outa]" output.mp4
这玩意儿如果只是偶尔用一次还行,但一旦涉及批量操作、文件命名规范、路径里有空格、视频分辨率不一致这些现实问题时,手写的 Shell 脚本很快就变得又臭又硬,而且难复用、难维护。
我也考察过一些现成的开源工具。有些确实能解决片头片尾拼接的问题,但要么依赖图形界面不适合服务器上跑,要么功能过于简单不支持批量操作,要么需要同时装 Python、Java 等一大堆依赖。为了一个需求引入一个重型工具链,总觉得不划算。
最后决定自己动手:用 Node.js 写一个命令行工具,底层调用 FFmpeg 来完成实际的视频处理,上层用 Node.js 来做命令行交互、批量遍历和流程控制。这个组合的好处很明显——Node.js 生态成熟、跨平台、命令行解析库好用,FFmpeg 则负责最硬核的视频编码解码,两者各司其职。
这个工具适合谁参考?我觉得有三类人:一是像我一样有批量视频处理需求的内容从业者,不想被重复劳动折磨;二是想练手 Node.js 编写真实 CLI 工具、学习 child_process 与外部程序协作的开发者;三是对 FFmpeg 感兴趣但不想直接啃那一堆晦涩参数、希望有更友好封装的同学。文章后面我会把完整的实现思路、核心代码、踩过的坑都讲一遍,代码你可以直接拿去用,也可以根据自己的场景改。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境搭建:Node.js 和 FFmpeg 的安装细节与版本选择
在写任何代码之前,先把运行环境说明白。这是整个项目的地基,地基不牢,后面全是坑。
2.1 Node.js 版本怎么选
先说 Node.js。做 CLI 工具,我的经验是不要追求最新版本,稳定 LTS 版本永远是首选。目前 Node.js 的 LTS 版本已经到 22.x,最低也建议选 18.x 以上。为什么这么说?因为我们用到的几个核心能力——fs/promises 文件系统 API、child_process 的子进程管理、process.argv 参数解析——在 18.x 都是稳定可用的。
在你感兴趣的"热词"里我注意到很多人搜"node.js 18.20.4 lts版本下载""node.js 22.12+""如何查看有没有安装node.js"。这里顺带补充一下新手最容易困惑的点:安装完 Node.js 后怎么验证?打开终端(Windows 是 cmd 或 PowerShell,macOS/Linux 是 Terminal),敲两个命令:
bash复制node -v
# 例如输出 v20.11.1
npm -v
# 例如输出 10.2.4
两个命令都有输出版本号,说明安装成功了。如果提示"command not found"或者"无法识别",第一步先检查是不是没把安装目录加到 PATH 环境变量里。Windows 官方安装包一般会自动配好,但某些绿色版或者手动解压的版本需要自己配;macOS 如果用的是 nvm 安装,需要确认 source ~/.zshrc 或重启终端。
2.2 FFmpeg 安装与更隐蔽的坑
FFmpeg 的安装相比之下要稍微注意一点,因为不同平台的差异比较大。
- Windows:去官网下载 build 版本,选择一个
ffmpeg-master-latest-win64-gpl.zip之类的压缩包,解压后把bin目录(里面有ffmpeg.exe)加到 PATH。验证方法是在终端输入ffmpeg -version,如果能输出一大段版本信息就没问题。 - macOS:有 Homebrew 的直接
brew install ffmpeg,这是最省事的路径。 - Linux(CentOS/Ubuntu等):Ubuntu 用
apt install ffmpeg,CentOS 可能要启用 EPEL 源。注意 CentOS 7 自带的 FFmpeg 版本非常老,不仅性能差,很多 filter 还不支持,强烈建议编译新版或者用第三方源。
FFmpeg 安装这里有一个特别容易踩的坑:装是装了,但 Node.js 子进程里调不到。出现这种情况通常是 GUI 环境里终端能执行 ffmpeg,但从 Node.js 的 child_process 里执行却报 spawn ffmpeg ENOENT。原因往往是 PATH 没有正确传到子进程,尤其是在 macOS 上通过 Finder 启动的终端或者某些 IDE 内置终端,加载的 PATH 和系统级 PATH 不一致。解决方式有两个:一是在代码里写死 FFmpeg 的绝对路径;二是在启动 Node.js 进程之前确保终端环境里 ffmpeg 能被找到。我自己的做法是在工具的配置里增加一个 ffmpegPath 选项,允许用户显式指定,默认才去 PATH 里找,这个设计的理由后面会详说。
2.3 运行环境探测:别让用户猜
环境搭好后,一个好的 CLI 工具会主动做环境检查,而不是等到运行到一半才报错。我在工具启动时做了这么几件事:检查 ffmpeg 是否可用、检查 ffprobe 是否可用、检查输入目录是否存在、检查输出目录是否有写入权限。任何一项不满足,直接给出友好的中文提示并退出。
检查命令很简单,用 child_process.exec 跑一下就好:
javascript复制const { execSync } = require('child_process');
function checkFFmpeg() {
try {
const output = execSync('ffmpeg -version', { encoding: 'utf8' });
return output.includes('ffmpeg version');
} catch (e) {
return false;
}
}
这里有个小技巧:用 execSync 返回的字符串去匹配版本关键字,比单纯检查有没有抛出异常更可靠,因为某些情况下系统可能有 ffmpeg 这个命令但它对应的是别的程序(比如某些 Linux 发行版里 ffmpeg 其实是 Libav 提供的 avconv 改名)。
3. 工具的核心设计:CLI 结构、命令参数与工作流程
环境问题解决之后,我们正式进入工具的设计环节。其实写 CLI 工具和其他软件一样,最重要的不是堆代码,而是先想清楚用户会怎么用、输出是什么、异常怎么办。
3.1 参数设计:为高频需求做减法
我设计的命令行用法是这样的:
bash复制videomerge --input ./videos --output ./output --intro intro.mp4 --outro outro.mp4
也可以不带片头片尾,纯粹做批量格式统一或无拼接合并:
bash复制videomerge --input ./videos --output ./output
参数尽可能少、
