
Bad asset URLs causing UI to be unusable when delivered via non-standard port
快速结论:当 Gradio 通过非标准端口(如 20080)的反向代理提供页面时,CSS、JS 等资源 URL 拼接时丢失端口号,导致 UI 完全不可用。优先排查是否使用了 Gradio 6.17.x 版本,并检查 root 变量拼接逻辑。
问题场景
用户在 HTTPS 非标准端口反向代理环境中运行 Gradio(6.17.3),前端 UI 因资源加载失败而完全不可用。具体架构为:HTTPS + 非默认端口 → 反向代理 → Docker → Gradio。
报错原文
The URLs for:
- theme.css
- iframeResizer.contentWindow.min.js
- /gradio_api/upload_progress
- ... (maybe more?)
are concatenated with the `root` variable, instead of just being an absolute path (see /manifest.json).
Therefore the resulting URLs contain only the hostname without the port number, which causes the UI to fail if a non-standard port is used.
原因分析
Issue 中明确指出 Gradio 前端将资源 URL 与 root 变量进行拼接,而非使用绝对路径(如 /manifest.json)。当反向代理运行在非标准端口时,root 变量仅保留主机名(hostname)而丢失端口号,导致浏览器无法正确解析资源 URL。问题影响多个资源文件(theme.css、iframeResizer.contentWindow.min.js、upload_progress 等)。Issue 作者推测 root 变量原本用于设置基础路径(base path),但不适合用于拼接包含端口的主机地址。
环境排查
- Gradio 版本:6.17.x 及之前版本(6.20.x 中已修复,但作者测试时遇到其他异常)
- 部署方式:反向代理(如 Nginx) → Docker → Gradio
- 代理协议/端口:HTTPS + 非标准端口(如 20080)
- Gradio 前端模式:通常为 SPA(单页应用)
解决步骤
- 确认问题症状:在浏览器开发者工具中检查网络请求,确认
theme.css、iframeResizer.contentWindow.min.js等资源的请求 URL 是否缺少端口号(例如请求https://machine.local/theme.css而非https://machine.local:20080/theme.css)。 - 可优先尝试:从 Issue 评论区 PR 安装预发布版本(基于 commit a70d093),命令:
pip install https://huggingface.co/buckets/gradio/pypi-previews/resolve/a70d093e35660c0f19a904bea5bc958c0ee1e0e7/gradio-6.20.0-py3-none-any.whl。注意:原作者在升级时遇到了模块重复注册异常,需排查项目依赖兼容性。 - 替代方案:如果无法升级,可尝试在反向代理(如 Nginx)中显式设置
Host和X-Forwarded-Host头,确保 Gradio 能接收到完整的 host(含端口)信息。但这属于 workaround,不保证完全修复。 - 长期修复:参考 Issue 中建议的方法——在前端使用
<base href="..." />标签让浏览器自行处理资源解析,或直接使用绝对路径(如/manifest.json)替代root变量拼接。此修复已在 Gradio 后续版本中合并。
验证方法
通过反向代理访问 Gradio URL(例如 https://machine.local:20080),检查浏览器控制台无资源加载错误(404 或连接拒绝),且 UI 正常渲染。theme.css、iframeResizer.contentWindow.min.js 等资源应正确加载,不再包含 root 变量拼接导致的错误路径。

![[Bug]: Infinite loop vectorization of the same file](https://www.chat-gpts.plus/wp-content/uploads/2026/07/13327-db66c79b-768x403.jpg)
![[Feature Request]: Make BLOB_STORAGE_SIZE_THRESHOLD configurable via environment variable](https://www.chat-gpts.plus/wp-content/uploads/2026/07/16634-af62caa6-768x403.jpg)
