直接用dotnet new blazorwasm创建项目可快速启动，但需严格遵循模板名blazorwasm（区分大小写）、组件文件名首字母大写（如Counter.razor）、事件参数类型准确（如MouseEventArgs），否则将导致白屏、点击无响应或状态不更新等静默失败问题。
直接用 dotnet new blazorwasm 创建项目就能跑，但不注意模板名、文件命名规则和事件参数类型，5分钟内就会卡在路由白屏、点击无反应、状态不更新这些地方。
dotnet new blazorwasm 命令必须写全，不能简写或拼错
Blazor WebAssembly 项目模板名是固定且区分大小写的：blazorwasm。常见错误包括：
- 写成
blazor→ 报错Invalid template name，该模板已弃用 - 写成
blazor-wasm或blazorWasm→ 找不到模板，返回空列表 - 漏掉
-n参数 → 生成默认项目名WebApplication1，后续引用组件时容易混淆类名
正确命令示例：dotnet new blazorwasm -n MyWeatherApp。执行后进目录运行 dotnet run，看到 Now listening on: https://localhost:7055 即启动成功。
Counter.razor 文件名必须 PascalCase，否则组件不渲染
Blazor 不靠文件路径注册路由，而是通过 @page 指令 + 文件名首字母大写自动推导组件类名。小写文件名（如 counter.razor）会导致编译器无法生成有效类，现象是页面能访问但空白，控制台报错 Failed to find a valid digest in the index.html。
前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。
立即学习“前端免费学习笔记（深入）”；
- ✅ 正确：文件名
Counter.razor，内容含@page "/counter"→ 类名自动生成为Counter，<counter></counter>可正常使用 - ❌ 错误：文件名
counter.razor，哪怕@page路径写对，也无法实例化组件 - ⚠️ 别手动改
partial class Counter : ComponentBase——.razor编译器会覆盖它，改了也没用
@onclick 绑定函数参数类型错一个字母就静默失效
Blazor 的事件绑定不报编译错误，但参数类型不匹配时，方法根本不会被调用，也没有控制台提示，这是最常踩的坑。
- ✅
private void IncrementCount(MouseEventArgs e)→ 支持获取按键状态、坐标等 - ❌
private void IncrementCount(ClickEventArgs e)→ClickEventArgs类型不存在，方法永不触发 - ✅
private void IncrementCount()→ 可用，但拿不到事件上下文信息 - 其他常用类型：
KeyboardEventArgs（对应@onkeypress）、ChangeEventArgs（@onchange）、EventArgs（兜底通用）
StateHasChanged() 不是每次状态变更都要手动调用
只有在非组件生命周期线程中修改了状态（比如从 Task.Run、Timer 或 JS 互操作回调里更新字段），才需要显式调用 StateHasChanged()。正常 @onclick、OnInitializedAsync 等生命周期方法里赋值，框架会自动触发重渲染。
- ✅
private async Task LoadData() { items = await http.GetFromJsonAsync<List<Item>>("api/items"); }→ 不用加StateHasChanged() - ❌
Task.Run(() => { count++; StateHasChanged(); });→ 这种写法危险，跨线程调用 UI 方法可能崩溃；应改用InvokeAsync(StateHasChanged) - ⚠️ 在 JS 互操作回调里更新字段后，必须用
InvokeAsync(StateHasChanged)，不能直接调用
最容易被忽略的是：文件名大小写和事件参数类型的严格性 —— 它们不报错，但让整个组件“看起来在运行，实际没干活”。调试时先盯住这两点，比查网络请求或状态管理快得多。
