Blazor .NET Core 8中Local Storage配置问题求助

针对你遇到的服务器端渲染无法访问浏览器 Local Storage 的问题，以下是经过验证的可行方案及排查要点：

核心原理说明 #

Blazor Server 即使关闭预渲染，组件初始化阶段仍在服务器端执行，此时无法直接访问浏览器存储。所有涉及 Local Storage 的操作必须等待客户端 JS 运行完成后执行，也就是在组件的 OnAfterRenderAsync 生命周期方法中处理。

方案一：正确使用 Blazored Local Storage #

1. 确保服务注册：在 Program.cs 中添加 Blazored Local Storage 服务：

   builder.Services.AddBlazoredLocalStorage();
   

2. 组件配置与代码实现：

   @inject ILocalStorageService LocalStorage
   @rendermode @(new InteractiveServerRenderMode(prerender: false))
   
   <h3>购物车内容</h3>
   @if (cartItems != null)
   {
       @foreach (var item in cartItems)
       {
           <p>@item.Name - 数量: @item.Quantity</p>
       }
   }
   
   @code {
       private CartItem[]? cartItems;
   
       // 必须在客户端渲染完成后访问 Local Storage
       protected override async Task OnAfterRenderAsync(bool firstRender)
       {
           if (firstRender)
           {
               // 读取已有购物车数据
               cartItems = await LocalStorage.GetItemAsync<CartItem[]>("cart") ?? [];
               StateHasChanged();
           }
       }
   
       public async Task AddToCart(CartItem item)
       {
           var currentCart = await LocalStorage.GetItemAsync<CartItem[]>("cart") ?? [];
           var updatedCart = currentCart.Append(item).ToArray();
           await LocalStorage.SetItemAsync("cart", updatedCart);
           cartItems = updatedCart;
           StateHasChanged();
       }
   
       public class CartItem
       {
           public string Name { get; set; } = string.Empty;
           public int Quantity { get; set; }
       }
   }
   

方案二：使用 ProtectedLocalStorage 加密存储 #

如果需要对存储数据加密，推荐使用框架自带的 ProtectedLocalStorage：

1. 服务注册：无需额外安装包，框架默认支持：

   builder.Services.AddScoped<IProtectedLocalStorage, ProtectedLocalStorage>();
   

2. 组件代码示例：

   @inject IProtectedLocalStorage ProtectedLocalStorage
   @rendermode @(new InteractiveServerRenderMode(prerender: false))
   
   @code {
       private CartItem[]? cartItems;
   
       protected override async Task OnAfterRenderAsync(bool firstRender)
       {
           if (firstRender)
           {
               var result = await ProtectedLocalStorage.GetAsync<CartItem[]>("protected-cart");
               if (result.Success)
               {
                   cartItems = result.Value;
                   StateHasChanged();
               }
           }
       }
   
       public async Task AddToCart(CartItem item)
       {
           var currentCart = await ProtectedLocalStorage.GetAsync<CartItem[]>("protected-cart");
           var updatedCart = currentCart.Success ? currentCart.Value.Append(item).ToArray() : [item];
           await ProtectedLocalStorage.SetAsync("protected-cart", updatedCart);
           cartItems = updatedCart;
           StateHasChanged();
       }
   }
   

方案三：服务器端状态同步 + Local Storage 持久化 #

如果需要跨页面共享购物车数据，建议结合服务器端状态管理：

1. 创建购物车服务：

   // CartService.cs
   public class CartService
   {
       private readonly ILocalStorageService _localStorage;
       private List<CartItem> _cartItems = [];
       public event Action? OnCartUpdated;
   
       public CartService(ILocalStorageService localStorage)
       {
           _localStorage = localStorage;
       }
   
       public async Task LoadCartFromStorage()
       {
           var savedCart = await _localStorage.GetItemAsync<List<CartItem>>("cart");
           if (savedCart != null)
           {
               _cartItems = savedCart;
           }
       }
   
       public async Task AddItem(CartItem item)
       {
           _cartItems.Add(item);
           await _localStorage.SetItemAsync("cart", _cartItems);
           OnCartUpdated?.Invoke();
       }
   
       public List<CartItem> GetCartItems() => _cartItems;
   }
   

2. 注册服务：

   // Program.cs
   builder.Services.AddScoped<CartService>();
   

3. 组件中使用：

   @inject CartService CartService
   @rendermode @(new InteractiveServerRenderMode(prerender: false))
   
   @code {
       protected override async Task OnAfterRenderAsync(bool firstRender)
       {
           if (firstRender)
           {
               await CartService.LoadCartFromStorage();
               CartService.OnCartUpdated += StateHasChanged;
               StateHasChanged();
           }
       }
   }
   

关键排查要点 #

• 所有访问 Local Storage 的代码必须放在 OnAfterRenderAsync 中，禁止在 OnInitializedAsync/OnParametersSetAsync 等服务器端生命周期方法中执行
• 确认组件的 rendermode 已正确设置为交互式模式且关闭预渲染
• 检查浏览器控制台是否有 JS 错误（如 Blazored Local Storage 脚本未加载）
• 确保 Program.cs 中已正确注册相关存储服务

内容的提问来源于stack exchange，提问作者Jair Vieira Junior