配置

服务器配置

配置 Hugo 开发服务器的请求头与重定向规则。

难度
进阶
预计用时
10–15 分钟

开始之前,你需要

  • 站点能正常构建,并知道 config/ 目录可以按环境拆分配置(见配置简介)。
  • 用过 hugo server 在本地预览,会打开浏览器开发者工具。

读完之后你能

  • 把开发服务器专用配置放进 config/development/,不污染生产构建;
  • 写出响应头与重定向规则,并在浏览器里确认它们生效;
  • 在自定义重定向之后补回 404 规则,多语言站点把默认语言规则放在最后。

接着读:配置简介 · 故障排查

这一页解决什么问题

[server] 只作用于 hugo server(本地开发服务器),用来在本地模拟线上行为:加响应头(尤其是 CSP)、写重定向、指定 404 页面。它不影响正式构建,所以推荐把它放进 config/development/,别混进生产配置。

你应当看到什么:hugo server 之后,在浏览器开发者工具的 Network 面板里检查响应头与重定向跳转链;而 hugo 正式构建的产物里不会体现这些设置。

什么时候需要这些设置

设置 什么时候需要 改错了会看到什么现象
[[headers]] 想在上线前验证 CSP、X-Frame-Options 等响应头 for 的路径模式写错 → 响应头不生效,没有任何提示,本地看起来「CSP 没问题」
[[redirects]] 本地调试重定向、单页应用(SPA)的 URL 重写 只有 status = 200 才触发 URL 重写;写成 301/302 会真的跳转,SPA 刷新后地址会变
force 即使该路径下已存在内容也要强制重定向 置 true 会盖住真实存在的页面,本地表现与线上不一致
404 规则 自定义了任何重定向之后 上游明确:一旦定义了其他重定向,就必须显式补上 404 规则,否则不存在的 URL 不再落到 /404.html

这些设置只作用于 Hugo 的开发服务器,因此推荐为开发环境单独建立一个配置目录,把服务器配置放在其中:

project/
└── config/
    ├── _default/
    │   └── hugo.toml
    └── development/
        └── server.toml

配置目录的用法见 /configuration/。

默认设置

对于请求了并不存在的 URL,开发服务器默认重定向到 /404.html,详见下文的 404 错误一节。

重定向键

键名 类型 默认值 说明
force bool false 即使该路径下已存在内容,也强制重定向。
from string 无 匹配请求 URL 的 glob 模式。from 与 fromRE 必须至少设置一个;若两者都设置,URL 必须同时匹配两者。
fromHeaders map[string][string] 无 重定向需要匹配的请求头,把 HTTP 头名称映射到待匹配取值的 glob 模式。该映射为空时重定向总是触发。0.144.0 版本新增。
fromRe string 无 匹配请求 URL 的正则表达式。from 与 fromRE 必须至少设置一个;若两者都设置,URL 必须同时匹配两者。正则的捕获组可在 to 字段中以 $1、$2 等引用。0.144.0 版本新增。
status string 无 重定向使用的 HTTP 状态码。状态码为 200 时会触发 URL 重写。
to string 无 把请求转发到的目标 URL。

响应头

在每个服务器响应中都加入响应头,便于测试,尤其是内容安全策略(CSP)这类功能:

toml
[[headers]]
for = '/**'

[headers.values]
X-Frame-Options = 'DENY'
X-XSS-Protection = '1; mode=block'
X-Content-Type-Options = 'nosniff'
Referrer-Policy = 'strict-origin-when-cross-origin'
Content-Security-Policy = 'script-src localhost:1313'

for 用于匹配请求路径,headers.values 下的键值对会原样写入响应头。

重定向

可以定义简单的重定向规则:

toml
[[redirects]]
from = '/myspa/**'
to = '/myspa/'
status = 200
force = false

示例中的 200 状态码会触发 URL 重写,这通常是单页应用(SPA)想要的行为。

404 错误

开发服务器默认把任何指向不存在 URL 的请求重定向到 /404.html。

如果已经定义了其他重定向,就必须显式补上这条 404 重定向:

toml
[[redirects]]
force = false
from   = '/**'
to     = '/404.html'
status = 404

多语言项目要确保默认语言的 404 重定向定义在最后:

toml
defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = false
[[redirects]]
from = '/fr/**'
to = '/fr/404.html'
status = 404

[[redirects]] # 默认语言必须放在最后。
from = '/**'
to = '/404.html'
status = 404

当默认语言放在子目录中提供服务时:

toml
defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true
[[redirects]]
from = '/fr/**'
to = '/fr/404.html'
status = 404

[[redirects]] # 默认语言必须放在最后。
from = '/**'
to = '/en/404.html'
status = 404

完整示例

只保留开发环境需要的内容,可把开发服务器配置单独放在 config/development/server.toml:

toml
[[headers]]
for = '/**'

[headers.values]
X-Content-Type-Options = 'nosniff'

[[redirects]]
from = '/myspa/**'
to = '/myspa/'
status = 200
force = false

[[redirects]]
force = false
from   = '/**'
to     = '/404.html'
status = 404

常见坑

症状 真因 怎么修
加了 headers / redirects,本地毫无变化 写进了生产配置,或 config/development/ 没有被读到(hugo server 默认环境是 development) 用 hugo config --environment development 确认这些键是否生效
不存在的 URL 不再落到 404 页面 定义了其他重定向后,没有显式补回 404 规则 按本页示例补 from = '/**'、status = 404 的规则
多语言站点只有部分语言的 404 生效 默认语言的规则没有放在最后(上游明确要求) 把默认语言的 [[redirects]] 移到数组末尾
SPA 刷新后地址变了 用了 301/302,而 URL 重写需要 status = 200 改成 status = 200;确实需要跳转时才用 3xx
报错看不懂 这类配置基本不报错,症状是「行为与预期不符」 见故障排查

更多排查入口见故障排查。