Python mimetypes 怎样为自定义音频扩展名注册类型

如果音频文件使用了系统默认表中没有的后缀，例如 .sfx，Python 的 mimetypes.guess_type() 通常无法直接推断类型。解决办法是在业务初始化阶段调用 mimetypes.add_type() 注册映射，再用同一个模块推断文件名。这样上传接口、下载响应和静态文件处理都可以复用同一份类型规则。

官方文档：https://docs.python.org/3/library/mimetypes.html

核心代码只有一行：mimetypes.add_type("audio/x-sfx", ".sfx", strict=False)。如果这个后缀属于团队内部或厂商私有格式，建议使用 strict=False；如果你明确要把它加入标准类型映射，再使用默认的 strict=True。

• add_type() 的第一个参数是 MIME 类型，第二个参数是带点的扩展名。
• guess_type() 返回二元组 (type, encoding)，不要把编码字段当成 MIME 类型。
• 注册发生在当前 Python 进程的映射中，不能替代浏览器、网关或操作系统的全局配置。

先看未知音频后缀为什么返回 None

mimetypes 根据文件名或 URL 的扩展名推测 MIME 类型。对于未知后缀，返回值中的 type 是 None；如果文件名带有已识别的压缩编码，第二个返回值才可能包含编码信息。音频后缀必须保留开头的点，例如 .sfx，不能传入不带点的 sfx。

import mimetypes

# 先观察未注册的自定义后缀，type 预期为 None。
mime_type, encoding = mimetypes.guess_type("concert.sfx")
print(mime_type, encoding)

如果本地映射里没有 .sfx，这里的结果通常是 None None。这不是音频内容损坏，也不是 guess_type() 读取了文件头后判断失败；该函数主要依赖文件名或 URL 的后缀，因此需要先补充映射。

用 add_type 注册自定义音频扩展名

注册时把完整 MIME 字符串和带点扩展名传给 mimetypes.add_type()。下面把团队内部的 .sfx 文件映射为 audio/x-sfx，然后立即重新推断文件名。

import mimetypes

# 注册当前进程需要识别的私有音频格式。
mimetypes.add_type("audio/x-sfx", ".sfx", strict=False)

# 注册后再按文件名推断 MIME 类型。
mime_type, encoding = mimetypes.guess_type("concert.sfx")
print(mime_type)  # 预期输出：audio/x-sfx
print(encoding)   # 没有压缩编码时通常为 None

这里的注册只改变 Python 进程内的类型表，不会修改文件内容，也不会检查 concert.sfx 是否真的包含可播放的音频数据。因此，上传系统仍应按自己的业务需要检查文件大小、权限和内容处理策略。

strict=True 和 strict=False 应该怎么选

strict 用来区分官方 MIME 类型映射与非标准类型映射。默认值是 True，会把映射加入标准类型表；设为 False 则把它放入非标准类型表。对于只在自家系统内流转的扩展名，使用 False 能更清楚地表达“这是应用约定”，也能避免把私有格式误标成通用标准。

import mimetypes

# 私有或厂商扩展优先放入非标准映射，避免扩大标准类型语义。
mimetypes.add_type("audio/x-sfx", ".sfx", strict=False)

# 对明确要加入标准映射的类型，可以保留 strict=True。
mimetypes.add_type("audio/vnd.example.score", ".score", strict=True)

# guess_type 返回 type 与 encoding；业务响应只应使用 type。
mime_type, encoding = mimetypes.guess_type("demo.score")
print({"content_type": mime_type, "content_encoding": encoding})

不要仅凭后缀把 encoding 写入 Content-Type。例如某个文件名同时带有压缩后缀时，guess_type() 会分别返回类型和编码；HTTP 响应通常要把它们放到各自的响应字段中，具体是否设置还要结合实际传输过程。

把注册逻辑放在初始化阶段

类型注册是进程级配置，适合集中放在应用启动代码、模块初始化函数或依赖注入容器的配置阶段。不要在每一次上传请求里重复散落调用，否则规则来源难以追踪，也容易出现不同请求使用不同映射的情况。

import mimetypes

CUSTOM_AUDIO_TYPES = {
    ".sfx": "audio/x-sfx",
    ".voicepack": "audio/x-voicepack",
}


def register_custom_types() -> None:
    # 统一注册应用拥有的私有扩展名，便于启动时审查配置。
    for extension, mime_type in CUSTOM_AUDIO_TYPES.items():
        mimetypes.add_type(mime_type, extension, strict=False)


# 在创建上传服务或路由之前完成一次初始化。
register_custom_types()

如果代码显式调用 mimetypes.init()，要把它安排在自定义注册之前。官方文档说明初始化会重建内部数据结构；在自定义映射之后重新初始化，可能让刚注册的内容不再处于你预期的状态。正常使用便捷函数时，模块会按需要初始化，通常不需要手动调用 init()。

在上传和响应处理中只消费识别结果

完成注册后，可以把类型推断封装成一个小函数供上传入口调用。关键点是对未知后缀保留明确的兜底策略，而不是把 None 拼成字符串发送给下游。

import mimetypes


def content_type_for(filename: str) -> str:
    # 由扩展名得到类型，encoding 另行保留，避免字段语义混淆。
    mime_type, encoding = mimetypes.guess_type(filename)
    if mime_type is None:
        # 未知后缀不能冒充音频类型，交给上层决定是否拒绝或人工确认。
        return "application/octet-stream"
    return mime_type


mimetypes.add_type("audio/x-sfx", ".sfx", strict=False)
print(content_type_for("concert.sfx"))

这个兜底值只代表“类型未知的二进制内容”，不代表文件一定不是音频。若业务必须限制音频格式，还需要在更高层结合允许列表、文件内容解析或专用媒体处理组件作决定；mimetypes 本身只负责扩展名到类型的映射。

常见问题

扩展名参数需要写成 .sfx 吗？

需要。调用 add_type() 时应传入带点的扩展名，例如 .sfx。实际推断时传入完整文件名或 URL，例如 concert.sfx。

注册后为什么别的服务还是识别不到？

注册只影响当前 Python 进程中的 mimetypes 映射。浏览器、反向代理、对象存储或另一种语言的服务不会自动同步这份配置，需要在对应系统中单独设置。

自定义类型应该使用 audio/x- 前缀吗？

可以把它作为团队约定的一种清晰写法，但真正要发送的类型应由你的协议、客户端和服务端约定。strict=False 只能表达“非标准映射”，不会替你注册一个全网通用的媒体标准。

guess_type() 返回的第二个值是什么？

返回值是 (type, encoding)。type 是可用于内容类型的字符串，encoding 表示文件名后缀推断出的编码信息；二者应按各自的 HTTP 或文件处理语义分别使用。