MudBlazor Blazor WASM页面刷新后主题颜色异常问题排查

问题场景 #

我使用MudBlazor构建Blazor WASM应用，在<MainLayout.razor>中配置了主题提供者：

<MudThemeProvider Theme="@_theme" IsDarkMode="@_isDarkMode" />

字段_theme初始化为null：

private MudTheme? _theme = null;

并在OnInitialized()中实例化自定义主题：

protected override void OnInitialized()
{
    base.OnInitialized();
    _theme = new()
    {
        PaletteLight = _lightPalette,
        PaletteDark = _darkPalette,
        LayoutProperties = new LayoutProperties()
    };
}

自定义明暗调色板定义如下：

private readonly PaletteLight _lightPalette = new()
{
    Black = "#110e2d",
    AppbarText = "#424242",
    AppbarBackground = "rgba(255,255,255,0.8)",
    DrawerBackground = "#ffffff",
    GrayLight = "#e8e8e8",
    GrayLighter = "#f9f9f9",
};

private readonly PaletteDark _darkPalette = new()
{
    Primary = "#7e6fff",
    Surface = "#1e1e2d",
    Background = "#1a1a27",
    BackgroundGray = "#151521",
    AppbarText = "#92929f",
    AppbarBackground = "rgba(26,26,39,0.8)",
    DrawerBackground = "#1a1a27",
    ActionDefault = "#74718e",
    ActionDisabled = "#9999994d",
    ActionDisabledBackground = "#605f6d4d",
    TextPrimary = "#b2b0bf",
    TextSecondary = "#92929f",
    TextDisabled = "#ffffff33",
    DrawerIcon = "#92929f",
    DrawerText = "#92929f",
    GrayLight = "#2a2833",
    GrayLighter = "#1e1e2d",
    Info = "#4a86ff",
    Success = "#3dcb6c",
    Warning = "#ffb545",
    Error = "#ff3f5f",
    LinesDefault = "#33323e",
    TableLines = "#33323e",
    Divider = "#292838",
    OverlayLight = "#1e1e2d80",
};

刷新页面后，深色模式下的颜色会异常变亮（接近默认深色主题），但明暗模式状态保持不变。此时打开汉堡菜单或切换明暗模式再切回，颜色会恢复为自定义的深色主题效果：

• 期望的深色主题效果：
  

• 刷新后的异常深色主题效果：
  

问题原因 #

核心问题在于组件初始化顺序导致的主题加载延迟：

1. Blazor组件首次渲染发生在OnInitialized()方法执行之前，此时_theme仍为null，MudThemeProvider会自动加载默认的MudBlazor主题。
2. OnInitialized()中实例化自定义主题后，虽然_theme的引用发生了变化，但MudThemeProvider并未自动触发主题的重新应用（组件未检测到需要刷新主题的信号）。
3. 当你打开汉堡菜单或切换明暗模式时，会触发MudThemeProvider内部的状态变更逻辑，强制重新计算并应用主题，此时自定义主题才会生效，颜色恢复正常。

解决方案 #

方案1：提前初始化主题（推荐） #

直接在字段声明时初始化_theme，避免延迟加载，确保首次渲染时就使用自定义主题：

// 移除null初始化，直接创建主题实例
private readonly MudTheme _theme = new()
{
    PaletteLight = _lightPalette,
    PaletteDark = _darkPalette,
    LayoutProperties = new LayoutProperties()
};

// 同时保留已定义的_lightPalette和_darkPalette
private readonly PaletteLight _lightPalette = new() { ... };
private readonly PaletteDark _darkPalette = new() { ... };

此方案无需额外生命周期方法调用，逻辑最简洁。

方案2：在OnInitialized中触发主题刷新 #

如果必须在OnInitialized()中初始化主题（比如需要异步加载配置），可以通过以下两种方式强制刷新主题：

方式A：调用StateHasChanged()通知组件更新

private MudTheme? _theme = null;

protected override void OnInitialized()
{
    base.OnInitialized();
    _theme = new()
    {
        PaletteLight = _lightPalette,
        PaletteDark = _darkPalette,
        LayoutProperties = new LayoutProperties()
    };
    // 通知组件重新渲染，触发MudThemeProvider应用新主题
    StateHasChanged();
}

方式B：调用MudThemeProvider的RefreshTheme()方法

先获取MudThemeProvider的引用，再调用其内置方法强制刷新主题：

<!-- 在MainLayout.razor中添加@ref获取组件实例 -->
<MudThemeProvider @ref="_themeProvider" Theme="@_theme" IsDarkMode="@_isDarkMode" />

private MudTheme? _theme = null;
private MudThemeProvider? _themeProvider;

protected override void OnInitialized()
{
    base.OnInitialized();
    _theme = new()
    {
        PaletteLight = _lightPalette,
        PaletteDark = _darkPalette,
        LayoutProperties = new LayoutProperties()
    };
    // 强制刷新主题
    _themeProvider?.RefreshTheme();
}

额外注意：持久化明暗模式状态 #

如果你的_isDarkMode状态未做持久化（比如存在本地存储），刷新页面后会重置为初始值，也可能导致主题显示异常。建议在组件初始化时从localStorage读取之前保存的模式状态：

protected override async Task OnInitializedAsync()
{
    base.OnInitialized();
    // 从本地存储读取明暗模式状态
    var darkModeStr = await JS.InvokeAsync<string>("localStorage.getItem", "darkMode");
    _isDarkMode = !string.IsNullOrEmpty(darkModeStr) && bool.Parse(darkModeStr);
    // 初始化主题
    _theme = new() { ... };
}

内容的提问来源于stack exchange，提问作者Val