Nuxt构建部署时如何替换错误页为自定义静态维护页？

针对你在Docker+Traefik架构下，Nuxt构建部署期间出现Bad Gateway的问题，以下是几个可行的落地方案：

方案1：通过Traefik错误页中间件全局捕获502/503错误 #

直接在反向代理层处理错误响应，无需修改业务容器，是最快速的解决方式。

1. 部署静态维护页服务
   新增一个基于Nginx的轻量容器，存放你的自定义维护页面：

# docker-compose.yml 新增维护页服务
services:
  maintenance-page:
    image: nginx:alpine
    volumes:
      - ./maintenance:/usr/share/nginx/html
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.maintenance.rule=Host(`localhost`)"
      - "traefik.http.routers.maintenance.service=maintenance-page"
      - "traefik.http.services.maintenance-page.loadbalancer.server.port=80"
    networks:
      - your-existing-network # 加入与Traefik、Nuxt相同的网络

将自定义维护页命名为502.html/503.html，放入本地./maintenance目录。

2. 配置Traefik错误页中间件
   在Traefik的labels中添加错误捕获规则：

services:
  traefik:
    # ... 现有配置
    labels:
      - "traefik.http.middlewares.maintenance-error.errors.status=502,503"
      - "traefik.http.middlewares.maintenance-error.errors.service=maintenance-page"
      - "traefik.http.middlewares.maintenance-error.errors.query=/{status}.html"

3. 将中间件绑定到Nuxt路由
   修改Nuxt容器的Traefik标签，应用错误处理中间件：

services:
  nuxt-app:
    # ... 现有配置
    labels:
      - "traefik.http.routers.nuxt-app.middlewares=maintenance-error@docker"

当Nuxt容器关闭或无法响应时，Traefik会自动返回你的自定义维护页，替代默认的Bad Gateway提示。

方案2：Nuxt容器优雅更新（彻底避免服务中断） #

通过滚动更新策略，确保旧容器在新容器完全就绪后再关闭，从根源上消除服务不可用窗口。

1. 配置Docker滚动更新规则
   在docker-compose.yml中为Nuxt容器添加部署策略：

services:
  nuxt-app:
    # ... 现有配置
    deploy:
      replicas: 2
      update_config:
        parallelism: 1
        delay: 10s
        order: start-first # 先启动新容器，再关闭旧容器

2. 添加服务健康检查
   配置Traefik仅向就绪的Nuxt容器转发流量，需先在Nuxt项目中添加健康检查接口（比如/health，返回200状态码），然后更新容器标签：

services:
  nuxt-app:
    # ... 现有配置
    labels:
      - "traefik.http.services.nuxt-app.loadbalancer.healthcheck.path=/health"
      - "traefik.http.services.nuxt-app.loadbalancer.healthcheck.interval=5s"
      - "traefik.http.services.nuxt-app.loadbalancer.healthcheck.timeout=2s"

3. 优化容器启动脚本
   修改Nuxt的Dockerfile，确保构建完成后再启动服务：

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
CMD ["sh", "-c", "npm run build && npm run start"]

更新时，新容器会先完成构建并通过健康检查，Traefik自动切换流量后再关闭旧容器，全程无服务中断。

方案3：构建期间临时替换Nuxt静态页 #

针对容器内部构建的场景，通过脚本在构建阶段临时替换首页为维护页：

1. 在Nuxt项目根目录创建maintenance.html，然后修改package.json的构建脚本：

{
  "scripts": {
    "prebuild": "cp maintenance.html dist/index.html",
    "build": "nuxt build",
    "postbuild": "rm dist/index.html && mv dist/.nuxt/dist/client/index.html dist/index.html"
  }
}

构建开始前，先将维护页复制为首页；构建完成后，再替换回正常的Nuxt生成首页，确保构建过程中访问站点能看到维护提示。

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