SvelteKit适配Node时构建/后端宕机如何配置503维护页？

针对你遇到的构建阶段后端不可用、后端宕机/维护时抛出500错误的问题，结合Adapter Node、NGINX、PM2环境，分场景给出配置方案：

一、构建阶段的503页面处理 #

构建时若因后端不可达导致请求失败，可通过SvelteKit的错误捕获机制返回503状态及维护页：

1. 编写路由级错误捕获逻辑
   在根路由的+page.server.js中，捕获后端请求失败的异常并抛出503错误：

export async function load({ fetch }) {
  try {
    // 替换为你的后端接口请求逻辑
    const res = await fetch('http://your-strapi-domain/api/data');
    if (!res.ok) throw new Error('Backend unavailable');
    return { data: await res.json() };
  } catch (err) {
    // 抛出带503状态码的错误
    throw new Error('Service Unavailable', { status: 503 });
  }
}

2. 创建全局错误页
   在项目根目录新建+error.svelte，根据状态码渲染维护页内容：

<script>
  import { page } from '$app/stores';
</script>

{#if $page.status === 503}
  <div style="text-align:center; padding:2rem; max-width:600px; margin:0 auto;">
    <h1>服务维护中</h1>
    <p>我们正在进行例行维护，预计不久后恢复服务，请稍后重试。</p>
  </div>
{:else}
  <h1>服务器错误</h1>
  <p>抱歉，出现了未知错误，请稍后再试。</p>
{/if}

二、后端宕机/维护时的NGINX层面处理 #

通过NGINX反向代理直接拦截请求，比应用层处理更高效，还能覆盖SvelteKit服务本身宕机的场景：

1. 准备静态503资源
   在NGINX可访问的目录（如/var/www/maintenance）下创建503.html及配套静态资源（如CSS、图片），确保页面内容符合维护场景。

2. 修改NGINX站点配置
   编辑你的站点配置文件（如/etc/nginx/sites-available/your-sveltekit-app）：

server {
  listen 80;
  server_name your-domain.com;

  # 可通过文件开关触发维护模式
  set $maintenance off;
  if (-f /var/www/maintenance/maintenance_on) {
    set $maintenance on;
  }

  # 维护模式开启时直接返回503
  if ($maintenance = on) {
    return 503;
  }

  location / {
    proxy_pass http://localhost:3000; # 对应SvelteKit的Node服务端口
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # 拦截后端返回的5xx错误，重定向到503页
    proxy_intercept_errors on;
    error_page 500 502 503 504 = /503.html;
  }

  # 处理503页请求，返回正确状态码
  location = /503.html {
    root /var/www/maintenance;
    add_header Content-Type text/html;
    add_header Retry-After 3600; # 告知客户端1小时后重试
    return 503;
  }

  # 维护页静态资源路由
  location /maintenance-assets/ {
    root /var/www/maintenance;
  }
}

配置生效后：

• 手动创建/var/www/maintenance/maintenance_on文件，即可全局触发维护模式
• 当SvelteKit服务或Strapi后端宕机时，NGINX会自动返回503维护页

三、PM2配合维护模式 #

在重启SvelteKit服务的短暂窗口，可通过脚本自动触发/关闭维护模式：

# 开启维护模式
touch /var/www/maintenance/maintenance_on

# 重启PM2管理的SvelteKit服务
pm2 restart your-sveltekit-app

# 服务启动完成后关闭维护模式（按需调整等待时间）
sleep 10
rm /var/www/maintenance/maintenance_on

四、SvelteKit全局错误兜底 #

在src/hooks.server.js中添加全局错误处理，覆盖所有未被路由捕获的后端异常：

export async function handleError({ error, event }) {
  if (error.message.includes('Backend unavailable') || error.status === 503) {
    return {
      status: 503,
      message: '服务维护中，请稍后重试'
    };
  }
  return {
    status: error.status || 500,
    message: error.message || '服务器错误'
  };
}

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