Svelte项目部署GitHub Pages后显示空白页求助

云原生阿岚

2026-7-29

Svelte项目部署GitHub Pages空白页问题排查修复

问题描述

本地执行npm run dev时项目显示正常，但部署到GitHub Pages后页面空白，<div id="app"></div>中无内容，尝试多种部署方法未解决。仓库名：CV-VioleauTamara。

当前配置文件

vite.config.js

import { defineConfig } from 'vite' import { svelte } from '@sveltejs/vite-plugin-svelte'

// https://vitejs.dev/config/ export default defineConfig({   base: "/cv-TamaraVioleau",   plugins: [svelte()], })

package.json

{
    "name": "my-app",
    "private": true,
    "version": "0.0.0",
    "type": "module",
    "scripts": {
        "dev": "vite",
        "build": "vite build",
        "preview": "vite preview",
        "deploy": "npx gh-pages -d dist"
    },
    "devDependencies": {
        "@sveltejs/vite-plugin-svelte": "^2.0.2",
        "gh-pages": "^5.0.0",
        "sass": "^1.58.3",
        "svelte": "^3.55.1",
        "vite": "^4.1.0"
    }
}

修复步骤

修正base路径大小写
GitHub Pages路径区分大小写，你的仓库名是CV-VioleauTamara，但vite.config.js中base设置为小写的/cv-TamaraVioleau，导致资源加载失败。修改为：
```
export default defineConfig({
  base: "/CV-VioleauTamara/",
  plugins: [svelte()],
})
```
注意末尾添加斜杠，避免路径解析异常。
验证构建产物
执行npm run build后，打开dist/index.html，检查JS、CSS等资源的引用路径是否为/CV-VioleauTamara/assets/xxx格式，确保路径正确。
确认GitHub Pages部署设置
进入仓库的GitHub Pages设置页，确认部署来源是gh-pages分支的根目录（gh-pages工具默认会把dist内容推到该分支根目录）。
强制刷新清除缓存
部署完成后，按Ctrl+F5强制刷新页面，避免浏览器缓存旧资源导致页面空白。
本地预览构建结果
执行npm run preview，在本地模拟生产环境查看页面是否正常，排查是否是构建过程中的问题。