如何正确部署Kotlin Multiplatform WebAssembly项目并解决白屏问题？

问题描述 #

我使用JetBrains官方的Kotlin Multiplatform Wizard创建仅包含Web选项的KMP项目，本地执行./gradlew wasmJsBrowserDevelopmentRun时开发服务器可正常运行；但执行./gradlew wasmJsBrowserProductionWebpack生成生产包后，通过SFTP上传至strato.de服务器并设置主目录，访问index.html仅显示白屏，上传普通静态index.html却能正常显示。

操作流程 #

• 项目搭建：通过Kotlin Multiplatform Wizard仅选择Web选项创建项目
• 构建命令：
  • 本地开发：执行./gradlew wasmJsBrowserDevelopmentRun，运行正常
  • 生产构建：执行./gradlew wasmJsBrowserProductionWebpack生成生产包
• 构建后本地js目录结构：

  └── js
      ├── node_modules
      ├── package.json
      ├── packages
      ├── packages_imported
      └── yarn.lock
  

托管商要求：strato.de的Web空间需将域名指向包含启动文件（如index.html、index.php）的目录。

咨询问题 #

如何正确部署该项目到标准Web托管环境，实现与本地开发服务器一致的运行效果？

解决步骤 #

1. 定位正确的构建产物 #

执行生产构建后，可部署的静态文件并非根目录下的js文件夹，而是存放在项目的build/wasmJs/productionExecutable目录中，该目录包含index.html、编译后的WASM文件、依赖JS资源等完整可运行内容。

2. 上传正确的产物文件 #

将build/wasmJs/productionExecutable目录下的所有文件及子目录完整上传至strato.de的Web空间指定主目录，确保index.html处于该目录的根层级。

3. 修正资源路径配置 #

• 打开上传后的index.html，确认其中引用的.wasm、.js等资源路径为相对路径（例如./app.wasm），避免因绝对路径与服务器域名路径不匹配导致加载失败。
• 若服务器要求特定资源前缀，可在项目的webpack.config.d目录添加自定义配置文件，修改资源输出的公共路径：

  module.exports = {
    output: {
      publicPath: './'
    }
  };
  

  修改后重新执行生产构建再上传。

4. 排查浏览器控制台错误 #

访问域名时打开浏览器开发者工具（F12），查看「控制台」标签的错误信息：

• 若出现404错误，核对资源文件名、路径与服务器上的实际文件是否一致；
• 若出现WASM加载失败，确认服务器是否支持.wasm的MIME类型，若不支持可通过.htaccess添加配置：AddType application/wasm .wasm。

5. 检查文件权限 #

确保上传的所有文件权限设置为644，目录权限设置为755，避免因权限不足导致资源无法读取。

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