music-metadata 是 node 生态中唯一能跨格式（mp3、flac、m4a、wav）稳定读写 id3/vorbis/mp4 原生标签的库，需用 parsefile() 初始化并显式调用 writemetadata()，且须验证写入支持、处理中文路径与封面规范。
用 music-metadata 读写音频文件元数据最稳
Node 生态里真正能跨格式（MP3、FLAC、M4A、WAV）稳定读写标准 ID3、Vorbis、MP4 原生标签的，只有 music-metadata。别碰 id3v2 或 node-id3 —— 它们要么只支持 MP3，要么写入后 iTunes/Windows 资源管理器不识别，要么破坏 FLAC 的封面二进制流。
安装时加 --save-dev 即可，它不依赖 native 模块，Windows/macOS/Linux 全兼容：
npm install music-metadata --save-dev
关键点：必须用 parseFile()（而非 parseBuffer()）才能正确写入；写操作必须显式调用 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 终端里跑脚本比插件更可控
别装什么 “ID3 Editor” 类 VSCode 插件——它们底层用的还是 Node 库，但封装层屏蔽了错误堆栈，出问题只能干瞪眼。直接在 VSCode 集成终端里运行自写脚本，出错立刻看到 TypeError: Cannot set property 'title' of undefined 这种真实报错。
使用一条命令部署ProbeChain Rydberg测试网代理节点。自动注册为Agent(NodeType=1)，免gas，支持macOS/Linux/Windows。触发词：/r
示例脚本片段（保存为 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 默认用系统 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）就看不到。
