Planethoster cPanel部署Svelte应用遇白屏问题求助

以下是针对你遇到的白屏问题的分步排查和解决方法：

1. 先确认本地Build产物正常 #

在本地执行npm run build后，用本地静态服务器测试产物是否能正常运行：

npx serve build

如果本地访问也白屏，说明问题出在项目本身，先检查：

• 若应用部署在子目录，需在svelte.config.js中设置base路径，比如部署到example.com/my-svelte-app，则添加：

  const config = {
    kit: {
      paths: {
        base: '/my-svelte-app',
      },
      // 其他配置...
    }
  };
  

• 检查npm run build的输出日志，修复所有编译报错后重新build。

2. 正确上传Build文件到cPanel #

• cPanel主域名的根目录是public_html，需将build文件夹内的所有文件（而非build文件夹本身）上传到这里；如果是子域名，上传到对应子域名的根目录（比如sub.example.com对应public_html/sub）。
• 不要直接上传整个build文件夹，否则访问路径会多一层/build，导致静态资源加载失败。

3. 检查文件权限 #

选中所有上传的文件和文件夹，右键设置权限：

• 文件权限设为644
• 文件夹权限设为755
  权限错误会导致浏览器无法读取静态资源，出现403错误进而引发白屏。

4. 处理路由问题（若使用路由） #

如果你的Svelte应用用到了路由库（如svelte-kit内置路由或第三方路由），需要配置URL重写避免刷新/直接访问路由时白屏：
在网站根目录创建或修改.htaccess文件，添加以下规则：

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

这个规则会将所有非文件/非目录的请求指向index.html，确保路由能正常工作。

5. 针对SSR应用的Node环境配置（若适用） #

如果你的Svelte应用是服务端渲染（SSR）类型，不能只传静态文件，需在cPanel中配置Node.js环境：

• 登录cPanel，找到「Node.js」工具
• 创建新应用，设置应用根目录（比如public_html/your-app），选择与本地开发兼容的Node版本
• 上传完整项目文件（包括package.json、服务器端代码等），然后在Node.js工具中执行npm install安装依赖
• 设置启动文件（如server.js），并启动应用，确保cPanel映射的端口正确

6. 浏览器调试定位问题 #

打开浏览器开发者工具（F12）：

• 「控制台」标签查看是否有JS报错、资源加载失败提示
• 「网络」标签检查所有静态资源（JS、CSS、图片）的状态码，若出现404，说明文件路径或上传位置有误，对应调整即可。

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