Blazor OnInitializedAsync 方法使用教程

来源：这里教程网时间：2026-02-21 17:32:57 作者：

Blazor 中的

OnInitializedAsync

是组件初始化阶段执行异步逻辑的核心入口，适合加载初始数据、检查用户权限、读取配置等操作。 它在组件首次渲染前调用，且只执行一次（服务端渲染 SSR 模式下需注意两次调用问题）。正确使用能避免“数据未加载就渲染”或“重复请求”等常见问题。

什么时候该用 OnInitializedAsync？

当你需要在组件显示前完成一项或多项异步任务时，比如：

从 API 获取页面主数据（如用户详情、订单列表） 读取本地存储（
localStorage
或
sessionStorage
）中的用户偏好 调用身份验证服务判断登录状态 初始化依赖服务（如 SignalR 连接、WebSocket）

注意：如果只是同步赋值（如设置默认字段），用

OnInitialized

更轻量；涉及

await

就必须选

OnInitializedAsync

。

基础写法与注意事项

在组件中重写该方法，返回

Task

，内部用

await

调用异步操作：

@code {
    private List<Product> products = new();
    private bool isLoading = true;
    protected override async Task OnInitializedAsync()
    {
        try
        {
            products = await ProductService.GetProductsAsync();
        }
        catch (Exception ex)
        {
            // 记录错误，可设 ErrorState 显示提示
            Console.WriteLine($"加载失败: {ex.Message}");
        }
        finally
        {
            isLoading = false;
        }
    }
}

关键点：

不要在方法内直接调用
StateHasChanged()
—— Blazor 会在方法结束后自动触发一次渲染 务必处理异常，否则会导致组件初始化失败且无提示 避免在其中做耗时过长的阻塞操作（如大文件解析），应考虑分页或懒加载

服务端渲染（SSR / Static Server Side Rendering）下的陷阱

在 .NET 8+ 启用 SSR 模式时，

OnInitializedAsync

可能在服务器端和浏览器端各执行一次：

服务器端执行：生成 HTML 快照，但此时无法访问浏览器 API（如
localStorage
、
NavigationManager
） 浏览器端再次执行：接管交互，此时才可安全使用前端能力

解决方案是加运行环境判断：

protected override async Task OnInitializedAsync()
{
    if (IsServerSide)
    {
        // 仅服务器端执行：查数据库、读配置等
        data = await ServerService.LoadDataAsync();
    }
    else
    {
        // 仅客户端执行：读 localStorage、发带凭据的 API 请求等
        preferences = await LocalStorage.GetItemAsync<UserPrefs>("prefs");
    }
}
@code {
    [CascadingParameter] private HttpContext? HttpContext { get; set; }
    private bool IsServerSide => HttpContext is not null;
}

替代方案对比：OnParametersSetAsync vs OnInitializedAsync

别混淆这两个生命周期方法：

OnInitializedAsync
：组件首次创建时调用，参数已注入但尚未变更，适合一次性初始化
OnParametersSetAsync
：每次父组件传入参数变化时都触发，适合响应参数更新（如路由参数
[Parameter] public string Id { get; set; }
改变后重新加载详情）

如果组件支持复用（如路由参数变化不重建组件），仅靠