如何在SvelteKit中添加自定义404页面及其他错误场景的通用错误页

1 实现独立自定义404页面 #

如果你需要和通用错误页完全隔离的404页面，用SvelteKit的兜底路由方案实现即可：

• 进入src/routes目录，创建名为[...not_found]的文件夹
• 在新建的文件夹内创建+page.svelte文件，编写你的404页面内容，示例代码如下：

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

  export function load({ setHeaders }) {
    // 明确设置404状态码，同时设置不缓存避免CDN缓存错误页面
    setHeaders({
      'Cache-Control': 'no-cache, no-store, must-revalidate'
    });
  }
</script>

<div class="not-found-wrapper">
  <h1>404 页面不存在</h1>
  <p>你访问的路径 <code>{$page.url.pathname}</code> 未找到，请检查地址是否正确</p>
  <a href="/">点击返回首页</a>
</div>

该路由会自动匹配所有未被其他路由规则命中的请求，完全独立于通用错误逻辑。

2 实现独立通用错误页面 #

通用错误页用于处理所有非404的运行时异常，比如接口请求失败、权限不足、服务端内部错误等场景：

• 在src/routes根目录下创建+error.svelte文件，这个文件是SvelteKit的全局错误边界，会捕获所有子路由抛出的未处理错误
• 你可以直接调用SvelteKit自动注入的status（错误状态码）、error（错误对象）参数来渲染对应的错误信息，示例代码如下：

<script>
  export let status;
  export let error;
</script>

<div class="error-wrapper">
  <h1>错误 {status}</h1>
  <p class="error-message">{error.message}</p>
  
  <!-- 仅开发环境展示错误详情，生产环境自动隐藏避免泄露敏感信息 -->
  {#if import.meta.env.DEV}
    <details class="error-details">
      <summary>查看错误栈信息</summary>
      <pre><code>{error.stack}</code></pre>
    </details>
  {/if}

  <div class="action-buttons">
    <button onclick="history.back()">返回上一页</button>
    <a href="/">返回首页</a>
  </div>
</div>

可选简化方案 #

如果你不需要完全独立的两个页面，也可以直接在根+error.svelte内通过状态码判断渲染逻辑，当status === 404时渲染404内容，其他状态渲染通用错误内容，仅需维护一个文件即可。

注意事项 #

• 错误页面内不要引入可能抛出异常的组件或逻辑，避免触发错误死循环
• 生产环境下SvelteKit会自动隐藏错误栈等敏感信息，无需额外手动处理
• 兜底路由的404页面必须明确设置404状态码，否则搜索引擎会将错误页面判定为正常内容收录

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