SvelteKit应用通过Azure Static Web Apps本地启动后无页面显示问题排查

尝试用Azure Static Web Apps（SWA）本地启动SvelteKit应用，按配置完成后启动无法显示页面，访问http://localhost:4280时提示找不到404.html，CLI报错：

swa cli request error:
GET http://localhost:4280/404.html - 404

配置详情 #

Svelte配置（svelte.config.js） #

import azure from 'svelte-adapter-azure-swa';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

export default {
  kit: {
    adapter: azure()
  },
  preprocess: vitePreprocess()
};

Azure Static Web Apps配置（staticwebapp.config.json） #

{
  "routes": [
    {
      "route": "/*",
      "allowedRoles": ["anonymous", "authenticated"]
    }
  ],
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["*.{css,scss,js,png,gif,ico,jpg,svg}"]
  },
  "globalHeaders": {
    "X-Content-Type-Options": "nosniff"
  },
  "mimeTypes": {
    ".json": "text/json"
  }
}

启动命令 #

swa start

已尝试步骤 #

• 核对参考项目配置说明
• 确认staticwebapp.config.json的路由和导航回退配置正确性

环境信息 #

• SvelteKit版本：^2.0.0
• svelte-adapter-azure-swa：^0.20.0
• Azure Static Web Apps CLI版本：1.1.7
• 操作系统：Windows 11

问题原因与解决方法 #

1. 未预先构建SvelteKit应用 #

SWA CLI需要读取SvelteKit的构建产物才能正常启动，直接执行swa start会找不到编译后的静态资源。

解决操作：
先执行构建命令：

npm run build

再指定构建目录启动SWA：

swa start ./build

（若自定义了适配器输出目录，替换为对应路径）

2. 导航回退配置不匹配SSR模式 #

当前navigationFallback指向静态index.html，但SvelteKit SSR模式下需回退到适配器生成的server入口。

修改配置：
更新staticwebapp.config.json中的navigationFallback字段：

"navigationFallback": {
  "rewrite": "/server",
  "exclude": ["*.{css,scss,js,png,gif,ico,jpg,svg}"]
}

3. SWA CLI版本兼容性问题 #

旧版本SWA CLI（1.1.7）与SvelteKit 2.x存在兼容性问题，导致资源加载异常。

解决操作：
更新到最新版CLI：

npm install -g @azure/static-web-apps-cli@latest

4. 缺少自定义错误页面 #

SWA默认会请求404.html，但项目中未生成该文件，需在SvelteKit中创建错误页面。

解决操作：
在src/routes目录下创建+error.svelte：

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

<h1>{$page.status} 错误</h1>
<p>页面不存在或无法正常访问</p>

重新构建后启动即可自动生成对应错误页面。

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