ADK-Python项目Web UI启动黑屏问题解决方案

在Windows系统上使用ADK-Python项目时，开发者可能会遇到通过adk web命令启动Web界面后出现黑屏的问题。本文将深入分析该问题的成因，并提供完整的解决方案。

问题现象

当执行adk web命令后，访问http://127.0.0.1:8000/dev-ui页面时出现完全空白的情况。虽然控制台显示服务已正常启动，且adk run命令可以正常工作，但Web界面无法正常渲染。

根本原因分析

经过排查，该问题主要与Windows系统中的MIME类型注册表配置有关。具体表现为：

1. JavaScript文件(main-SLIAU2JL.js)被错误地识别为text/plain类型
2. Uvicorn服务器依赖Windows注册表中的MIME类型配置
3. 当注册表配置不正确时，浏览器无法正确解析JavaScript文件

解决方案

方法一：修复Windows注册表

1. 打开注册表编辑器(regedit)
2. 导航至HKEY_CLASSES_ROOT.js
3. 确保Content Type值为application/javascript
4. 如果没有.js项，则需要创建并设置正确的值

方法二：强制指定MIME类型

对于无法修改注册表的情况，可以在启动命令中添加MIME类型参数：

adk web --mime-types .js=application/javascript

方法三：使用开发服务器替代方案

如果上述方法无效，可以考虑使用其他开发服务器：

1. 安装备用服务器：

pip install hypercorn

2. 使用备用服务器启动：

hypercorn --bind 127.0.0.1:8000 your_app:app

验证解决方案

成功解决问题后，您应该能够：

1. 看到完整的Web界面而不再是黑屏
2. 浏览器开发者工具中不再出现MIME类型错误
3. 所有JavaScript文件都能正确加载和执行

预防措施

为避免类似问题再次发生，建议：

1. 定期检查系统注册表中的MIME类型配置
2. 在项目文档中明确系统要求
3. 考虑在代码中添加MIME类型检测和修复逻辑

通过以上解决方案，开发者应该能够顺利启动ADK-Python项目的Web界面，并继续后续的开发工作。