如何处理使用mutagen写入日文标签时触发的UnicodeEncodeError错误

错误原因 #

该UnicodeEncodeError由两个核心问题触发：

• MP3的旧版ID3标签（ID3v2.3及更早版本）默认仅支持Latin1或UTF-16编码，默认配置下mutagen会用不支持日文的Latin1编码写入标签，导致编码失败
• Windows系统默认字符编码为GBK（cp936，属于charmap编码集），未包含对应日文字符的映射，也会触发该类报错

修复代码 #

你仅需要修改addTag函数的内部逻辑即可，无需改动下方不受控制的业务代码：

import mutagen

def addTag(fpath, title, albumName):
    audio = mutagen.File(fpath, easy=True)
    # 避免重复添加标签报错
    if audio.tags is None:
        audio.add_tags()
    audio['title'] = title
    audio['album'] = albumName
    # 保存时指定ID3v2.4版本，强制用UTF-8编码写入标签，完美支持日文字符
    audio.save(fpath, v2_version=4, encoding=3)

参数说明：

• v2_version=4指定使用ID3v2.4版本标签，该版本原生支持UTF-8编码
• encoding=3对应UTF-8编码，是目前兼容性最好的Unicode编码方案

兼容旧设备方案 #

如果你的标签需要在不支持ID3v2.4的旧播放器/设备上读取，可以改成使用ID3v2.3版本+UTF-16编码：

audio.save(fpath, v2_version=3, encoding=1)

额外Windows环境适配 #

如果修改代码后仍触发该报错，可在脚本最开头添加以下代码，强制Python标准输出/错误流使用UTF-8编码：

import sys, io
sys.stdout = io.TextIOWrapper(sys.stdout.detach(), encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.detach(), encoding='utf-8')

也可以在运行脚本前，先在CMD中执行set PYTHONUTF8=1再启动Python脚本，效果一致。

内容的提问来源于stack exchange，提问作者new_buffer_overflow