GPT Academic 界面主题定制实战指南：从一键切换内置主题到创建自定义主题

本篇指南以 GPT Academic 的界面定制能力为核心，系统讲解从「界面外观」浮动工具栏一键切换主题、字体与布局，到通过 config.py 配置默认值，再到修改 CSS/JS 创建全新主题的完整定制路径。读完后，你可以为项目配置一套符合个人阅读习惯的外观：选定主题与字体、调整布局模式、启用明暗模式与 Live2D 形象，并具备直接参与主题源码开发的能力。

定制体系的三层结构

GPT Academic 的界面定制不是单点开关，而是分三层实现的，理解这一结构后，后文的每个功能点都能落到具体源码上：

1. 运行时交互层：页面左上角的浮动工具栏中「界面外观」标签页，负责主题、字体、字体大小、功能区显隐、明暗模式等实时切换，选择结果通过浏览器 Cookie 持久化。定义见 浮动工具栏。
2. 配置层：config.py / config_private.py 中的 THEME、FONT、LAYOUT、DARK_MODE 等参数决定服务启动时的默认外观。
3. 主题资源层：themes/ 目录下的 Python 主题定义文件与 CSS/JS 文件，承载颜色变量、附加样式与交互脚本。主题加载入口是 themes/theme.py 中的 load_dynamic_theme()。

启动时，main.py 先调用 adjust_theme() 得到 Gradio 主题对象，再将其与附加 CSS 一起传入 gr.Blocks(..., theme=set_theme, css=advanced_css)，整个界面即以此渲染。

快速切换主题

最简单的定制方式是界面直接切换：点击左上角浮动工具栏，进入「界面外观」标签页，在「更换UI主题」下拉菜单中选择目标主题。切换后效果立即生效、无需刷新，且系统会自动记住选择，下次访问保持相同主题。

从源码看，这一「免刷新切换」的原理是：main.py 中注册了 theme_dropdown.select 回调 on_theme_dropdown_changed，它在后端重新调用 load_dynamic_theme(theme) 生成对应主题的 CSS 字符串，写入隐藏的 secret_css 文本框，随后由前端 themes/theme.js 的 change_theme 函数动态替换页面 <style> 标签完成换肤。

内置主题

项目预置了三种风格迥异的主题，无需任何配置即可使用：

主题名称	风格特点	适用场景	主题定义文件
Default	橙色调，简洁明快	通用场景，默认推荐	themes/default.py
Chuanhu-Small-and-Beautiful	绿色调，清新舒适	长时间阅读	themes/green.py
High-Contrast	高对比度，黑白分明	视觉辅助需求	themes/contrast.py

从源码结构看，themes/theme.py 的 load_dynamic_theme() 按主题名做分支分发：名称为 Chuanhu-Small-and-Beautiful 时导入 green.py，为 High-Contrast 时导入 contrast.py，其余本地主题（含 Default）一律回落到 default.py；而名称中包含斜杠 / 的主题名会被识别为 HuggingFace 主题，转入下一节的动态下载逻辑。

Default 主题的实现可以参考 themes/default.py：它基于 gr.themes.Default 并将主色调 primary_hue 设为 orange，再通过 set_theme.set(...) 微调按钮渐变、阴影、输入框背景等数十个 Gradio 主题变量，最后叠加 default.css 与公共样式 common.css 作为附加 CSS。

HuggingFace 主题库

除了内置主题，还可以使用 Gradio 官方主题商店（Gradio theme gallery）中的任意主题，这些主题由社区贡献，风格从暗黑科技感到二次元风格均有覆盖。使用方式是在配置文件中设置带 用户名/主题名 格式的主题名称：

THEME = "Gstaff/Xkcd"        # XKCD 漫画风格
THEME = "NoCrypt/Miku"       # 初音未来主题
THEME = "gradio/seafoam"     # 海洋绿主题

这类主题在 themes/gradios.py 的 dynamic_set_theme() 中处理：函数调用 Gradio 的 ThemeClass().from_hub(THEME.lower()) 从 HuggingFace Hub 拉取主题定义并解析为本地 Gradio 主题对象。

网络要求：从 HuggingFace 下载主题需要访问外网。如果配置了代理，代码会在 ProxyNetworkActivate("Download_Gradio_Theme") 上下文中发起下载（见 gradios.py），即项目会自动通过代理拉取主题文件；首次加载可能需要几秒，异常时会在日志中输出「下载Gradio主题时出现异常」，而不会导致服务崩溃——dynamic_set_theme 捕获异常后返回已构造的空主题对象。

字体定制

文字是界面的核心元素，GPT Academic 支持「昵称(英文真名@CSS 链接)」的统一字体描述格式，系统字体与网络字体混排在一个下拉列表中。

界面切换字体

「界面外观」标签页的字体类型下拉菜单（gui_toolbar.py）由配置项 AVAIL_FONTS 驱动，config.py 中预置了完整的字体清单：

系统字体（需要本地系统已安装才能正常显示）：

• 宋体（SimSun）—— 标准印刷体，适合正式文档
• 黑体（SimHei）—— 无衬线体，现代简洁
• 楷体（KaiTi）—— 手写风格，温和亲切
• 仿宋（FangSong）—— 古典风格
• 华文系列 —— 华文细黑、华文楷体、华文仿宋、华文宋体、华文中宋、华文新魏、华文隶书等更精细的中文字体

网络字体（从 CDN 加载，无需本地安装）：

• 思源宋体（Source Han Serif CN VF）—— 开源高质量字体
• 月星楷（Moon Stars Kai HW）—— 手写楷体
• 珠圆体（MaokenZhuyuanTi）—— 圆润可爱
• 平方萌萌哒（PING FANG MENG MENG DA）—— 活泼风格

列表末尾还提供 Helvetica、ui-sans-serif、sans-serif、system-ui 等通用字体回退项。

切换字体后，前端会立即调用 themes/init.js 中的 gpt_academic_change_chatbot_font()，将新字体应用到对话区 #gpt-chatbot 元素；页面刷新时该函数也会被 init.js 读取 Cookie 后重新执行，从而恢复上次的字体选择。

调整字体大小

字体类型下方是字体大小滑块，默认值为 15（gui_toolbar.py 中定义为 5～25 的步进滑块，标签即「字体大小(默认15)」）。按屏幕尺寸与视力习惯，一般调整到 12（紧凑）到 20（宽松）之间即可获得较好体验。选择结果同样存入 Cookie，刷新页面自动恢复。

添加自定义字体

如果预设字体都不满足需求，可以在 config.py 或 config_private.py 的 AVAIL_FONTS 列表追加自定义网络字体，格式为：

字体昵称(字体英文名@字体CSS链接)

例如添加「霞鹜文楷」：

AVAIL_FONTS = [
    # ... 保留原有字体 ...
    "霞鹜文楷(LXGW WenKai@https://cdn.jsdelivr.net/npm/lxgw-wenkai-webfont@1.1.0/style.css)",
]

只要字体提供了标准的 CSS webfont 文件，即可通过这种方式引入，无需改动任何前端代码。

界面布局调整

GPT Academic 的界面由多个功能区组成，可以根据使用习惯显示或隐藏不同区域。

功能区显示控制

「界面外观」标签页中「显示/隐藏功能区」复选框组（gui_toolbar.py）共提供 5 个可选项，默认勾选「基础功能区」与「函数插件区」：

功能区	说明
基础功能区	包含学术润色、翻译等常用按钮
函数插件区	包含所有插件的下拉菜单
浮动输入区	在对话区域上方的快捷输入框
输入清除键	快速清空输入框的按钮
插件参数区	部分插件需要的额外参数输入

如果你主要使用插件功能而很少用基础按钮，可以隐藏「基础功能区」获得更简洁的界面。这一显隐逻辑由 themes/theme.py 内嵌的 js_code_show_or_hide 实现：JavaScript 按复选框值切换 #basic-panel、#plugin-panel、清除键按钮等 DOM 节点的 display 样式，并把「输入清除键」的状态写入 Cookie 以便刷新后保持。

其他界面元素

「显示/隐藏自定义菜单」复选框组（默认勾选「主标题」「副标题」「显示logo」）控制更多界面元素：

• 自定义菜单：用户自定义的快捷按钮区域
• 主标题 / 副标题：页面顶部的标题文字
• 显示 logo：GPT Academic 的品牌标识
• 添加 Live2D 形象：仅在配置 ADD_WAIFU = True 时出现在该复选框组中（见 gui_toolbar.py），用于在页面右下角显示可互动的虚拟形象

整体布局模式

通过修改配置文件中的 LAYOUT 参数切换整体布局模式，config.py 中的相关定义：

LAYOUT = "LEFT-RIGHT"   # 左右布局：输入区在左，对话区在右（默认）
LAYOUT = "TOP-DOWN"     # 上下布局：输入区在上，对话区在下

左右布局适合宽屏显示器，上下布局更适合窄屏或移动设备。配套的 CHATBOT_HEIGHT = 1115 控制对话窗高度，仅在 LAYOUT = "TOP-DOWN" 时生效（config.py 中的注释明确说明）。页面加载时，LAYOUT 与 DARK_MODE 等参数会一并注入前端初始化脚本（见 main.py 中的 GptAcademicJavaScriptInit("{DARK_MODE}","{INIT_SYS_PROMPT}","{ADD_WAIFU}","{LAYOUT}","{TTS_TYPE}")），完成布局与明暗的初始应用。

明暗模式

GPT Academic 支持明暗两种显示模式。在「界面外观」标签页点击「切换界面明暗 ☀」按钮即可在两种模式间切换。

该按钮绑定的是 themes/theme.py 中的 js_code_for_toggle_darkmode：脚本检测 <body> 上是否已有 .dark 类，没有则添加、有则移除，同时把结果写入名为 js_darkmode_cookie 的 Cookie（有效期 365 天），因此明暗偏好保存在浏览器中，下次访问自动应用。

也可以在配置文件中设置默认模式：

DARK_MODE = True   # 默认使用暗色模式（config.py 当前默认值）
DARK_MODE = False  # 默认使用亮色模式

Live2D 虚拟形象

Live2D 功能会在页面右下角显示一个可互动的动漫角色，增添趣味并根据操作给出不同反应。相关资源位于 themes/waifu_plugin/ 目录，包含 waifu.css、live2d.js、waifu-tips.js 等文件。

启用 Live2D

在配置文件中设置（config.py 当前默认值为 False，见 config.py）：

ADD_WAIFU = True

也可以在运行时通过「界面外观」标签页中的「添加 Live2D 形象」复选框控制——该选项只有在 ADD_WAIFU = True 时才会出现。

互动功能

Live2D 形象支持以下互动方式：

• 点击：形象会给出随机回应
• 拖拽：可以移动形象的位置
• 工具按钮：形象旁边的小图标提供更多功能，如切换角色、拍照等

配置文件定制

上述大部分定制都可以纯界面完成，但设置默认值或做更深入的定制需要修改配置文件。

核心配置项

与主题相关的核心配置项位于 config.py 或 config_private.py 中，config.py 的实际定义：

# 主题配置
THEME = "Default"                                    # 当前主题
AVAIL_THEMES = ["Default", "Chuanhu-Small-and-Beautiful", "High-Contrast",
                "Gstaff/Xkcd", "NoCrypt/Miku"]       # 可选主题列表

# 字体配置
FONT = "Theme-Default-Font"                          # 当前字体
AVAIL_FONTS = [...]                                  # 可选字体列表（见上文完整清单）

# 布局配置
LAYOUT = "LEFT-RIGHT"                                # 布局模式
CHATBOT_HEIGHT = 1115                                # 对话区高度（上下布局时生效）
DARK_MODE = True                                     # 默认明暗模式

# 其他界面选项
CODE_HIGHLIGHT = True                                # 代码高亮
ADD_WAIFU = True                                     # Live2D 形象
AUTO_OPEN_BROWSER = True                             # 启动时自动打开浏览器

补充两个界面行为细节：AUTO_OPEN_BROWSER 控制服务启动后是否在新线程中自动打开浏览器页面（main.py 中按该配置启动 open_browser 线程）；CODE_HIGHLIGHT 控制 Markdown 输出的代码高亮开关。

配置优先级

GPT Academic 的配置有三个来源，优先级从高到低依次为（config.py 头部注释明确定义）：

1. 环境变量 —— 适用于 Docker 部署，环境变量命名格式可参考 docker-compose.yml
2. config_private.py —— 推荐的个人配置方式
3. config.py —— 默认配置文件

建议把个性化配置写入 config_private.py（不存在则自行创建），这样做的好处是：更新项目时不会丢失个人配置，该文件也不会被 Git 追踪。

高级定制

如果你有前端开发经验，可以进行更深层次的界面定制。

修改 CSS 样式

每个主题都有对应的 CSS 文件，位于 themes/ 目录下：

• themes/default.css —— Default 主题样式
• themes/green.css —— Chuanhu-Small-and-Beautiful 主题样式
• themes/contrast.css —— High-Contrast 主题样式
• themes/common.css —— 所有主题共用的样式

可以直接修改这些文件调整颜色、间距、边框等视觉效果。从源码看，themes/default.py 在模块加载时读取 default.css 并拼接 common.css 作为 advanced_css，最终随 gr.Blocks(css=...) 注入页面，因此改动 CSS 后重启服务即可生效。若要修改主按钮颜色，可优先调整主题 adjust_theme() 中的 button_primary_background_fill 等变量，或在 CSS 中定位相应选择器覆盖。

创建自定义主题

想创建全新主题时，参考现有主题的结构。以 themes/default.py 为例，主题定义主要包含两部分：

1. adjust_theme() 函数：使用 Gradio 的 Theme API 定义颜色、字体等属性
2. advanced_css：随模块加载读取的附加 CSS 文件内容

创建新主题的步骤：

1. 复制一个现有主题文件（如 default.py 和 default.css）
2. 修改 adjust_theme() 函数中的颜色定义（primary_hue、neutral_hue、字体列表及各填充/阴影变量）
3. 调整 CSS 文件中的样式细节
4. 在 themes/theme.py 的 load_dynamic_theme() 中为新主题名增加一个 elif 分支，导入你的 adjust_theme 与 advanced_css
5. 将新主题名加入 config.py 的 AVAIL_THEMES 列表，使其出现在界面下拉菜单中

修改 JavaScript 行为

主题与界面行为相关的 JavaScript 代码位于：

• themes/init.js —— 初始化逻辑：页面加载时恢复字体、字号、明暗、布局、系统提示词等 Cookie 状态
• themes/theme.js —— 主题切换逻辑：change_theme() 将新主题 CSS 写入 localStorage（键为 theme-<主题名>）并替换样式标签，js_theme_selection_cookie 记录当前主题选择
• themes/common.js —— 通用功能

如果想修改动画效果、快捷键响应等交互行为，在这些文件中调整即可。注意切换主题后 CSS 会缓存于浏览器 localStorage，调试时可能需要清理缓存才能看到最新效果。

最佳实践

进行界面定制时，以下建议可以帮助你获得更好的体验：

• 选择护眼配色：长时间使用建议选择暗色模式或低对比度主题，减少眼睛疲劳。
• 保持界面简洁：隐藏不常用的功能区可以减少视觉干扰，提高工作效率；如果主要使用对话功能，可以只保留「函数插件区」。
• 备份自定义配置：如果进行了 CSS 或 JavaScript 修改，建议备份相关文件，项目更新时可能会覆盖这些文件。
• 测试不同设备：如果会在多种设备上使用，建议测试不同屏幕尺寸下的显示效果，LEFT-RIGHT 布局在小屏幕上可能不太适用。

相关文档

• 配置详解 —— 了解所有配置选项
• 自定义按钮 —— 添加个性化功能按钮
• 插件开发 —— 开发自定义插件