Blazor WebAssembly 项目启动失败主因是模板名、文件命名和事件参数类型不规范：模板名必须为严格小写的blazorwasm；Counter.razor文件名首字母必须大写；@onclick绑定函数参数类型须为MouseEventArgs等合法类型；仅在JS互操作等非UI线程更新状态时才需调用StateHasChanged()。
Blazor WebAssembly 项目跑不起来，八成卡在模板名、文件命名或事件参数类型上——不是环境问题，是约定没守牢。
dotnet new blazorwasm 命令必须严格写对
模板名 blazorwasm 是硬编码、区分大小写的字符串，拼错一个字母就失败：
-
dotnet new blazor→ 报错Invalid template name（该模板已弃用） -
dotnet new blazor-wasm或dotnet new blazorWasm→ 返回空列表，找不到模板 - 漏掉
-n参数 → 默认生成项目名WebApplication1，后续引用组件时类名易混淆（比如WebApplication1.Components.Counter而非预期的MyApp.Components.Counter）
正确命令示例：dotnet new blazorwasm -n WeatherApp。执行后进目录运行 dotnet run，看到 Now listening on: https://localhost:7055 才算真正启动成功。
Counter.razor 文件名大小写错了，页面就白屏
Blazor 不靠文件路径注册路由，而是靠 @page 指令 + 文件名首字母大写自动推导组件类名。小写文件名（如 counter.razor）会导致编译器无法生成有效类，现象是能访问路由但页面空白，控制台报错 Failed to find a valid digest in the index.html。
PigX UI 前端开发
下载
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
立即学习“前端免费学习笔记（深入）”；
- ✅ 正确：文件名
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() 不是状态变了就要手动调用
只有在非组件生命周期线程中修改了状态，才需要显式调用 StateHasChanged()：
- 比如从
Task.Run、Timer回调、或 JS 互操作（IJSRuntime.InvokeVoidAsync）里更新字段时，必须加StateHasChanged() - 但在
@onclick、OnInitialized、OnParametersSet等生命周期方法内直接改字段，Blazor 会自动刷新 UI，加了反而多余 - 如果用了
async/await，确保回调仍在同步上下文中（即未被调度到后台线程），否则仍需手动触发
最容易被忽略的是 JS 互操作后的状态更新——很多人以为 await 就安全了，其实 JS 回调默认不在 UI 上下文，不加 StateHasChanged() 就看不到变化。
