luckinboy1. 项目的真实起点：为什么非要自己造一个视频合并 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
参数尽可能少、职责单一：
| 参数 | 作用 | 是否必填 |
|---|---|---|
--input / -i |
指定输入目录 | 必填 |
--output / -o |
指定输出目录 | 必填 |
--intro |
片头文件路径 | 可选 |
--outro |
片尾文件路径 | 可选 |
--concurrency |
同时处理的文件数量 | 可选，默认1（串行） |
--overwrite |
是否覆盖同名输出文件 | 可选，默认false |
为什么参数做这么少？因为我用过的很多工具从第一天起就拼命堆参数，结果用户根本记不住。视频合并这个场景，核心变量只有：输入在哪、输出到哪、片头是谁、片尾是谁。其他所有东西，比如编码参数、分辨率、帧率、码率，在绝大多数场景下维持视频原有编码就行，不需要暴露给用户。
3.2 工作流程：三步走
整个工具的逻辑可以浓缩成三条路径：
第一步，解析参数并做合法性检查。 除了上面说的环境探测，还要检查 --input 路径存在且是目录，--intro / --outro 文件存在且能被 FFmpeg 解析。这里有一个容易被新手忽略的点：--intro 的文件格式和主视频的格式很可能不一样。比如片头是 .mov，主视频是 .mp4，编码也可能不同（有的 H.264、有的是 H.265），混合拼接时如果不做转码，极容易出现音画不同步或者直接失败。所以这个工具默认会做一步"统一参数"处理，让所有参与拼接的视频先被转换到一个中间统一格式（比如统一为 H.264 + AAC 编码、统一分辨率等比缩放），再做拼接。这个细节后面讲原理的时候会详细展开。
第二步，扫描输入目录。 用 fs.readdir 读取目录，过滤掉非视频文件。注意只是按扩展名过滤，常见的有 .mp4、.mov、.avi、.mkv、.flv、.webm，同时跳过隐藏文件（以 . 开头的）和临时文件（以 ~ 开头或 .tmp 结尾的）。扫描完成后对文件列表做一次自然排序，保证 video2.mp4 排在 video10.mp4 前面，而不是按字符串排序排出一个奇怪顺序。
第三步，逐个处理。 遍历文件列表，对每个文件执行"读取文件信息→拼接处理→输出到目标位置"的流程。最后打印所有文件的处理结果汇总。
3.3 为什么要用 Node.js 而不是纯 Shell
我知道很多人会问：这活儿用 Bash 写不也行吗？为什么要引入 Node.js？说实话，纯 Bash 确实能做，我在最初的原型验证时就是用 Bash 写的。但很快暴露了三个问题：
第一是跨平台问题。Bash 脚本在 macOS/Linux 上跑得欢，到了 Windows 上就得装 Git Bash 或者 WSL，或者改写为 .bat。而 Node.js 本身就是跨平台的，同一套代码三个系统都能跑。
第二是复杂逻辑的表达能力。批量处理涉及条件分支、循环嵌套、错误收集、日志输出、并发控制，这些用 Node.js 写起来行云流水，用 Bash 写就很容易陷入转义地狱。
第三是后续扩展。这个工具后面如果想加一个 --watch 模式（监听目录，新文件进来就自动处理）、加一个 Web 控制界面、或者做成远程调用服务，Node.js 的生态能支撑这些扩展，而 Bash 就基本到头了。
4. 视频拼接的核心原理：从 concat 协议到转码的必要性
现在到了整个项目最关键的部分：怎么让 FFmpeg 把几个视频文件正确拼起来。重要的是先理解原理，再动手写代码。
4.1 FFmpeg 三种拼接方式，到底该选哪个
FFmpeg 拼接视频有三种主流方式，很多人搞不清区别，我用最直白的方式解释一下。
方式一：concat demuxer（基于文件列表的封装层拼接）
这是"推荐优先尝试"的方案。思路是先写一个文本文件，列出所有待拼接的视频文件路径，然后让 FFmpeg 读取这个列表，在"封装层"直接拼接。命令长这样：
bash复制ffmpeg -f concat -safe 0 -i list.txt -c copy output.mp4
-c copy 的意思是直接复制原始视频和音频流，不做任何重新编码。这种方式快得飞起——几秒钟就能拼完一个几GB的视频，因为它没有解码和重新编码的开销。
但它有严格的前提：所有视频的编码格式、分辨率、帧率、采样率、声道数必须完全一致。只要有一个不一致，轻则拼接处出现花屏、跳帧，重则直接报 Non-monotonous DTS in output stream 之类的错误然后退出。
方式二：filter_complex (concat filter)
这是用滤镜图在"帧层面"做拼接。命令可以写成前面那种一长串的形式，也可以配合命名管道。它的优势是灵活，可以处理不同分辨率、不同帧率的视频——只要你先把它们 scale、fps、aresample 到一致即可。代价是慢，因为每个视频都要完整解码和重新编码。
方式三：concat protocol（流级拼接）
语法是 ffmpeg -i "concat:file1.mp4|file2.mp4|file3.mp4" -c copy output.mp4。这种方式限制更大，只支持少数几种封装格式（主要就是 MPEG-TS），直接拼 MP4 经常失败。除非你专门处理 TS 流，否则不要用它。
4.2 这个项目到底该选哪种：一个"中间态"方案
回到我们的场景。片头 .mp4、主视频 .mp4、片尾 .mp4 可能编码相同，也可能不同。用户的主视频之间彼此也可能有差异。这种情况直接拿 concat demuxer 碰运气是不行的。
我最终采用的方案是一个"先统一，再无损拼接"的折中策略：
- 探测文件信息：用
ffprobe（FFmpeg 家族里的媒体信息探测工具）拿到每个文件的编码、分辨率、帧率、音频参数。 - 判断是否需要转码：如果所有文件参数一致，且确实都是 H.264 + AAC 这类标准编码，直接走 concat demuxer 无损拼接，这样速度最快。如果参数有差异，走 filter_complex 方案，先统一再拼接。
- 自动统一参数：对于需要转码的文件，用 filter_complex 中的 scale、fps、format、aresample 等过滤器把分辨率统一到第一个主视频的分辨率，帧率对齐，音频格式对齐。
这个逻辑通过代码自动判断，而不是要求用户手动指定。用户可以完全不关心内部走的是哪条路径，工具会自动选择"最快的可行方案"。
下面是核心的拼接函数，用 child_process.spawn 调 FFmpeg，并实时输出进度：
javascript复制const { spawn } = require('child_process');
const fs = require('fs');
const path = require('path');
async function mergeVideos({ fileList, outputPath, isHomogeneous }) {
return new Promise((resolve, reject) => {
let args = [];
if (isHomogeneous) {
// 同参数视频：concat demuxer 无损拼接
const listFile = path.join(process.cwd(), `.concat_${Date.now()}.txt`);
// 写入文件列表，注意 windows 路径要用正斜杠
const content = fileList.map(f => `file '${f.replace(/\\/g, '/')}'`).join('\n');
fs.writeFileSync(listFile, content, 'utf8');
args = ['-f', 'concat', '-safe', '0', '-i', listFile, '-c', 'copy', '-y', outputPath];
console.log('参数一致，走无损拼接模式');
} else {
// 参数不一致：filter_complex 逐段处理
const inputs = [];
const filterParts = [];
fileList.forEach((file, index) => {
inputs.push('-i', file);
filterParts.push(`[${index}:v]scale=1920:1080:force_original_aspect_ratio=decrease,pad=1920:1080:(ow-iw)/2:(oh-ih)/2,fps=30,format=yuv420p[v${index}];`);
filterParts.push(`[${index}:a]aformat=sample_rates=44100:channel_layouts=stereo[a${index}];`);
});
let filterComplex = filterParts.join('') +
fileList.map((_, i) => `[v${i}][a${i}]`).join('') +
`concat=n=${fileList.length}:v=1:a=1[outv][outa]`;
inputs.push('-filter_complex', filterComplex);
inputs.push('-map', '[outv]', '-map', '[outa]');
inputs.push('-c:v', 'libx264', '-preset', 'medium', '-crf', '18');
inputs.push('-c:a', 'aac', '-b:a', '192k');
inputs.push('-y', outputPath);
args = inputs;
console.log('参数不一致，转码拼接模式');
}
const ffmpeg = spawn('ffmpeg', args, { stdio: ['ignore', 'pipe', 'pipe'] });
// 这里可以把 FFmpeg 的 stderr 输出转发到我们的日志
let stderrData = '';
ffmpeg.stderr.on('data', (data) => {
stderrData += data.toString();
// FFmpeg 进度在 stderr 里
const match = data.toString().match(/time=(\d+):(\d+):(\d+\.\d+)/);
if (match) {
const totalSeconds = parseInt(match[1]) * 3600 + parseInt(match[2]) * 60 + parseFloat(match[3]);
process.stdout.write(`\r处理中... ${totalSeconds.toFixed(1)}秒`);
}
});
ffmpeg.on('close', (code) => {
if (code === 0) {
resolve();
} else {
reject(new Error(`ffmpeg 退出码 ${code}，错误信息: ${stderrData.slice(-500)}`));
}
});
});
}
这段代码有几个值得注意的地方：
- 用
spawn而不是exec。exec会把命令放进 shell 里执行，再拼接字符串时容易遇到路径空格、特殊字符导致的转义问题，还有命令行长度的限制。spawn直接以参数数组形式传给进程，完全绕开了 shell 转义，安全且可控。这一点被无数人踩过坑。 - 进度解析从
stderr里抓，因为 FFmpeg 约定把日志和进度写到标准错误流，标准输出流用于输出真正的媒体流数据。第一次接 FFmpeg 的人几乎都会在这里困惑，以为 FFmpeg 没有任何输出。 isHomogeneous判断是核心优化点。我封装了一个probeMediaInfo函数用 ffprobe 获取文件信息，比较编码、分辨率、帧率、采样率、声道数是否全部一致。全一致才走无损模式，这样速度和生产质量都能兼顾。
4.3 ffprobe 探测信息：参数统一的基础
上面提到的 isHomogeneous 判断依赖 ffprobe。这是 FFmpeg 家族中的"侦察兵"，它不做音视频处理，只负责读取媒体文件的元数据并打印成 JSON，方便程序解析。
javascript复制const { execSync } = require('child_process');
function probeMediaInfo(filePath) {
const cmd = `ffprobe -v quiet -print_format json -show_format -show_streams "${filePath}"`;
const output = execSync(cmd, { encoding: 'utf8' });
const data = JSON.parse(output);
const videoStream = data.streams.find(s => s.codec_type === 'video');
const audioStream = data.streams.find(s => s.codec_type === 'audio');
if (!videoStream) {
throw new Error(`${filePath}: 没有找到视频流`);
}
return {
duration: parseFloat(data.format.duration || 0),
width: videoStream.width,
height: videoStream.height,
fps: eval(videoStream.r_frame_rate), // "30000/1001" 这种分数形式
codec: videoStream.codec_name,
audioCodec: audioStream ? audioStream.codec_name : null,
sampleRate: audioStream ? audioStream.sample_rate : null,
channels: audioStream ? audioStream.channels : null
};
}
这里顺手解释一个很多人第一次接触 ffprobe 会懵的点：r_frame_rate 字段是一个分数形式的字符串，比如 "30000/1001" 表示 NTSC 标准的 29.97fps，"25/1" 表示 25fps。直接当数字读就完全错了，必须用 eval 或在 Node.js 里手动解析分子分母。
5. 批量处理的工程化：排序规则、并发控制和错误恢复
"能拼接视频"只是第一步，一个真正能日常使用的工具，必须把工程化的细节做扎实。这部分我回想一下自己实际踩坑的过程，每一项都来自真实事故。
5.1 文件扫描与自然排序
文件扫描用 fs.readdir 拿到字符串数组之后，如果直接按默认的字典序排序，video2.mp4 会排在 video10.mp4 后面——因为字符 '1' 的 ASCII 码比 '2' 小。这件事在逻辑上没错，但在视频合并场景里绝对是错的：用户期望的是 2 号视频接 3 号视频，而不是 2 号后面接 10 号、再接 3 号。
所以我写了一个 naturalSort 函数，核心是用正则把字符串里的数字部分提取出来，转成数值后和字符串部分一起比较：
javascript复制function naturalSort(a, b) {
const reg = /(\d+)|(\D+)/g;
const aParts = a.match(reg);
const bParts = b.match(reg);
if (!aParts || !bParts) return a.localeCompare(b);
for (let i = 0; i < Math.min(aParts.length, bParts.length); i++) {
const aPart = aParts[i];
const bPart = bParts[i];
const aNum = parseInt(aPart);
const bNum = parseInt(bPart);
if (!isNaN(aNum) && !isNaN(bNum)) {
if (aNum !== bNum) return aNum - bNum;
} else if (aPart !== bPart) {
return aPart.localeCompare(bPart, 'zh-CN');
}
}
return aParts.length - bParts.length;
}
5.2 输出文件的命名与覆盖策略
输出文件名我做了这样一个设计：默认保留原始文件名，但增加一个可配置的后缀。比如输入是 video10.mp4，输出就是 video10_merged.mp4，这样原始文件不会被覆盖，用户拿两个目录对比也一目了然。
但这里马上会有一个新问题：如果同一个目录跑两次，第二次跑会不会覆盖第一次的输出？我在参数里设计了 --overwrite 开关，默认值是 false，也就是说如果目标文件已经存在，工具会跳过并提示。"默认不覆盖"这个决策是有意为之的：视频处理非常耗时，一个文件拼一次可能就要几分钟，万一处理到一半发现原来有更好的版本，结果已经被覆盖了，那真的会崩溃。
5.3 并发处理：快不一定好
处理多个视频文件时，很多人第一反应是"同时跑十个 FFmpeg 不就能快十倍吗"。理论上是这样，实际却要考虑两个问题。
第一，FFmpeg 是非常吃 CPU 和内存的进程。一个 1080p 视频转码时，CPU 占用轻松达到多核满载，内存也要几百 MB。如果你的机器有 16 核 CPU 和足够内存，同时跑 4 个确实能明显提速；但如果是在一台 4 核 8GB 内存的云服务器上跑，同时跑 8 个 FFmpeg 的结果可能是机器直接卡死。
第二，日志和输出的可读性。多个进程同时往终端输出进度行，输出会互相穿插，用户根本看不清谁完成了、谁还在跑。
所以我默认 --concurrency 1，也就是串行执行。想要加速的用户，可以手动指定并发数。这里我还有一个细节：我实现的并发不是一口气全部铺开，而是用一个"任务池"模型——初始化一个长度为 N 的队列，每当一个任务完成，就从队列里拿出下一个任务补位。这样能保证任意时刻最多有 N 个 FFmpeg 进程在跑。
javascript复制async function runWithConcurrency(tasks, concurrency) {
const results = [];
const queue = [...tasks];
async function worker() {
while (queue.length > 0) {
const task = queue.shift();
const result = await task();
results.push(result);
}
}
const workers = Array.from({ length: Math.min(concurrency, tasks.length) }, worker);
await Promise.all(workers);
return results;
}
5.4 错误处理与断点续跑
批量处理中，最怕的就是"跑了一半失败"。比如 50 个文件，第 30 个因为源文件损坏导致 FFmpeg 退出。如果整个程序崩溃，前 29 个白做了，用户还得重来。
我的做法是：每个文件单独 try-catch，失败的文件记录到日志，不中断整个流程。跑完之后单独输出一份汇总报告，告诉用户哪些成功了、哪些失败了、失败原因是什么。而且，因为每个文件的合并在输出到独立文件，所以失败的文件重新跑只需要支持指定文件重试，不用全量重跑。
这块的产物是一个 CSV 格式的日志文件，用户可以用 Excel 打开查看。顺便说一句，最近很多人搜"excel批量处理php"，虽然属实不同的技术栈，但"批量处理 + 日志 + 可追溯"的设计思路是一样的，程序性任务里"失败可重试"比"一次成功"重要得多。
6. 避坑实录：那些跑第一版时踩过的真实坑
这一节我按时间顺序记录开发过程中遇到过的几个最折磨人的问题。每个都有完整的排查链路，希望能帮你绕开。
6.1 坑一：spawn ENOENT —— FFmpeg 明明装了，Node 就是调不到
现象：在终端里手动跑 ffmpeg -version 完全正常，但 Node.js 用 spawn('ffmpeg', ...) 却报 spawn ffmpeg ENOENT。
排查链路：我一开始以为是代码问题，反复检查 spawn 的调用方式，没问题。然后在 Node 里 execSync('which ffmpeg')，能正确输出 /usr/local/bin/ffmpeg。那为什么 spawn 找不到？
后来才意识到，spawn 在默认情况下不走 shell，它尝试直接按文件名去 PATH 环境变量里搜索可执行程序。问题出在 Node.js 进程的环境变量上——当时的 PATH 是从 IDE 继承的，而 IDE 是从 GUI 环境继承的，GUI 环境加载的 PATH 和终端里 ~/.zshrc 设置的 PATH 不是一回事。终端里能用是因为 zsh 加载了 ~/.zshrc，而 IDE 的终端或 GUI 启动的 Node 进程没有加载。
解决：代码里增加 ffmpegPath 配置项，检测 spawn('ffmpeg') 失败时自动尝试几个常见路径（如 /usr/local/bin/ffmpeg、C:\ffmpeg\bin\ffmpeg.exe），并在文档里明确建议用户：如果在 IDE 里跑，最好用绝对路径配置。
6.2 坑二：concat 拼接后花屏和音画不同步
现象：用 concat demuxer 无损拼接，前几个视频拼出来没问题，但有一个视频拼完后，在拼接点附近出现花屏，后面音画开始不同步。
排查链路：第一反应是怀疑那个"问题视频"损坏了，用播放器单独放了一下发现完全正常。然后用 ffprobe -show_streams 对比各个视频参数，发现这个视频的帧率是 29.96fps，其他视频都是 30.00fps。差异极小，肉眼对着播放器盯着看都看不出来，但在封装层拼接时时间戳就对不齐，出现花屏。
解决：在判断"参数一致"时，帧率比较不能只做整数比较。把 29.96 和 30.00 的误差容忍设置在 0.01 以内，超出容差就按参数不一致处理。同时，比较分辨率时要注意，有的视频存储分辨率是 1920x1080，但实际画面比例可能是 2.39:1（上下黑边），有些则直接在容器里保留了 1920x800 的存储分辨率。这些差异叠在一起，让"看似一样"变成"实际不一致"，处理不好就会再现这个坑。
6.3 坑三：进度条解析不出来的焦虑
现象：一开始我监听 FFmpeg 子进程的 stdout 想解析进度，结果什么都没有。
排查链路：读了 FFmpeg 官方文档才知道，FFmpeg 的日志和进度全部走 stderr，stdout 只有残留的媒体数据。这个设计初看不合理，细想很合理——因为 stdout 在管道模式下要留给真正的输出数据，而 stderr 作为人类可读的日志通道。Node.js 里 spawn 如果不显式设置 stdio，子进程的 stdout/stderr 默认会用管道接到父进程，但你需要分别监听两个事件：child.stdout.on('data') 和 child.stderr.on('data')。
解决：监听 stderr 并匹配 time=HH:MM:SS.ss 字段解析进度。但是切记，FFmpeg 输出还在持续写行的过程中，time 字段是覆盖式的持续写入，可能需要用 \r 而不是 \n 来刷新同一行，这样终端显示更好看，也不会刷屏刷得让人眼晕。
6.4 坑四：中文文件名和路径里的空格
现象：文件名带中文或空格时，拼接失败。
排查链路：一开始我怀疑是编码问题，排查半天发现不是。真正原因是我在早期的实现里用了 exec 方式调用 FFmpeg，把命令拼成一个长字符串传进 shell，而 shell 对文件名里的空格天然需要转义处理。用纯字符串拼接命令时，忘了一对引号，就炸了。
解决：所有改用 spawn（参数数组方式），shell 转义问题根本不存在了，中文文件名、空格、括号全部安全。这个转变是质变——任何用 Node.js 调用外部命令行工具的场合，我都推荐优先用 spawn 而不是 exec，不只是安全考虑，也是语义正确性：外部程序需要的参数本来就是数组，不是字符串。
7. 透明度和可视化：让用户知道工具在干什么
一个只输出 处理中... 的 CLI 工具，用户用起来心里会发慌。我在工具的"透明度"上下了不少功夫。
7.1 每个文件的前置信息输出
处理每个文件之前，工具会打印这样一段信息：
code复制[3/50] 开始处理 video10.mp4
时长: 00:12:34.52
尺寸: 1920x1080
编码: h264 / aac
→ 拼接片头 intro.mp4
→ 拼接片尾 outro.mp4
→ 输出: ./output/video10_merged.mp4
这短短几行让用户一眼就知道：当前在处理第几个、总共有多少个、这个文件基本情况、预定的处理路径是什么。即使工具跑得慢，用户心里也有数，不会因为长时间没有输出而产生"是不是卡死了"的疑问。
7.2 真实处理耗时统计
每个文件跑完后，输出处理耗时和输出文件大小：
code复制[3/50] 完成 video10.mp4 (耗时 23.4秒, 输出 86.2MB)
[3/50] 失败 video10.mp4: 源文件解码错误
失败信息会同时写入 merge-error.log，方便事后单独排查。终端和文件双份记录，这个习惯建议大家都养成。
7.3 静默模式与日志级别
考虑到有些人会把这个工具集成到脚本里，可能不希望它每次打印一堆东西。我加了 --quiet 参数，只输出最终的汇总结果，不输出单个文件的过程信息。同时支持 --debug 参数，把 FFmpeg 的完整 stderr 输出都打印出来，方便遇到奇葩问题时的深度排查。
这三个等级的日志设计，对应了三种使用场景：普通用户的日常使用、脚本集成的静默调用、开发者的排错调试。没有一句话是多余的，也没有一句是缺失的。
8. 代码结构、测试与集成：如何让这个工具更健壮
工具面世之后，几个真实使用反馈让我意识到"能用"和"好用"之间还有不小的距离。这一节梳理一下我后来做的优化和扩展。
8.1 模块划分与可测试性
为了让代码好维护，我把工具拆成了几个独立模块：
code复制videomerge/
├── bin/
│ └── cli.js # 入口，解析参数、串联流程
├── lib/
│ ├── ffmpeg.js # FFmpeg/ffprobe 封装（探测、拼接、转码）
│ ├── scanner.js # 文件扫描、排序、过滤
│ ├── logger.js # 终端日志和文件日志
│ ├── config.js # 配置解析与管理
│ └── tasks.js # 任务队列与并发控制
└── test/
└── fixtures/ # 测试用的小型视频文件
这个结构看起来简单，但每个模块的边界非常清楚：ffmpeg.js 完全不关心文件系统的事，scanner.js 不碰 FFmpeg，tasks.js 只负责任务调度。这样写单元测试会很痛快——比如测试 scanner 时不需要真的去处理视频，只需要构造目录和文件名。
8.2 设备多样性兼容：arm64、Linux 服务器
很多人的实际使用环境是 CentOS 7 服务器或者树莓派（arm64）这类非主流开发环境。FFmpeg 在这些平台上的安装方式和坑都不一样。我在 README 里专门写了一节：
- 树莓派上
apt install ffmpeg可能装到的是硬件加速版本，对某些 filter 支持不完整，如果报 filter 相关的错，建议源码编译。 - CentOS 7 自带的 FFmpeg 版本很老，不支持
-safe 0参数或者部分 filter，建议用ffmpeg-release静态编译版本。 - Windows 上静态编译版（比如从 gyan.dev 下载的 release 版本）比 full build 在体积上小很多，但功能足够。
这些平台细节说实话不遇到不会想到，但写进文档里就能帮别人省大量时间。
8.3 与现有生态的协作：接上 n8n 之类的自动化编排
最后聊聊扩展思路。最近很多人研究 n8n 这类自动化编排工具，如果你的视频合并任务也是某个自动化流程中的一环，这个 CLI 就非常适合作为"工具节点"接入：n8n 监听到某个目录有新的视频文件，就执行一条命令调起合并工具，处理完后再通知下游任务发布。
这种情况下的调用接口已经支持得很好了：--quiet 模式让输出干净、退出码 0 表示成功、非 0 表示失败、输出文件落在固定目录，任何自动化系统拿到这三种信息都能可靠地编排。
举个例子，配合 n8n 的 Webhook 触发，用户在网盘上传一个原始视频，自动触发合并片头片尾，然后把成片推到一个分发系统，全过程不需要人碰命令行。这个工具从第一版就没有绑定任何交互式终端逻辑，这让我后来接自动化流程时几乎没改代码。
9. 一些必须说清楚的局限与后续规划
做工具做到最后，还是要诚实面对边界在哪里。这个工具目前有几个已知的局限，我写进 README 里，使用者心里有数。
局限一：不支持 GPU 硬件编码。 目前的转码路径用的是 libx264 软件编码，在低配置机器上处理长时间视频会比较慢。如果你有 NVIDIA 显卡，可以后续在代码里加 -c:v h264_nvenc 作为可选项，转码速度能提升非常多。但因为这会引入驱动和硬件差异，我暂时没有默认开启。
局限二：只处理目录内的文件，不递归子目录。 设计时故意做成平的。因为一旦递归，排序规则就复杂了（先按子目录分组还是先按文件排序），输出目录结构也要和输入目录结构对应。实际场景中如果确实有"分批处理不同目录"的需求，用户可以多次运行命令，或者简单地批量调用参数。
局限三：片头片尾永远"硬拼接"。 不做淡入淡出转场、不做音量自动平衡，片头片尾时长多长就放多长。有些用户问能不能对片头做 0.5 秒淡入，对片尾音乐做 1 秒淡出。这个功能后续加其实不难，filter_complex 里加 fade=t=in:st=0:d=0.5 就行，但会拖慢处理速度，第一版没上，后续规划里它是优先级很高的 next step。
局限四：对损坏视频文件只有错误提示，没有自动修复能力。 遇到某个文件在解码中途失败，工具会跳过它并写进日志，但不会尝试用 FFmpeg 的自动修复参数（比如 -err_detect ignore_err）重新处理。自动修复有时会成功，有时会输出损坏结果，默认不冒险是对的。
结尾
说实话，这个工具的技术含量不算高，没有机器学习、没有分布式、没有黑魔法。它的核心价值在于：把"原本需要手动做一百遍的重复劳动"压缩成一条命令。
在我自己的使用中，光上一次处理 120 个课程视频加片头片尾，就省下了大概四个小时。而且最重要的是，流程稳定之后，再也没有出现过"漏加片头""第 47 个视频忘记处理"这种人力操作才会犯的低级错误。
如果你也有类似的批量视频处理需求，或者你正在写自己的第一个真实 CLI 工具，我的建议很简单：不要追求功能大而全，先解决你最痛的那个问题，让它跑通、跑稳、跑得快，然后那些额外的优化（并发、GPU、格式兼容）再一点点加进去。工具是长出来的，不是设计出来的。