SvelteKit网站全局维护页面实现方案咨询（部署于Vercel）

方案一：利用全局错误页面（推荐） #

通过抛出503错误，让根级+error.svelte捕获并展示自定义维护界面，无需额外路由，逻辑更简洁。

步骤1：配置环境变量 #

• 开发环境：在.env文件中设置VITE_MAINTENANCE_MODE=1
• Vercel生产环境：在项目设置的「环境变量」中添加MAINTENANCE_MODE=1（服务器端用process.env读取，客户端用import.meta.env）

步骤2：修改根+layout.server.js #

在根目录的+layout.server.js中编写维护模式判断逻辑：

import { error } from '@sveltejs/kit';

export async function load() {
  // 区分开发/生产环境的环境变量读取方式
  const isMaintenance = import.meta.env.MODE === 'development' 
    ? import.meta.env.VITE_MAINTENANCE_MODE === '1'
    : process.env.MAINTENANCE_MODE === '1';

  if (isMaintenance) {
    // 抛出带自定义信息的503错误
    throw error(503, {
      message: '系统维护中',
      details: '预计1小时后恢复服务，感谢您的耐心等待'
    });
  }
}

步骤3：创建根级+error.svelte #

在src/routes/目录下创建+error.svelte，自定义503维护页面：

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

{#if $page.status === 503}
  <div class="maintenance-container">
    <h1>🔧 系统维护中</h1>
    <p>{$page.error.message}</p>
    <p>{$page.error.details}</p>
  </div>
{:else}
  <div class="error-container">
    <h1>{$page.status} 错误</h1>
    <p>{$page.error.message}</p>
  </div>
{/if}

<style>
  .maintenance-container {
    text-align: center;
    padding: 5rem 2rem;
    font-family: sans-serif;
  }
  h1 {
    font-size: 2.5rem;
    color: #ff6b6b;
  }
  p {
    font-size: 1.2rem;
    color: #333;
    margin: 0.5rem 0;
  }
</style>

之前错误页面不生效的原因：

• 需确保+error.svelte放在根路由目录（src/routes/），才能捕获全局错误
• SvelteKit在SSR模式下优先使用+error.svelte，src/error.html仅作为极端情况的静态 fallback，不会替代自定义错误组件

方案二：全局重定向到自定义维护路由 #

若偏好使用独立的/maintenance路由，优化重定向逻辑避免循环，同时兼容生产环境：

步骤1：创建/maintenance路由 #

在src/routes/maintenance/+page.svelte中编写维护页面：

<div class="maintenance-page">
  <h1>系统维护中</h1>
  <p>我们正在进行系统升级，暂时无法访问。</p>
  <p>请稍后再试！</p>
</div>

<style>
  .maintenance-page {
    text-align: center;
    padding: 6rem 2rem;
    font-family: Arial, sans-serif;
  }
</style>

步骤2：修改根+layout.server.js #

import { redirect } from '@sveltejs/kit';

export async function load({ url }) {
  const isMaintenance = import.meta.env.MODE === 'development' 
    ? import.meta.env.VITE_MAINTENANCE_MODE === '1'
    : process.env.MAINTENANCE_MODE === '1';

  const isMaintenanceRoute = url.pathname === '/maintenance';

  if (isMaintenance) {
    // 已在维护路由则放行，否则重定向
    if (!isMaintenanceRoute) {
      throw redirect(307, '/maintenance');
    }
  } else {
    // 维护模式关闭时，访问维护路由重定向到首页
    if (isMaintenanceRoute) {
      throw redirect(307, '/');
    }
  }
}

步骤3：Vercel环境变量补充 #

• Vercel中设置的MAINTENANCE_MODE默认仅服务器端可用，无需加VITE_前缀（若需客户端感知，可在根布局中把状态传给客户端）
• 如需客户端侧兜底重定向，可在+layout.svelte中添加：

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

{#if data.isMaintenance && $page.url.pathname !== '/maintenance'}
  <script>
    window.location.href = '/maintenance';
  </script>
{/if}

验证与部署 #

• 开发环境：启动项目并设置VITE_MAINTENANCE_MODE=1，访问任意路由应触发维护界面
• 生产环境：在Vercel中设置MAINTENANCE_MODE=1后重新部署；关闭维护模式时，只需将环境变量值改为0并重新部署（或使用Vercel环境变量即时更新功能）

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