Blazor是微软推出的Web前端框架，最大的特点是让你用C#和Razor语法来编写交互式Web UI，不再需要依赖JavaScript。对于习惯了.NET技术栈的开发者来说，这无疑是降低全栈开发门槛的好消息。不过许多刚接触的朋友在创建第一个Blazor项目时会遇到各种问题，比如SDK版本不匹配、模板找不到、托管模型不知道选哪个。这篇文章就从零开始，手把手完成Blazor项目的创建和首次运行。
一、创建项目前的环境准备
Blazor项目依赖.NET SDK，所以第一步是确认本机已经安装了合适版本的开发环境。打开命令行工具（Windows下可以用PowerShell或CMD），执行以下命令查看当前安装的SDK版本：
dotnet --version dotnet --list-sdks
第一个命令显示当前默认使用的SDK版本号，第二个命令列出所有已安装的SDK。建议使用.NET 6.0及以上版本，旧版本虽然也能创建Blazor项目，但已停止官方支持，遇到问题很难找到解决方案。如果没有安装，直接去微软官网下载最新版.NET SDK安装包，安装过程基本是下一步式的向导，非常简单。
除了SDK，开发工具方面推荐使用Visual Studio。注意社区版（Community）是免费的，功能足够个人学习和中小型项目使用。安装Visual Studio时记得在工作负载选择界面勾选“ASP.NET和Web开发”这一项，否则后面新建项目时看不到Blazor模板。如果你更偏爱轻量级编辑器，VS Code配合C#扩展也可以开发Blazor，但调试体验不如Visual Studio完善。
二、使用Visual Studio创建Blazor项目
打开Visual Studio，点击“创建新项目”，在搜索框里输入Blazor，你会看到几个不同的模板，常见的有Blazor Web App、Blazor Server和Blazor WebAssembly。以创建一个Blazor Server应用为例，选择模板后点击下一步，填写项目名称和解决方案名称，比如命名为MyFirstBlazor，存储路径建议放在没有中文和空格的目录下，避免某些工具链处理路径时出现奇怪的问题。
接下来是关键的一步：框架版本选择和托管模型配置。如果你用的是较新版本的Visual Studio，界面会提供交互模式选项，包括None、Server、WebAssembly和Auto。Server模式部署简单，对客户端要求低，适合快速上手；WebAssembly模式则把整个应用下载到浏览器端运行，离线能力更强但首次加载体积较大。初学者建议先选Server，跑通流程后再研究其他模式。
点击创建按钮后，Visual Studio会自动生成完整的项目骨架，包括Pages文件夹、Shared文件夹、wwwroot静态资源目录以及App.razor入口组件。直接按F5启动调试，浏览器会打开默认的欢迎页面，左侧导航栏可以切换Counter和Fetch data示例页面。如果页面正常显示并且Counter按钮点击有响应，说明项目创建成功。
三、使用命令行方式创建项目
不装Visual Studio也没关系，命令行同样可以完成全部工作。先确认可用的项目模板：
dotnet new list blazor
这个命令会列出所有和Blazor相关的模板。然后切换到你想存放项目的目录，执行创建命令：
dotnet new blazor -o MyFirstBlazor cd MyFirstBlazor dotnet run
其中-o参数指定输出目录，也就是项目文件夹名称。执行dotnet run后，控制台会输出监听地址，默认类似http://localhost:5000这样的形式，按住Ctrl键点击地址即可在浏览器中打开。想停止服务时按Ctrl+C即可。命令行方式的好处是跨平台，在Linux和macOS上操作完全一致，也方便后续集成到CI/CD流水线里。
如果只想创建纯WebAssembly项目，可以把模板换成blazorwasm：
dotnet new blazorwasm -o MyBlazorWasm
需要注意，blazorwasm模板在.NET 8之后被新的统一模板逐步替代，如果你的SDK版本较新，建议优先使用blazor模板并通过参数指定交互模式，例如-int WebAssembly，这样生成的项目结构更符合当前的推荐做法。
四、项目结构详解
项目创建完成后，花几分钟了解目录结构很有必要。打开解决方案资源管理器，主要文件和文件夹的含义如下：
- Pages文件夹：存放可路由的页面组件，每个文件对应一个URL路径，通过@page指令声明路由。
- Components或Shared文件夹：存放公共布局和可复用组件，比如MainLayout.razor定义了整体页面框架。
- App.razor：应用根组件，负责路由配置和渲染入口。
- Program.cs：应用启动文件，服务注册、中间件配置都在这里完成。
- wwwroot文件夹：存放css、js、图片等静态资源，站点根目录直接指向这里。
- appsettings.json：配置文件，数据库连接字符串等配置项写在这里。
以Counter页面为例，打开Pages/Counter.razor可以看到一段典型的组件代码：
@page "/counter"
<PageTitle>Counter</PageTitle>
<h1>Counter</h1>
<p role="status">当前计数: @currentCount</p>
<button class="btn btn-primary" @onclick="IncrementCount">点击加一</button>
@code {
private int currentCount = 0;
private void IncrementCount()
{
currentCount++;
}
}这段代码体现了Blazor的核心开发模式：HTML标记和C#代码写在同一个文件里，@code块中定义的成员可以直接在模板中通过@符号绑定。点击按钮时触发IncrementCount方法，页面会自动更新显示最新的计数值，整个过程没有一行JavaScript。理解了这个例子，就理解了Blazor组件开发的基本套路。
五、常见问题与注意事项
创建和首次运行阶段最容易碰到几类问题。第一类是模板缺失，执行dotnet new时提示找不到blazor模板，通常是SDK版本太旧导致的，升级SDK即可解决。第二类是端口占用，运行时报地址被占用的异常，可以在Properties/launchSettings.json中修改端口号，或者关掉占用该端口的进程。
第三类是Visual Studio中看不到Blazor模板，绝大多数情况是安装时漏掉了Web开发工作负载，打开Visual Studio Installer，点修改，补装ASP.NET和Web开发即可。第四类是浏览器控制台出现连接失败的错误，Blazor Server依赖WebSocket通信，如果部署在反向代理后面，需要额外配置WebSocket转发，本地开发一般不会遇到。
最后建议养成两个习惯：一是把项目放在纯英文路径下，避免构建工具解析中文路径出错；二是初次运行成功后用git初始化版本控制，记录每一次改动。跑通第一个项目只是起点，接下来可以尝试数据绑定、组件传参、调用API等进阶内容，逐步体会用C#写前端的独特优势。
Blazor创建项目Blazor教程Blazor项目搭建修改时间：2026-09-12 14:48:41