VSCode中利用Node批量修改多媒体文件元数据标签

在 Node.js 生态中，能够稳定跨格式读写音频元数据的库，music-metadata 几乎是不二之选。它全面支持 MP3、FLAC、M4A、WAV，并且对 ID3、Vorbis、MP4 原生标签的读写都非常可靠。不过，有几个关键细节需要留意：

使用 music-metadata 读写音频文件元数据，最为稳定可靠

说实话，不建议尝试那些 id3v2 或 node-id3 之类的库——它们要么仅支持 MP3，要么写入后 iTunes 或 Windows 资源管理器无法识别，更严重的是，可能会损坏 FLAC 的封面二进制流。相比之下，music-metadata 安装非常简单，只需添加 --save-dev 即可，且不依赖 native 模块，完美兼容 Windows、macOS 和 Linux：

npm install music-metadata --save-dev

这里有几个必须牢记的关键点：

• 为什么必须使用 parseFile() 而不是 parseBuffer()？因为写操作依赖文件路径，而 parseBuffer() 仅处理内存中的数据，无法写回文件。因此，初始化时务必使用 parseFile()。
• 写操作必须显式调用 writeMetadata()，并且传入的路径必须是完整的目标路径，不能只写一个文件名。

批量修改前，先验证文件是否支持写入

music-metadata 默认是只读模式，并非所有格式都支持写入——例如某些嵌套在 AVI 中的音频流，直接写入可能会静默失败，或者抛出 ERR_UNSUPPORTED_OPERATION 错误。因此，在批量操作前，最好先进行一个小测试。

具体步骤如下：

• 使用 parseFile(filePath, { write: true }) 初始化，如果返回的 format.dataFormat 为 undefined，或者 format.lossless === false 但格式是 MP3，那么大概率是可写的。
• 对每个文件单独尝试写入一个临时字段，例如 common.lyrics = "test"，然后立即读取一次，验证是否真正落盘。这样可以避免整批跑完后才发现所有修改都没生效的尴尬。
• 关于封面：MP3 的封面必须使用 { format: 'jpg' | 'png', data: Uint8Array } 格式传入 common.picture，不要传入 base64 字符串，否则会出现问题。

VSCode 终端里运行脚本，比插件更可控

说实话，VSCode 中那些“ID3 Editor”类的插件，表面上看起来很方便，一遇到问题就束手无策。它们底层同样使用 Node 库，但封装层屏蔽了错误堆栈，导致问题排查困难。不如直接在 VSCode 集成终端中运行自写脚本，出错时能立即看到 TypeError: Cannot set property 'title' of undefined 这类真实报错信息，调试起来轻松得多。

下面是一个示例脚本，保存为 batch-tag.js：

const mm = require('music-metadata');
const fs = require('fs').promises;

async function updateTags(file) {
  const parsed = await mm.parseFile(file, { write: true });
  if (!parsed.common.title) parsed.common.title = "Untitled";
  parsed.common.album = 'My Collection 2024';
  await mm.writeMetadata(parsed, file); // 注意：第二个参数必须是原路径
}

// 用 glob 匹配，避免手动列文件
const files = await fs.readdir('./audio');
for (const f of files.filter(f => /\.(mp3|flac|m4a)$/i)) {
  await updateTags(`./audio/${f}`);
}

执行命令：node batch-tag.js。注意：VSCode 终端默认工作目录是打开的文件夹根目录，因此路径不要写死成 C:...，使用相对路径更加稳妥。

中文路径和 Unicode 标签，Windows 上容易出问题

最令人头疼的其实是中文路径。Windows 下，Node.js 默认使用系统 ANSI 编码读取路径，遇到中文文件名会直接报 ENOENT；即使路径通了，写入的 common.artist 在资源管理器里显示乱码，这是因为 music-metadata 默认用 UTF-16 写入 ID3v2.4，而旧播放器只识别 UTF-8。

解决办法有以下几种：

• 启动脚本前，在 VSCode 终端先执行 chcp 65001，切换到 UTF-8 代码页。
• 写入时强制指定编码：await mm.writeMetadata(parsed, file, { native: true, id3v2Version: 3 })。ID3v2.3 默认使用 UTF-8，兼容性更好。
• 如果文件名包含 emoji 或生僻字，使用 path.resolve() 构造路径，避免拼接字符串导致乱码。

最麻烦的其实是封面：Windows 资源管理器只识别 ID3v2.3 的 APIC 帧，而且 picture.type 必须设置为 3（Front Cover），如果设置为 0（Other）则看不到封面。这一点务必注意。