AWS Amplify部署静态Svelte-Kit应用访问空白页问题求助

按优先级从上到下排查，90%的问题都能在前两步定位：

• 第一步：先看浏览器控制台报错
  打开应用URL按F12切到Console面板，先看具体错误，不要上来就改adapter：
  • 如果报一堆JS/CSS资源404：是资源引用路径或者重写规则的问题，按后面静态部署的配置改就行
  • 如果报window is not defined/document is not defined：是hydration失败，直接看最后一步的解决方案
  • 如果报503/权限错误：是SSR部署模式没开对，看第二步的SSR配置说明
• 第二步：匹配adapter和Amplify托管模式
  两种部署模式只能选一种，混配必出问题：
  1. 纯静态部署（新手优先选，配置简单无额外成本）
     • 卸载其他adapter，只安装@sveltejs/adapter-static，svelte.config.js配置如下：

       import adapter from '@sveltejs/adapter-static';
       
       /** @type {import('@sveltejs/kit').Config} */
       const config = {
         kit: {
           adapter: adapter({
             fallback: 'index.html', // *必须配置*，支持客户端路由跳转
             strict: true
           })
         }
       };
       
       export default config;
       

     • 项目根目录新建空文件命名为.nojekyll，避免Amplify过滤下划线开头的Svelte构建资源
     • Amplify构建设置中，构建输出目录填build，构建命令保持默认的npm run build即可
     • 进入Amplify控制台的「重写和重定向」设置，添加如下200重写规则，解决前端路由刷新404/资源加载失败问题：

       源路径：</^[^.]+$|\.(?!(css|gif|ico|jpg|js|png|txt|svg|woff|woff2|ttf|map|json|webp)$)([^.]+$)/>
       目标路径：/index.html
       规则类型：200 (Rewrite)

  2. SSR部署模式
     • 卸载其他adapter，只安装@sveltejs/adapter-node，不要自定义adapter的输出路径配置，保持默认即可
     • Amplify构建设置里，框架预设直接选SvelteKit，平台会自动识别SSR构建产物、分配计算资源，不要手动把输出目录改成静态托管的路径
     • 确认Amplify关联的服务角色有Lambda、CloudFront相关权限，权限不足会导致SSR函数无法正常响应，返回空白页
• 第三步：排查Hydration失败问题
  如果控制台没有资源404、没有服务端错误，只报hydration相关异常，检查所有用到window、document、浏览器本地存储等仅客户端存在的API的代码，全部放到onMount生命周期里执行，不要在组件顶层、load函数里直接调用这类API，否则服务端预渲染阶段会直接中断，导致页面空白。
  错误写法示例：

  <script>
    // 顶层直接调用，服务端渲染时会报错
    const token = window.localStorage.getItem('token')
  </script>
  

  正确写法示例：

  <script>
    import { onMount } from 'svelte'
    let token = ''
    onMount(() => {
      // 仅在客户端执行，不会触发服务端报错
      token = window.localStorage.getItem('token')
    })
  </script>
  

• 第四步：核对构建配置细节
  检查构建日志里的警告信息，如果出现"base path mismatch"、"fallback page not generated"类警告，检查svelte.config.js里的kit.paths配置，根域名部署的话不要随意设置base参数，保持默认空值即可，子目录部署才需要填对应的子路径。

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