媒体类型配置
定义媒体类型及其后缀,供输出格式引用。
这一页解决什么问题
媒体类型(media type,旧称 MIME 类型)是「文件格式」的两段式名称,例如 text/html。Hugo 预置了常见格式与后缀的对应关系,输出格式再引用媒体类型来决定产物文件的扩展名与模板后缀。
只有两种场景需要动它:改某个媒体类型的后缀(此时必须同时重新定义引用它的输出格式),以及新建媒体类型(例如 Atom,或 Netlify 那种没有后缀的 _redirects)。
什么时候需要这些设置
| 设置 | 什么时候需要 | 改错了会看到什么现象 |
|---|---|---|
suffixes |
想改主后缀(数组第一位就是主后缀) | 改了默认媒体类型的后缀,却没重新定义引用它的输出格式 → 产物扩展名与模板查找用的后缀不一致,模板「找不到」(上游明确指出必须同时重定义) |
新建 mediaTypes.<类型> |
接入新格式(Atom、自定义文本格式) | 媒体类型名与引用处不一致 → 引用它的输出格式解析失败,构建报错 |
delimiter = '' |
需要生成无后缀文件(如 _redirects) |
只清空后缀却没清空分隔符 → 文件名里多出分隔符,不符合平台约定 |
媒体类型(media type,旧称 MIME 类型)是标识文件格式的两段式名称,例如 HTML 内容的媒体类型是 text/html。在 Hugo 中,已配置的媒体类型有多种用途,其中之一是定义输出格式。下文给出 mediaTypes 区段的键名与默认值,并说明如何修改、新建媒体类型,以及如何注册没有后缀的媒体类型。
键名与默认值
mediaTypes 是一个映射:键为媒体类型名(如 text/html),值为该媒体类型的设置表。
| 键名 | 类型 | 默认值 | 含义 |
|---|---|---|---|
mediaTypes |
map |
见下节默认表 | 媒体类型映射,键为媒体类型名。 |
mediaTypes.<类型>.delimiter |
string |
"." |
文件名与后缀之间的分隔符。分隔符与后缀共同构成文件扩展名。 |
mediaTypes.<类型>.suffixes |
[]string |
因媒体类型而异,见下节 | 与该媒体类型关联的后缀,第一个后缀是主后缀。 |
默认媒体类型
默认配置中的媒体类型及其后缀如下:
| 媒体类型 | 后缀 |
|---|---|
application/json |
json |
application/manifest+json |
webmanifest |
application/octet-stream |
无 |
application/pdf |
pdf |
application/rss+xml |
xml、rss |
application/source-map |
map |
application/toml |
toml |
application/wasm |
wasm |
application/xml |
xml |
application/yaml |
yaml、yml |
font/otf |
otf |
font/ttf |
ttf |
font/woff |
woff |
font/woff2 |
woff2 |
image/avif |
avif |
image/bmp |
bmp |
image/gif |
gif |
image/heic |
heic |
image/heif |
heif |
image/jpeg |
jpg、jpeg、jpe、jif、jfif |
image/png |
png |
image/svg+xml |
svg |
image/tiff |
tif、tiff |
image/webp |
webp |
text/asciidoc |
adoc、asciidoc、ad |
text/calendar |
ics |
text/css |
css |
text/csv |
csv |
text/html |
html、htm |
text/javascript |
js、jsm、mjs |
text/jsx |
jsx |
text/markdown |
md、mdown、markdown |
text/org |
org |
text/pandoc |
pandoc、pdc |
text/plain |
txt |
text/rst |
rst |
text/tsx |
tsx |
text/typescript |
ts |
text/x-gotmpl |
gotmpl |
text/x-sass |
sass |
text/x-scss |
scss |
video/3gpp |
3gpp、3gp |
video/mp4 |
mp4 |
video/mpeg |
mpg、mpeg |
video/ogg |
ogv |
video/webm |
webm |
video/x-msvideo |
avi |
表中的「后缀」一列就是各媒体类型关联的后缀。例如,Hugo 把 .html 和 .htm 文件与 text/html 媒体类型关联起来;application/octet-stream 在默认配置中没有定义后缀。
注意 第一个后缀是主后缀。为模板文件命名时应使用主后缀。例如为 RSS feed 创建模板时,使用
xml后缀。
修改媒体类型
可以修改任何默认媒体类型。例如把 text/html 的主后缀从 html 换成 htm:
[mediaTypes.'text/html']
suffixes = ['htm','html']注意这里把 htm 放在了数组首位,因此它成为主后缀。
如果改动了某个默认媒体类型,就必须同时显式地重新定义所有使用该媒体类型的输出格式。例如,要让上面的改动作用于 html 输出格式,就要重新定义它:
[outputFormats.html]
mediaType = 'text/html'新建媒体类型
可以按需新建媒体类型。例如为 Atom feed 新建一个媒体类型:
[mediaTypes.'application/atom+xml']
suffixes = ['atom']注册之后,就可以在输出格式的 mediaType 设置里引用它,具体写法参见输出格式配置。
无后缀的媒体类型
有时需要创建既没有后缀、也没有分隔符的媒体类型。例如 Netlify 会识别名为 _redirects 和 _headers 的配置文件,而 Hugo 可以用自定义输出格式生成它们。
为此,注册一个不带后缀和分隔符的媒体类型:
[mediaTypes.'text/netlify']
delimiter = ''对应的自定义输出格式定义大致如下:
[outputFormats.redir]
baseName = '_redirects'
isPlainText = true
mediatype = 'text/netlify'
[outputFormats.headers]
baseName = '_headers'
isPlainText = true
mediatype = 'text/netlify'
notAlternative = true常见坑
| 症状 | 真因 | 怎么修 |
|---|---|---|
| 改了后缀,产物扩展名却没变 | 只改了 mediaTypes,没有重新定义使用它的输出格式 |
像本页示例那样同时写 [outputFormats.html] 并设 mediaType = 'text/html' |
| 自定义模板不被使用 | 模板文件名用了非主后缀;主后缀是 suffixes 的第一项 |
用主后缀命名模板,例如 RSS 用 xml |
| 生成的文件名与平台约定不符 | 清了后缀却没有把 delimiter 也设为空 |
两者都留空:delimiter = '',并在输出格式里用 baseName 指定文件名 |
| 构建报「找不到类型」一类错误 | 媒体类型名与引用处不一致(大小写、斜杠、拼写) | 用 hugo config 确认 [mediatypes] 中的键名,再核对输出格式的 mediaType |
更多排查入口见故障排查。