blazor全栈开发是按运行时边界分工的双模架构：server端负责状态权威、权限与事务，wasm端专注交互响应与离线体验；混用需统一序列化配置、显式处理js互操作及生命周期陷阱。
直接说结论：Blazor 全栈开发不是“用 C# 写前后端”这么简单，而是以共享类型系统和业务逻辑为前提，按运行时边界明确切分职责——Server 端管状态权威性、权限与事务，WASM 端管交互响应与离线体验；强行把所有逻辑塞进 WASM 或全扔给 Server，都会在 2026 年的真实项目中踩坑。
Blazor Server 和 WebAssembly 不是二选一，而是职责分工
很多人一上来就纠结“该用 Server 还是 WASM”，其实 2026 年主流架构是双模共存：dotnet new blazor --host wasm --server 生成的模板已默认支持。关键区别不在“谁快”，而在“谁该负责什么”：
- Blazor Server：适合高敏感操作（如支付确认、审计日志写入）、强实时协作（多人编辑同一文档）、低带宽弱终端（IoT 管理后台）——它靠 SignalR 维持长连接，
StatePersistenceMode.LocalStorage只缓存视图状态，不缓存业务数据 - Blazor WebAssembly：适合内容型应用（文档预览、仪表盘）、离线优先场景（现场巡检 App）、CDN 分发（静态资源哈希固化后可强缓存）、第三方嵌入（作为微前端子应用）——它的
Program.cs中AddCascadingStatePersistence配置的是客户端本地持久化，和服务端无关 - 混用时注意：共享记录类型（如
UserState）必须是public record，且字段名、序列化顺序、JsonSerializerOptions配置需两端完全一致，否则System.Text.Json反序列化会静默失败或字段为空
@rendermodeInteractiveAuto 不是万能开关，得看运行时环境
@rendermodeInteractiveAuto 看起来很智能，但它只做两件事：首屏走 SSR（服务端渲染），然后根据 UA 和网络条件决定是否升级为 WASM 或保持 Server 模式。它不会自动帮你处理以下问题：
- WASM 初始化失败时（比如用户禁用 JS 或内存不足），降级逻辑必须手动在
App.razor里用@onerror捕获并跳转到 Server 模式页面，否则白屏 - Server 模式下
IJSRuntime是空引用，调用InvokeAsync会抛InvalidOperationException: JavaScript interop calls cannot be issued—— 不能靠 try/catch 掩盖，得用@if (JS is not null)显式判断 - 自动模式下
NavigationManager的Uri在首次 SSR 渲染时是服务端视角的绝对路径（如https://app.example.com/dashboard），而 WASM 启动后变成浏览器视角的相对路径（/dashboard），路由参数解析要统一用NavigationManager.ToBaseRelativePath
[JSInvokable] 方法被调用时，参数反序列化规则很严格
JavaScript 调用 C# 方法看似方便，但 JSON → .NET 类型转换不是无损的。常见掉坑点：
- 日期字段默认按 ISO 8601 解析，但 JS
new Date().toISOString()带毫秒，.NETDateTimeOffset若没配JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter())，可能丢精度或抛异常 - 传布尔值
false到bool?参数，会变成null而非false；传字符串"false"则反序列化失败 —— 建议所有参数用string或JsonElement接收，再手动解析 - 异步方法标记
[JSInvokable]后，JavaScript 侧拿到的是Promise，但若 C# 方法内部 await 了未注册的 Service（比如没在Program.cs里AddSingleton<imyservice></imyservice>），运行时直接报InvalidOperationException: No service for type 'IMyService' has been registered，错误堆栈不显示 JS 调用链
CascadingParameter 跨层级传值，别忽略生命周期时机
用 CascadingValue + CascadingParameter 实现主题、语言、用户上下文透传很常见，但容易忽略初始化顺序：
-
CascadingValue的Value属性如果是异步加载的（比如从 API 获取用户配置），子组件的OnInitializedAsync里读到的仍是默认值 —— 必须监听ValueChanged事件或改用CascadingValue<t></t>的IsFixed = false模式 - 当父组件重渲染导致
CascadingValue重新设置Value，所有子组件的OnParametersSet会被触发，但ShouldRender默认返回true，可能引发不必要的重绘 —— 若值未真正变更，应在OnParametersSet里做浅比较并控制shouldRender返回值 -
CascadingParameter不支持泛型约束（如CascadingParameter<iusercontext></iusercontext>），只能声明为具体类型，否则编译报错CS0311: The type 'T' cannot be used as type parameter 'T' in the generic type or method
实际项目里最常被忽略的，是跨端序列化的隐式契约：WASM 和 Server 共享的 DTO 类型，哪怕只改一个字段的 JsonInclude 特性，或加一个 JsonIgnore，都可能导致某端解析失败且无提示。建议所有共享类型放在独立的 .Contracts 项目里，CI 流水线中强制跑 dotnet test 验证两端反序列化一致性。
