如何配置NGINX宕机、重载及应用构建时加载自定义提示HTML模板

核心逻辑 #

前端构建流程执行时，当前root指向的build目录内容会被临时清空、替换，这一时间段内nginx无法找到默认的index.html资源，就会返回内置的通用错误提示页。只要把自定义提示页存放在构建流程完全不会触碰的固定路径，再通过nginx的错误页规则将构建时段的异常请求定向到这个自定义页，就能实现目标效果。
必须将自定义提示页放在build目录外部，否则构建清空目录时提示页本身也会被删除，完全无法生效。原有配置里的server块基础逻辑并不是问题根源，出现默认提示页的核心原因是没有绑定自定义错误页规则，nginx直接返回了内置默认模板。

具体配置修改步骤 #

1. 存放自定义提示文件
   新建和构建流程解耦的存放目录，比如/home/smiling/smiling-frontend/shared/，把写好的提示页（不管是叫403.html还是maintenance.html，内容可自定义为“当前正在更新部署，暂不可访问”这类提示）放到这个目录下。
2. 新增错误页定向规则
   在现有server块内部加入错误页映射，把构建过程中常见的缺失资源、服务临时异常的状态码，全部定向到自定义提示页的访问路径：

   # 把常见异常状态码统一导向自定义提示页
   error_page 404 403 500 502 503 = /maintenance.html;
   

3. 新增自定义提示页的访问规则
   因为提示页不在现有root指向的build目录下，需要单独写location用alias指向实际的文件路径，避免走现有root路径找文件失败：

   location = /maintenance.html {
       # 指向build目录外部的提示页实际路径
       alias /home/smiling/smiling-frontend/shared/maintenance.html;
       # 关闭提示页缓存，避免用户长时间留存旧的维护状态
       add_header Cache-Control "no-store, no-cache, must-revalidate";
   }
   

4. 原有location规则适配
   现有location /块的try_files逻辑不需要大改：
   • 构建过程中，build目录为空，请求找不到对应资源，最终触发对应的异常状态码，自动匹配之前配置的error_page规则，返回自定义提示页
   • 构建完成后，build目录下的index.html恢复正常，try_files能找到对应资源，正常返回前端页面，不会触发维护页规则

注意事项 #

• 如果自定义提示页需要引入css、图片等静态资源，这些资源也必须存放在build目录外部，否则构建过程中同样会加载失败
• 不要在提示页的配置上开启长期缓存，否则构建完成后，用户浏览器可能还缓存着旧的“正在维护”页面
• 现有配置中Access-Control-Allow-Origin '*/'的写法不符合CORS规范，后续可以调整为合法的'*'（或指定可访问的域名），避免前端跨域请求异常

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