feat: Add DEFAULT_THEME env var to configure default UI theme

该 Issue 是一个功能请求,并非报错。用户希望 Open WebUI 支持通过 DEFAULT_THEME 环境变量配置新用户首次访问时的默认主题(当前硬编码为 system ,跟随系统主题)。如果你正遇到类似“新用户首次访问总是浅色模式、无法通过服务端配置默认主题”的问题,优先检查部署环境中是

快速结论:该 Issue 是一个功能请求,并非报错。用户希望 Open WebUI 支持通过 DEFAULT_THEME 环境变量配置新用户首次访问时的默认主题(当前硬编码为 system,跟随系统主题)。如果你正遇到类似“新用户首次访问总是浅色模式、无法通过服务端配置默认主题”的问题,优先检查部署环境中是否已设置 DEFAULT_THEME 环境变量。

适用环境:Open WebUI(源码或 uvx 启动方式),涉及文件:backend/open_webui/config.pybackend/open_webui/main.pysrc/app.htmlsrc/routes/+layout.sveltesrc/lib/components/chat/Settings/General.svelte。Issue 提出者使用 Python 3.11 + uvx open-webui@latest 方式运行。

最快修复方案:暂无确认的一步修复方案。该 Issue 是功能请求,截至关闭时尚未确认是否已合入正式版本。

注意事项:Issue 中提到的 DEFAULT_THEME 环境变量属于提议方案,是否已在当前安装的 Open WebUI 版本中生效需要自行验证;旧版本大概率不支持。

问题场景

用户自托管 Open WebUI 服务,希望新用户或新浏览器会话首次访问时默认使用深色主题,而非当前的 system 主题(系统偏好为浅色时会显示浅色模式)。当前主题存储在客户端 localStorage.theme 中,回退值硬编码为 'system'(位于 src/app.html 约第 50 行),服务端无法覆盖该默认值。每次新用户或清除浏览器数据后,都需要手动在设置中切换主题。

报错原文

feat: Add DEFAULT_THEME env var to configure default UI theme

原因分析

可能原因:Open WebUI 的前端主题初始化逻辑中,localStorage.theme 未显式设置时,硬编码回退为 'system',服务端缺少可配置的默认主题入口。该功能请求希望新增 DEFAULT_THEME 环境变量(取值:systemdarklightoled-dark),并在后端 config.py 中定义、通过 /api/config 暴露给前端,最终替换 src/app.html 中的硬编码回退值。注意:此处属于功能缺失,并非程序运行时抛出的错误。

环境排查

  • 确认 Open WebUI 版本(open-webui --version 或查看 Docker 镜像 tag)。
  • 确认启动命令中是否已包含 DEFAULT_THEME 环境变量(若版本不支持则无效)。
  • 确认前端浏览器 localStorage 中是否已有 theme 键(已有值会覆盖默认主题)。
  • 若使用 Docker Compose,检查 environment 段落是否传入了 DEFAULT_THEME

解决步骤

  1. 检查当前 Open WebUI 版本是否已支持 DEFAULT_THEME 环境变量:查看官方文档或 Changelog,确认该功能是否已合并。
  2. 若版本已支持,在启动 Open WebUI 时设置环境变量,例如:
    DEFAULT_THEME=dark open-webui serve

    或者使用 uvx:

    DEFAULT_THEME=dark DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve --port 8088
  3. 若版本不支持,可考虑临时方案:在浏览器控制台手动执行 localStorage.theme = 'dark' 后刷新页面(注意:仅对当前浏览器生效)。
  4. 若你具备二次开发能力,可参考 Issue 中的提议方案自行实现:在 config.py 中定义 DEFAULT_THEME = os.getenv('DEFAULT_THEME', 'system'),将其注册到 DEFAULT_CONFIGui.default_theme,通过 /api/config 暴露,并在 main.pySPAStaticFiles.get_response() 中替换 HTML 占位符。
  5. 对已设置过主题的现有用户,该环境变量不会生效(他们仍保留自己在设置 UI 中选择的主题)。

验证方法

使用无痕窗口或清除浏览器站点数据后访问 Open WebUI,确认首次加载时主题是否为 DEFAULT_THEME 指定的模式(如 dark)。同时检查浏览器开发者工具中 localStorage.theme 是否为期望值,以及在 Network 面板中查看 /api/config 接口返回是否包含 ui.default_theme 字段。若主题已在首屏渲染时正确应用(无闪白),则说明配置生效。

参考来源

open-webui/open-webui #28642

GamsGo AI

AI 工具推荐

想把多个 AI 模型放在一个入口?

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。

这个方案解决了吗?

celebrityanime
celebrityanime
文章: 18825

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注