在 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）则看不到封面。这一点务必注意。
