创建 Blazor Web…

在新建 ASP.NET Core Blazor 项目时，根据交互需求、部署环境和认证要求选择正确的渲染模式并执行对应的 dotnet new blazor 命令。

适用场景

解决思路

1. 在脚手架之前先收集需求：确认应用做什么（列出主要页面/功能）、需要何种交互性（显示数据与表单、实时更新、离线支持、富拖拽 UI）、部署环境（公网、内网、移动端慢连接）、是否需要认证（匿名、个人账户、组织账户如 Azure AD）。
2. 按复杂度递进选择渲染模式：Static SSR → SSR + Enhanced Nav → Interactive Server → Interactive WebAssembly，从满足需求的最简单级别开始，只有存在具体理由时才升级。
3. 若应用只需显示数据、简单表单和页面链接，使用 Static SSR（`-int None`）：无 JS 运行时、无 circuit、无 WebAssembly 下载，表单通过 HTML POST 工作，增强导航让体验流畅。
4. 若在上述基础上还需要少量客户端行为组件（实时搜索、实时更新、复杂表单向导），使用按页面的 Interactive Server（`-int Server`）：只有需要的组件通过 `@rendermode` 选择加入交互，其余保持静态，服务端执行、可完整访问 .NET、无需 API 层。
5. 若大多数页面需要丰富交互（仪表板、拖拽、聊天），使用全局 Interactive Server（`-int Server -ai`）：所有组件默认交互，UX 一致、心智模型简单，代价是每个用户在服务器上占用一个 SignalR circuit。
6. 若网络延迟是问题、用户在移动端/差网络，或应用必须离线工作，使用 Interactive WebAssembly（`-int WebAssembly`）：代码在浏览器运行，消除往返延迟，但需要 `.Client` 项目、用于数据访问的 API 层，且首次访问需下载 .NET 运行时；离线支持需在脚手架后添加 service worker 和 manifest 启用 PWA（模板默认不含）。
7. 若需要首次加载快（Server）且之后延迟低（WebAssembly），使用 Interactive Auto（`-int Auto`）：首次访问用 Server，后续访问用缓存的 WebAssembly 运行时；仅在 Server 和 WebAssembly 的约束同时适用时才选择。
8. Auto 模式约束：所有交互组件必须放在 `.Client` 项目；交互组件不能直接访问服务器（无 EF `DbContext`、文件系统、仅服务端服务），所有数据访问必须走 HTTP API；两个 `Program.cs` 必须注册匹配的服务；代码不能假设执行环境（无 `HttpContext` 访问，无 `RendererInfo` 保护的浏览器专用 API）；必须在两种模式下测试。
9. 避免的选型：不要因为「酷」而选 WebAssembly；不要在没有明确理由说明 Server 和 WebAssembly 单独都不够时选 Auto；不要为大多数页面是只读内容的应用选全局交互。
10. Static SSR 脚手架：`dotnet new blazor -o {AppName} -int None`。
11. 按页面 Interactive Server 脚手架（推荐默认）：`dotnet new blazor -o {AppName} -int Server`。
12. 全局 Interactive Server 脚手架：`dotnet new blazor -o {AppName} -int Server -ai`。
13. 按页面 Interactive WebAssembly 脚手架：`dotnet new blazor -o {AppName} -int WebAssembly`，会创建 `{AppName}`（服务端）和 `{AppName}.Client`（WebAssembly）两个项目。
14. 全局 Interactive WebAssembly 脚手架：`dotnet new blazor -o {AppName} -int WebAssembly -ai`。
15. 按页面 Interactive Auto 脚手架：`dotnet new blazor -o {AppName} -int Auto`。
16. 全局 Interactive Auto 脚手架：`dotnet new blazor -o {AppName} -int Auto -ai`。
17. 添加认证：在上述任意命令后追加 `-au Individual`，例如 `dotnet new blazor -o {AppName} -int Server -au Individual`；`-au Individual` 会脚手架 ASP.NET Core Identity（CLI 用 SQLite，Visual Studio 用 SQL Server），Identity 页面始终是静态 SSR，不使用交互渲染模式。
18. `blazor` 模板只支持 `-au Individual`；组织认证（Microsoft Entra ID、Azure AD B2C）需先用 `-au Individual` 脚手架，再用 `Microsoft.Identity.Web` / OIDC 中间件替换 Identity 提供程序，并在 `appsettings.json` 中配置租户。
19. 验证模板生成的 `Program.cs` 注册与所选模式匹配：Static SSR 用 `AddRazorComponents()` 和 `app.MapRazorComponents<App>()`；Server 用 `.AddInteractiveServerComponents()` 和 `.AddInteractiveServerRenderMode()`；WebAssembly 用 `.AddInteractiveWebAssemblyComponents()`、`.AddInteractiveWebAssemblyRenderMode()` 和 `.AddAdditionalAssemblies(typeof({AppName}.Client._Imports).Assembly)`，客户端 `Program.cs` 用 `AddAuthorizationCore()` 并注册 `HttpClient` 等客户端服务；Auto 同时注册 Server 和 WebAssembly 两者。
20. 脚手架后在项目根目录（`.csproj` 旁；两项目时放在服务端项目根）创建 `AGENTS.md`，根据所选模式从 `assets/agents-md/` 选择对应模板（`ssr-none.md`、`server-per-page.md`、`server-global.md`、`webassembly-per-page.md`、`webassembly-global.md`、`auto-per-page.md`、`auto-global.md`），复制内容并将所有 `{AppName}` 替换为实际项目名；若用了 `-au Individual`，添加 `## Authentication` 章节说明 Identity 已配置且 `Components/Account/` 下的页面始终是静态 SSR，不要加 `@rendermode`。
21. 脚手架并创建 AGENTS.md 后继续实现用户请求的功能：删除默认模板页（Counter、Weather），替换为实际应用页面。
22. 区分全局与按页面交互：按页面时 `App.razor` 中 `<Routes>` 和 `<HeadOutlet>` 不加 `@rendermode`，由各页面自行选择加入；全局时在 `<Routes @rendermode="InteractiveServer" />` 和 `<HeadOutlet @rendermode="InteractiveServer" />` 上设置（按需替换为 `InteractiveWebAssembly` 或 `InteractiveAuto`）。
23. 脚手架后验证：运行 `dotnet build` 确认构建通过，运行 `dotnet run`（两项目时在服务端项目）启动，然后在 `Components/Pages/`（服务端项目）或 `Pages/`（`.Client` 项目中的 WebAssembly 组件）创建第一个 `.razor` 页面。
24. 不要使用 `dotnet new blazorwasm`，它创建的是无服务端渲染的独立 WebAssembly SPA；应使用 `blazor` 模板加 `-int WebAssembly`。
25. 不要手动给 `-int None` 创建的项目添加 `AddInteractiveServerComponents()` 并期望其工作，还需要 `@rendermode` 指令并可能修改 `App.razor`；若模式需要根本性改变，应重新脚手架。
26. 不要把面向 WebAssembly 的组件放在服务端项目中，它们在预渲染时能工作，但交接后会失败。

适用边界 · 注意事项

• 不要用于给现有项目添加功能、改变现有应用的渲染方式或组件编写（组件编写应使用 author-component 技能）。
• 不要因为「酷」而选 WebAssembly，也不要为大多数页面是只读内容的应用选全局交互。
• 不要在没有明确理由说明 Server 和 WebAssembly 单独都不够时选 Auto 模式。