告别千篇一律：AdGuardHome Web界面主题与插件深度定制指南

2026-02-05 05:14:10作者：农烁颖Land

你是否厌倦了AdGuardHome默认界面的单调外观？是否希望根据个人喜好调整主题配色或扩展功能？本文将详细介绍如何定制AdGuardHome的Web界面主题，以及通过插件扩展其功能，让你的网络广告过滤体验更加个性化。

主题定制基础

AdGuardHome的Web界面主题系统基于client/src/helpers/constants.ts中定义的主题常量实现，目前支持三种主题模式：

export const THEMES = {
  auto: 'auto',
  dark: 'dark',
  light: 'light',
};

自动模式(auto): 根据系统设置自动切换深色/浅色主题
深色模式(dark): 深色背景配合浅色文字的高对比度主题
浅色模式(light): 浅色背景配合深色文字的传统主题

主题切换功能通过client/src/api/Api.ts中的API调用实现，核心代码如下：

const theme = data.theme ? data.theme : THEMES.auto;
const config = { data: { theme, language } };

手动切换主题

登录AdGuardHome管理界面
点击右上角用户头像，打开设置菜单
在"外观"或"界面设置"部分找到主题选项
选择偏好的主题模式并保存设置

主题设置会保存在浏览器本地存储中，通过client/src/helpers/localStorageHelper.ts进行管理：

export const STORAGE_KEYS = {
    THEME: 'account_theme',
    // 其他存储键...
};

自定义主题实现原理

AdGuardHome的主题切换通过修改CSS变量实现界面元素的样式变化。主题切换的状态管理由client/src/reducers/dashboard.ts负责：

case 'SET_THEME':
    return {
        ...state,
        theme: payload.theme,
    };

要实现自定义主题，需要修改以下几个关键部分：

主题样式定义: 在CSS文件中添加自定义主题的样式变量
主题切换逻辑: 修改client/src/api/Api.ts中的主题设置代码
UI控制元素: 添加自定义主题选择的界面控件

插件系统架构

AdGuardHome虽然没有官方正式的插件系统，但可以通过以下方式扩展功能：

自定义过滤规则: 通过FILTERS_URLS定义的URL路径管理自定义过滤规则
DNS重写规则: 使用MODAL_TYPE中的ADD_REWRITE和EDIT_REWRITE模态框添加自定义DNS重写规则
外部集成: 通过修改client/src/api/Api.ts中的API调用，实现与外部服务的集成

实用插件推荐

1. 自定义过滤规则插件

通过FILTERS_URLS.dns_blocklists路径添加自定义过滤规则列表，实现更精确的广告和跟踪器过滤。

2. DNS重写管理器

利用MODAL_TYPE.ADD_REWRITE和MODAL_TYPE.EDIT_REWRITE功能，实现自定义DNS重定向规则管理。

3. 统计数据导出工具

修改STATS_NAMES相关代码，添加数据导出功能，将DNS查询统计数据导出为CSV或JSON格式。

高级定制技巧

多主题自动切换

通过修改client/src/api/Api.ts中的主题设置逻辑，可以实现基于时间或系统事件的自动主题切换：

// 示例: 根据时间自动切换主题
const hour = new Date().getHours();
const theme = hour >= 18 || hour < 6 ? THEMES.dark : THEMES.light;
const config = { data: { theme, language } };

自定义主题配色方案

编辑CSS变量定义，创建个性化的主题配色：

/* 自定义主题变量示例 */
:root.theme-custom {
    --primary-color: #4a6fa5;
    --secondary-color: #8d7b6c;
    --background-color: #f1f1f1;
    --text-color: #333333;
    /* 其他变量... */
}