Svelte+Vite部署GitHub Pages后页面空白问题咨询

操作流程 #

• 通过VSCode的「发布仓库」按钮推送项目
• 在package.json中新增部署命令："deploy": "npx gh-pages -d dist"
• 执行构建命令：npm run build
• 执行部署命令：npm run deploy
• 修改vite.config.js，添加基础路径配置：base: "/lilys-website/",
• 重新执行npm run build和npm run deploy

问题现象 #

页面仅加载CSS资源，整体显示空白，推测JS资源未正常加载，但浏览器开发者工具中无任何文件加载错误提示。

排查与解决方法 #

1. 确认base配置准确性 #

确保vite.config.js中的base值与GitHub仓库名称完全匹配（注意大小写敏感），正确配置示例：

export default defineConfig({
  base: "/lilys-website/",
  // 其他项目配置
})

2. 检查构建产物路径 #

执行npm run build后，查看dist目录下的index.html，确认其中JS资源的引用路径是否为/lilys-website/assets/xxx.js格式，避免相对路径错误导致资源无法定位。

3. 验证GitHub Pages部署分支 #

登录GitHub仓库后台，进入「Settings」→「Pages」页面，确认部署来源为gh-pages分支的根目录（/root），而非其他分支或子路径。

4. 强制清除浏览器缓存 #

浏览器缓存可能导致旧资源未更新，可使用快捷键Ctrl+Shift+R（Windows/Linux）或Cmd+Shift+R（Mac）强制刷新页面，或通过无痕模式访问验证。

5. 前端路由模式适配（若使用路由） #

如果项目使用了前端路由且为history模式，需在public目录下创建404.html文件，内容与index.html完全一致，确保GitHub Pages能正确重定向路由请求。

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