SvelteKit构建后路由未生成及静态访问异常问题

问题现象 #

• npm run dev模式下应用路由完全正常，但执行npm run build后：
  • 用VS Code Live Server访问dist目录，或执行npx serve dist时，/tree、/v1等非根路由无法访问（返回404）
  • 仅通过npx serve dist --single能正常访问所有路由
• dist目录未生成/tree或/v1对应的物理目录
• 目标是部署到虚拟机Nginx静态服务器（无需Node服务），但部署失败

核心原因 #

SvelteKit使用客户端路由（SPA模式）时，所有路由逻辑由前端处理，不需要对应物理目录。普通静态服务器默认会寻找对应路径的文件，找不到就返回404；而--single模式会将所有请求转发到index.html，由前端路由接管。你的adapter-static配置已设置fallback: index.html，但还需配合客户端渲染配置和Nginx重写规则才能生效。

解决方案 #

1. 修正SvelteKit配置 #

修改svelte.config.js，确保适配SPA静态部署：

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

/** @type {import('@sveltejs/kit').Config} */
const config = {
  kit: {
    adapter: adapter({
      pages: 'dist',
      assets: 'dist',
      fallback: 'index.html', // 关键：指定SPA fallback页面
    }),
    paths: {
      base: '',
    },
    // 根据需求选择渲染模式：
    // 方案A：纯客户端SPA（所有路由由前端处理）
    prerender: { enabled: false },
    // 方案B：预渲染所有可访问路由（需确保路由无客户端专属依赖）
    // prerender: { entries: ['*'] },
  },
  preprocess: vitePreprocess(),
};

export default config;

同时在src/routes/+layout.js中添加渲染模式声明：

// 纯客户端SPA模式（对应方案A）
export const ssr = false;

// 预渲染模式（对应方案B）
// export const prerender = true;

2. 本地验证 #

修改配置后重新构建并验证：

npm run build
npx serve dist --single

此时所有路由应正常访问，dist目录仍不会生成/tree、/v1物理目录，属于正常现象。

3. Nginx服务器配置 #

编辑Nginx站点配置文件（如/etc/nginx/sites-available/your-app.conf），添加路由重写规则：

server {
    listen 80;
    server_name 你的虚拟机IP或域名;

    root /dist目录的绝对路径;
    index index.html;

    # 将所有请求转发到index.html，由前端路由处理
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源缓存优化（可选）
    location ~* \.(js|css|png|jpg|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

配置完成后重启Nginx：

sudo systemctl restart nginx

4. 排查要点 #

• 检查build日志，确认无预渲染失败或配置错误提示
• 若使用预渲染模式，确保所有路由无客户端专属依赖（如浏览器API），否则会导致预渲染失败
• Live Server默认不支持SPA路由重写，本地验证优先使用npx serve dist --single

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