Nginx使用@maintenance指令无法加载自定义维护页面问题

问题场景 #

尝试通过Nginx实现：当系统中存在/var/www/html/maintenance_mode_on文件时，跳转到包含独立CSS/JS的自定义维护页面，但目前仅显示Nginx标准503页面。

原配置代码 #

location / {
        if (-f /var/www/html/maintenance_mode_on){
            return 503;
        }
        root /var/www/html/my_normal_site/;
        index index.html index.htm;
}
error_page 503 @maintenance;
location @maintenance {
        root /var/www/html/maintenance/;
        index maintenance.html;
}

问题原因 #

1. 原配置仅处理了根路径的503跳转，维护页面中引用的CSS/JS等静态资源请求会走默认的/ location。此时因为维护文件存在，这些资源请求会被返回503，导致资源加载失败，最终只能显示Nginx默认503页面。
2. @maintenance location的root配置会让Nginx尝试在/var/www/html/maintenance/下查找请求路径对应的文件，而非直接返回maintenance.html，当请求非根路径时会匹配失败。

修正后的配置方案 #

# 优先处理维护页面的静态资源请求，避免被维护拦截
location ^~ /maintenance/ {
    root /var/www/html/;
}

location / {
    if (-f /var/www/html/maintenance_mode_on) {
        return 503;
    }
    root /var/www/html/my_normal_site/;
    index index.html index.htm;
}

error_page 503 @maintenance;
location @maintenance {
    root /var/www/html/;
    # 将所有请求重写到维护页面
    rewrite ^(.*)$ /maintenance/maintenance.html break;
}

关键说明 #

• location ^~ /maintenance/：使用^~确保该location优先匹配，让维护页面的静态资源（如/maintenance/css/style.css）能直接从/var/www/html/maintenance/目录加载，不受维护判断逻辑影响。
• rewrite ^(.*)$ /maintenance/maintenance.html break：将所有触发503的请求强制重写到自定义维护页面，确保无论请求路径是什么，都返回维护页内容。
• 维护页面的资源引用路径要对应实际目录结构，比如CSS文件如果放在/var/www/html/maintenance/css/，页面中应写为/maintenance/css/style.css。

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