上周帮一个刚接触 .NET 后端开发的朋友看他的项目他花了两天时间用 ASP.NET Core Web API 搭了个简单的用户管理后台。功能是有了但代码结构让我有点头疼控制器里塞满了各种ActionResult视图模型和业务逻辑混在一起一个简单的表单提交要在控制器、模型、验证器几个文件里跳来跳去。他问我“有没有更简单、更聚焦一点的方式我就想快速做个带页面的管理后台不想一开始就搞这么重的分层。”这让我想起了 ASP.NET Core 里一个常被低估的选项Razor Pages。很多人对它的认知还停留在“是不是就是以前的 Web Forms”或者觉得它只适合做静态页。但如果你真正用它构建过一个中小型的内容管理、内部工具或快速原型你会发现对于“页面驱动”的 Web 应用它的开发体验直接得惊人——它把处理一个 HTTP 请求所需的所有东西路由、模型、处理逻辑和视图都放在了一个物理文件里。这不是倒退而是一种针对特定场景的范式简化。当你的应用是以“页面”为基本单位每个页面有明确的输入和输出时Razor Pages 通过PageModel将 MVC 模式中的 Controller 和 Model 合二为一让关注点从“控制器动作”回归到“页面生命周期”。今天我们就抛开那些大而全的框架对比深入聊聊如何用 ASP.NET Core Razor Pages 高效地构建网站特别是在 .NET 8/9 的语境下它有哪些新的可能性和你必须要避开的“坑”。1. 重新理解 Razor Pages不是简化版 MVC而是页面优先的架构在开始写第一行代码之前我们需要先扭转一个常见的误解。很多人把 Razor Pages 看作 ASP.NET Core MVC 的一个子集或简化版认为它只是省去了 Controller。这种理解是片面的也容易导致错误的使用方式。Razor Pages 的核心设计哲学是“页面为中心”Page-Centric。在传统的 MVC 模式中你思考的起点是控制器Controller和动作Action/User/Edit/1对应UserController下的Edit(int id)方法。你的代码组织天然围绕着控制器展开。而在 Razor Pages 中思考的起点是一个具体的页面/User/Edit直接对应文件系统中的一个物理文件Pages/User/Edit.cshtml和它的伴生模型文件Edit.cshtml.cs。请求的处理、业务逻辑和视图渲染都围绕着这个页面实体展开。这种转变带来的最直接好处是内聚性。一个用户编辑页面所有相关的代码页面呈现Edit.cshtml接收表单数据的模型EditModel中的[BindProperty]处理 GET 请求的OnGet方法处理 POST 请求的OnPost方法页面专用的验证逻辑和业务调用所有这些都位于同一个逻辑单元通常是两个紧邻的文件中。你不再需要在Controllers、Models、Views多个文件夹间来回切换来完成一个功能。对于功能明确、页面数量适中的后台管理系统、内容发布站点或内部工具这种内聚性能显著降低认知负担提高开发效率。那么它和 Web API 项目是什么关系很多人搜索“创建asp.net core web api项目”其实内心需求可能是“需要一个能返回数据的后端”。这里的关键区分在于交互模式Web API专注于提供结构化数据JSON/XML端点供前端应用如 SPA、移动App消费。它的核心是ControllerBase和ActionResultT。Razor Pages专注于生成完整的 HTML 页面处理表单提交并直接渲染结果。它的核心是PageModel和PageResult。如果你的应用主要是服务器端渲染 HTML有大量的表单交互那么从一开始就选择 Razor Pages会比用 Web API 配合某种前端框架更直接。当然两者并非互斥你完全可以在一个项目中同时使用 Razor Pages 和 Web API Controllers。2. 从零搭建环境、项目结构与第一个页面理论说再多不如动手建一个。我们以 .NET 8 为例.NET 9 预览版已出但 LTS 版本目前仍是 .NET 8生产环境建议使用稳定版。2.1 创建项目与初始结构打开终端执行以下命令dotnet new webapp -n MyRazorApp -o MyRazorApp cd MyRazorApp这个webapp模板就是为 Razor Pages 量身定制的。让我们看看生成的关键结构MyRazorApp/ ├── Pages/ │ ├── Index.cshtml │ ├── Index.cshtml.cs │ ├── Privacy.cshtml │ ├── Privacy.cshtml.cs │ └── Shared/ │ └── _Layout.cshtml ├── wwwroot/ ├── appsettings.json └── Program.csPages/目录这是 Razor Pages 的根目录也是默认的页面查找位置。它的子目录结构直接映射到 URL 路由。Pages/Index.cshtml与Index.cshtml.cs这是一对典型的 Razor Page 文件。.cshtml是视图模板包含 HTML 和 Razor 语法.cshtml.cs是它的页面模型类PageModel。Pages/Shared/存放布局、局部视图等共享组件。wwwroot/静态资源CSS, JS, 图片的家。Program.cs.NET 6 之后的主程序入口采用最小主机 API 配置。运行dotnet run访问https://localhost:5001你会看到一个基础的 Bootstrap 风格页面。这个页面就是由Pages/Index.cshtml渲染的。2.2 解剖一个 Razor PagePageModel是如何工作的打开Pages/Index.cshtml.cs你会看到类似以下代码public class IndexModel : PageModel { private readonly ILoggerIndexModel _logger; public IndexModel(ILoggerIndexModel logger) { _logger logger; } public void OnGet() { // 处理 GET 请求 } }这个IndexModel类继承自PageModel它是页面的“大脑”。OnGet()方法是一个处理器方法当以 HTTP GET 方式请求该页面时它会被自动调用。你可以在其中准备页面所需的数据。再看Pages/Index.cshtmlpage model IndexModel { ViewData[Title] Home page; } div classtext-center h1 classdisplay-4Welcome/h1 pLearn about a hrefhttps://learn.microsoft.com/aspnet/corebuilding Web apps with ASP.NET Core/a./p /divpage指令这是最关键的一行。它告诉框架这是一个 Razor Page而不是普通的 Razor 视图。它必须是文件的第一行指令。model IndexModel指定此视图关联的页面模型类型这样你就可以在视图中使用Model属性来访问页面模型中的公开成员。页面生命周期简析请求到达路由系统根据 URL 匹配到Pages/Index.cshtml。框架实例化IndexModel并执行依赖注入如ILogger。根据 HTTP 方法GET/POST/PUT/DELETE调用对应的处理器方法OnGet/OnPost/OnPut/OnDelete。也支持异步版本OnGetAsync。处理器方法执行完毕通常返回void默认渲染同名视图或IActionResult如RedirectToPage。框架渲染关联的.cshtml视图生成 HTML 响应。2.3 创建新页面约定大于配置添加一个新页面“关于我们”About。你不需要手动注册路由。在Pages文件夹下创建一个新的子文件夹About可选用于组织。在About文件夹中添加两个文件Index.cshtmlIndex.cshtml.cs此时这个页面的访问 URL 就是/About。因为Index.cshtml在 Razor Pages 中是一个默认文档类似于 Web 服务器中的index.html。如果你想创建一个路径为/About/Team的页面只需在Pages/About/下创建Team.cshtml和Team.cshtml.cs即可。这就是 Razor Pages 的“约定大于配置”文件系统的结构就是你的路由表。这极大地简化了路由管理对于大多数常规页面来说你根本不需要碰Startup.cs或Program.cs中的路由配置。3. 核心功能实践数据绑定、表单处理与验证Razor Pages 在处理表单交互上尤其优雅。我们通过一个“用户反馈”页面来演示。3.1 定义页面模型与数据绑定首先在Pages下创建Feedback文件夹并添加Index.cshtml.csusing System.ComponentModel.DataAnnotations; namespace MyRazorApp.Pages.Feedback { public class IndexModel : PageModel { // 使用 [BindProperty] 将表单数据绑定到模型属性 [BindProperty] public FeedbackInput Input { get; set; } new(); // 用于页面显示的消息 public string? SuccessMessage { get; set; } public void OnGet() { // 初始化或加载一些数据 } // 处理表单提交方法名对应 asp-page-handlerSubmit public async TaskIActionResult OnPostSubmitAsync() { if (!ModelState.IsValid) { // 验证失败重新显示表单当前页面 return Page(); } // 模拟保存到数据库等业务操作 // await _feedbackService.SaveAsync(Input); _logger.LogInformation(收到反馈{Email}, 内容{Message}, Input.Email, Input.Message); // 成功处理后重定向到 GET 请求避免表单重复提交Post-Redirect-Get 模式 // 同时传递一个成功消息 SuccessMessage 感谢您的反馈; return RedirectToPage(); } // 嵌套的输入模型类 public class FeedbackInput { [Required(ErrorMessage 请输入您的姓名)] [Display(Name 姓名)] public string Name { get; set; } string.Empty; [Required] [EmailAddress] [Display(Name 电子邮箱)] public string Email { get; set; } string.Empty; [Required] [StringLength(500, MinimumLength 10, ErrorMessage 反馈内容请在10到500字之间)] [Display(Name 反馈内容)] public string Message { get; set; } string.Empty; [Display(Name 订阅新闻)] public bool Subscribe { get; set; } } } }关键点解析[BindProperty]属性这是 Razor Pages 数据绑定的核心。它告诉模型绑定器在 POST 请求时将表单字段绑定到该属性。SupportsGet true参数可允许 GET 请求绑定但需谨慎使用。处理器方法命名OnPostSubmitAsync。OnPost表示处理 POST 请求Submit是处理器名称。在视图中可以通过asp-page-handlerSubmit来指定触发此方法。ModelState.IsValid自动执行基于数据注解如[Required],[EmailAddress]的验证。这是服务器端验证必不可少。Post-Redirect-Get (PRG) 模式在成功处理 POST 后使用RedirectToPage()重定向到一个 GET 请求。这能有效防止用户刷新页面时重复提交表单。3.2 构建强类型表单视图接下来创建Pages/Feedback/Index.cshtmlpage model MyRazorApp.Pages.Feedback.IndexModel { ViewData[Title] 用户反馈; } h1ViewData[Title]/h1 if (!string.IsNullOrEmpty(Model.SuccessMessage)) { div classalert alert-success rolealert Model.SuccessMessage /div } form methodpost asp-page-handlerSubmit div asp-validation-summaryModelOnly classtext-danger/div div classmb-3 label asp-forInput.Name classform-label/label input asp-forInput.Name classform-control / span asp-validation-forInput.Name classtext-danger/span /div div classmb-3 label asp-forInput.Email classform-label/label input asp-forInput.Email classform-control / span asp-validation-forInput.Email classtext-danger/span /div div classmb-3 label asp-forInput.Message classform-label/label textarea asp-forInput.Message classform-control rows5/textarea span asp-validation-forInput.Message classtext-danger/span /div div classmb-3 form-check input asp-forInput.Subscribe classform-check-input / label asp-forInput.Subscribe classform-check-label/label /div button typesubmit classbtn btn-primary提交反馈/button /form section Scripts { partial name_ValidationScriptsPartial / }关键点解析Tag Helpersasp-for,asp-validation-for,asp-validation-summary,asp-page-handler。这些是 Razor Pages 开发中提升生产力的利器。它们能生成正确的id、name属性并与模型绑定、客户端验证无缝集成。partial name_ValidationScriptsPartial /这个局部视图包含了 jQuery Unobtrusive Validation 脚本它基于数据注解为表单提供客户端验证。这能立即给用户反馈无需等到服务器往返。asp-page-handlerSubmit指定表单提交时调用页面模型中的OnPostSubmitAsync方法。如果省略handler则默认调用OnPostAsync或OnPost。现在运行应用访问/Feedback你会看到一个完整的、带客户端和服务器端验证的表单。提交后会触发 PRG 模式刷新页面并显示成功消息。3.3 关于“远程验证”的探讨搜索词中提到了“asp.net core 如何启用远程验证 remote”。远程验证Remote Validation是一种在用户输入时通过 AJAX 调用服务器端验证逻辑的技术例如检查用户名是否已存在。在 Razor Pages 中实现它与 MVC 中类似。首先在 PageModel 中创建一个用于远程验证的 Action// 在 IndexModel 类中添加 [AcceptVerbs(GET, POST)] public IActionResult VerifyEmail(string email) { // 模拟检查邮箱是否已被注册 if (email existingexample.com) { return Json($邮箱 {email} 已被使用。); } return Json(true); }然后在模型属性上使用[Remote]特性public class FeedbackInput { // ... 其他属性 ... [Required] [EmailAddress] [Remote(action: VerifyEmail, page: /Feedback/Index, HttpMethod GET)] [Display(Name 电子邮箱)] public string Email { get; set; } string.Empty; }注意远程验证能提升用户体验但它不能替代服务器端验证。客户端和远程验证都可以被绕过最终的、决定性的验证必须在服务器端的ModelState.IsValid或你的业务逻辑中完成。4. 进阶模式依赖注入、分层架构与 API 集成当项目规模增长将所有逻辑都放在PageModel中会变得臃肿。此时我们需要引入更清晰的分层。4.1 在 Razor Pages 中使用依赖注入ASP.NET Core 内置的依赖注入容器用起来非常方便。假设我们有一个IFeedbackService// Services/IFeedbackService.cs public interface IFeedbackService { Taskbool SaveFeedbackAsync(FeedbackInput input); } // Services/FeedbackService.cs public class FeedbackService : IFeedbackService { private readonly ILoggerFeedbackService _logger; public FeedbackService(ILoggerFeedbackService logger) _logger logger; public Taskbool SaveFeedbackAsync(FeedbackInput input) { _logger.LogInformation(保存反馈{Name}, {Email}, input.Name, input.Email); // 实际保存到数据库... return Task.FromResult(true); } }在Program.cs中注册服务builder.Services.AddScopedIFeedbackService, FeedbackService();然后在 PageModel 中通过构造函数注入public class IndexModel : PageModel { private readonly IFeedbackService _feedbackService; public IndexModel(IFeedbackService feedbackService) _feedbackService feedbackService; public async TaskIActionResult OnPostSubmitAsync() { if (!ModelState.IsValid) return Page(); var result await _feedbackService.SaveFeedbackAsync(Input); if (result) SuccessMessage 保存成功; return RedirectToPage(); } }4.2 保持 PageModel 的“瘦身”职责分离一个健康的 PageModel 应该主要承担以下职责协调请求调用合适的服务方法。管理页面状态准备视图数据ViewData,TempData。处理页面逻辑简单的条件判断、重定向。绑定与验证通过[BindProperty]和ModelState处理输入。而以下职责应该被剥离到服务层或领域层数据访问使用 Repository 或 EF Core DbContext复杂的业务规则计算外部 API 调用日志记录、审计等横切关注点一个简单的判断标准是如果你的OnGet或OnPost方法超过了 20 行或者开始出现嵌套的if-else和循环就该考虑将部分逻辑提取出去了。4.3 在 Razor Pages 项目中集成 Web API有时页面中的某个组件如动态加载评论需要调用 API。你可以在同一个项目中添加 API 控制器。在Program.cs中确保已包含AddControllerswebapp模板默认可能没有builder.Services.AddControllers(); // 添加对 API 控制器的支持然后添加一个 API 控制器// Controllers/Api/FeedbackApiController.cs using Microsoft.AspNetCore.Mvc; namespace MyRazorApp.Controllers.Api { [Route(api/[controller])] [ApiController] public class FeedbackApiController : ControllerBase { private readonly IFeedbackService _feedbackService; public FeedbackApiController(IFeedbackService feedbackService) _feedbackService feedbackService; [HttpGet] public IActionResult GetLatest([FromQuery] int count 10) { // 返回最新的反馈示例 var feedbacks new object[] { /* ... 从服务获取数据 ... */ }; return Ok(feedbacks); } } }在 Razor Page 的视图中你可以使用 JavaScript或 Blazor来调用这个 API。这样你就拥有了一个既能服务端渲染完整页面又能通过 API 提供数据端点的混合应用。5. 部署、配置与常见“坑点”排查5.1 环境与配置管理Razor Pages 应用使用标准的 ASP.NET Core 配置系统。appsettings.json和appsettings.{Environment}.json是管理配置的好地方。对于连接字符串等敏感信息务必使用 Secret Manager开发环境或环境变量/密钥管理服务生产环境。在 PageModel 或服务中通过IConfiguration接口注入来访问配置。public class IndexModel : PageModel { private readonly IConfiguration _config; public IndexModel(IConfiguration config) _config config; public void OnGet() { var apiKey _config[ExternalApi:Key]; // ... } }5.2 静态文件与客户端资源wwwroot目录所有静态文件CSS, JS, 图片都应放在这里。在视图中引用时路径以~/开头例如script src~/js/site.js/script。捆绑与压缩对于生产环境考虑使用Bundle and Minifier等工具或构建过程如 Webpack来优化客户端资源。LibMan库管理器Visual Studio 或 CLI 提供的 LibMan 是管理 Bootstrap、jQuery 等客户端库的轻量级方式。5.3 常见问题排查链路当你遇到 Razor Pages 相关问题时可以按以下顺序排查页面返回 404检查文件是否在Pages目录下且文件名和路径是否正确。确认.cshtml文件第一行是否有page指令。检查Program.cs中是否调用了app.MapRazorPages()模板项目默认已配置。表单提交后[BindProperty]属性为 null检查表单字段的name属性是否与模型属性名匹配Tag Helpers 会自动处理。确认模型属性是否有公共的setter。检查是否在OnPost方法中使用了[BindProperty]属性但提交的是 GET 请求需要SupportsGet true。复杂类型如集合绑定可能需要使用[BindProperty(Name ...)]指定前缀。验证消息不显示确保视图中的span asp-validation-for...或div asp-validation-summary...存在。检查是否在 POST 处理器中调用了ModelState.IsValid。确认_ValidationScriptsPartial已被引入用于客户端验证。依赖注入的服务为 null确认服务已在Program.cs中正确注册如AddScoped,AddSingleton。检查 PageModel 的构造函数参数类型是否正确。性能问题避免在 PageModel 的构造函数或OnGet中执行耗时同步操作使用异步方法。对于复杂视图考虑使用局部视图或视图组件来分解。启用响应压缩app.UseResponseCompression()。使用缓存策略[ResponseCache]特性或内存/分布式缓存。5.4 关于 .NET 9 的展望搜索词中提到了“asp.net core 9”。虽然本文基于 .NET 8但了解 .NET 9 的方向是有益的。根据发布路线图.NET 9 将继续提升性能、改进原生 AOT 支持并可能进一步增强 ASP.NET Core 的开发者体验。对于 Razor Pages 而言核心范式是稳定的但可以关注Blazor 与 Razor Pages 的融合在 Razor Pages 中更无缝地集成 Blazor 组件。新的性能优化更快的启动时间和更低的内存占用。工具链改进Hot Reload 体验的持续提升。对于新项目如果追求最新的功能和性能可以考虑从 .NET 9 预览版开始但要做好应对小版本变更的准备。对于需要长期稳定性的生产项目.NET 8 LTS 仍是更稳妥的选择。6. 何时选择 Razor Pages何时考虑其他方案经过上面的探讨我们可以为 Razor Pages 画一个更清晰的适用边界。选择 Razor Pages当你的项目是服务器端渲染SSR为主的网站如企业官网、博客、内容管理系统CMS、内部管理后台。功能以“页面”为自然边界每个页面有明确的输入、处理和输出。开发团队更熟悉服务器端技术栈希望快速产出功能无需深入前端框架。需要良好的 SEO因为初始 HTML 由服务器生成。项目规模中小型或者大型应用中可以清晰划分出的、相对独立的模块。考虑其他方案当你的需求是高度交互的单页面应用SPA如在线绘图工具、复杂的仪表盘。此时React、Vue、Angular 或 Blazor 可能是更好的选择。纯粹的数据 API 后端前端完全独立如移动 App 后端 API。使用 ASP.NET Core Web API 项目模板更纯粹。需要服务端与客户端实时双向通信考虑 SignalR。微服务架构中的某个纯 API 服务Web API 更符合其职责。一个务实的混合架构是使用 Razor Pages 构建主体网站框架、管理后台、SEO 关键页面。在需要复杂交互的特定页面中嵌入 Blazor 组件或通过 JavaScript 调用项目内集成的 Web API。这样既能享受 Razor Pages 的开发效率又能获得现代 Web 应用的交互体验。写在最后回归简单与专注技术选型没有银弹。Razor Pages 的价值在于它重新拥抱了 Web 开发的直观性——一个 URL 对应一个页面文件页面处理自己的请求和响应。它通过“约定大于配置”减少了决策点通过PageModel提高了内聚性通过 Tag Helpers 提升了开发体验。它可能不像前端框架那样“酷”但对于大量以信息展示和表单处理为核心的业务系统这种直接的、服务器端的方式往往能带来更快的交付速度、更少的上下文切换和更低的整体复杂度。下次当你需要快速构建一个功能明确的网站或后台时不妨给 Razor Pages 一个机会。从创建一个页面开始感受一下那种“所有相关代码都在手边”的流畅感。或许这就是你一直在寻找的那种“刚刚好”的简单。