本地运行ZenML UI空白问题排查与解决

问题现象 #

本地运行ZenML后，UI地址http://127.0.0.1:8237显示空白页，仅部分加载，浏览器控制台报错：

Failed to load module script: Expected a JavaScript-or-Wasm module script but the server responded with a MIME type of "text/plain".

查看浏览器网络标签页，发现.js资源返回错误的内容类型：

content-type: text/plain; charset=utf-8

排查验证 #

通过以下命令确认问题：

• 检查服务器返回的响应头：

  curl -I http://127.0.0.1:8237/assets/<file>.js
  

• 检查Python的MIME类型检测逻辑：

  poetry run python -c "import mimetypes; print(mimetypes.guess_type('test.js'))"
  

  返回结果为：

  ('text/plain', None)
  

问题根源 #

该问题并非ZenML自身缺陷，而是Windows系统下的Python默认将.js文件映射为text/plain类型，导致ZenML依赖的Starlette框架以错误的MIME类型提供静态文件。由于浏览器对ES模块执行严格的MIME类型检查，因此UI无法正常渲染。

解决方案 #

在Poetry虚拟环境中创建sitecustomize.py文件，路径为：

<venv>/Lib/site-packages/sitecustomize.py

文件内容如下：

import mimetypes

mimetypes.add_type("application/javascript", ".js")
mimetypes.add_type("text/css", ".css")

创建完成后重启ZenML服务。

验证修复 #

执行以下命令验证MIME类型是否修复：

poetry run python -c "import mimetypes; print(mimetypes.guess_type('test.js'))"

此时应返回正确的类型：

('application/javascript', None)

再次检查服务器返回的响应头，.js资源的内容类型应为：

content-type: application/javascript

完成后ZenML UI即可正常加载。

内容的提问来源于stack exchange，提问作者Bader Eddine Benhirt