在 linux 中遇到 nginx 语法检查提示 error page code invalid,通常是因为配置文件中使用了非标准的 http 状态码(如自定义的三位数以外的数字),或者在 error_page 指令中错误地混用了重定向标志与无效的状态码。修复方法是确保 error_page 指令中的第一个参数是有效的 http 状态码(如 404、500)或特殊关键字 =,且不要将重定向标记(如 302)直接作为错误码使用。

如何正确编写 error_page 指令以处理特定状态码
要正确处理特定状态码引发的错误页面,必须严格遵循 error_page 指令的语法规范。该指令允许你指定一个或多个状态码,后跟一个 URI 路径。如果指定的状态码不在标准 HTTP 定义范围内(例如 600 或 999),Nginx 会拒绝加载配置并报错。正确的做法是使用标准的 4xx 和 5xx 状态码,并确保它们之间用空格分隔,而不是逗号或其他符号。

server {
listen 80;
server_name example.com;
# 正确写法:使用标准状态码 404 和 500
error_page 404 /custom_404.html;
error_page 500 502 503 504 /custom_50x.html;
location = /custom_404.html {
root /usr/share/nginx/html;
internal;
}
location = /custom_50x.html {
root /usr/share/nginx/html;
internal;
}
}
在上述配置中,error_page 404 /custom_404.html; 表示当发生 404 错误时,内部重定向到 /custom_404.html。注意,internal 指令用于限制只有内部重定向才能访问这些文件,防止用户直接通过 URL 访问。如果尝试使用 error_page 600 /test.html;,Nginx 会在启动时报错,因为 600 不是标准的 HTTP 状态码。
如何处理需要返回特定状态码的重定向场景
有时开发者希望错误页面不仅显示内容,还要返回特定的状态码,例如在维护页面中返回 503。这时需要使用 = 符号来明确指定返回的状态码。常见的误区是将重定向代码(如 301 或 302)直接放在 error_page 的第一个位置,这会导致解析错误。正确的做法是使用 =503 这样的语法,告诉 Nginx 即使原始错误是其他类型,最终也要返回 503 状态码。

server {
listen 80;
server_name example.com;
# 正确写法:使用 =503 强制返回 503 状态码
error_page 503 @maintenance;
location @maintenance {
return 503 "<html><body>Maintenance</body></html>";
}
# 错误写法示例(会导致 error page code invalid):
# error_page 302 /redirect.html;
# 解释:302 是重定向码,不应直接作为 error_page 的目标状态码,除非配合 = 使用
}
在上面的例子中,error_page 503 @maintenance; 定义了当发生 503 错误时,跳转到命名位置 @maintenance。在 @maintenance 中,使用 return 503 明确返回 503 状态码和内容。如果误写为 error_page 302 /page.html;,Nginx 可能会将其解析为试图将 302 作为错误码处理,从而引发语法错误。务必区分错误码(4xx/5xx)和重定向码(3xx)的使用场景,仅在需要覆盖返回码时使用 = 语法。
基于 error_page 指令中状态码与 URI 分离的具体问题
在实际配置中,一个常见的问题是混淆了状态码列表和 URI 路径的边界。例如,写成 error_page 404,500 /error.html;,其中使用了逗号分隔状态码,这是无效的。Nginx 要求状态码之间必须用空格分隔。另一个问题是 URI 路径前缺少斜杠,如 error_page 404 custom.html;,这可能导致路径解析错误。正确的格式是 error_page 404 /custom.html;,确保 URI 以根目录开始。此外,如果 URI 指向的是外部 URL,如 error_page 404 http://example.com/error.html;,则会触发外部重定向,而非内部处理,这可能不符合预期。


















