一、项目介绍
ASP.NET Core 是微软官方推出的开源、跨平台框架，用于构建现代化的、面向云端的互联网连接应用，典型场景包括 Web 应用、IoT 应用以及移动应用后端。它构建在 .NET 运行时之上，而 .NET 本身是一个免费、跨平台、开源的应用运行时。ASP.NET Core 在架构上专门为那些要部署到云端或本地机房的应用做了优化，由一组模块化组件拼装而成，整体开销极小，开发者在构造解决方案时可以按需取舍，保留充分的灵活性。
与旧版 ASP.NET（仅能运行在 Windows + IIS 之上）不同，ASP.NET Core 从第一天起就被设计为跨平台：你可以在 Windows、macOS 以及 Linux 上完成开发、调试与运行，同一套代码可以部署到 Windows Server、Linux 服务器、容器（Docker/Kubernetes）以及各类云平台。它统一了此前 ASP.NET MVC、Web API、Web Pages、Web API OWIN 等多个技术栈，合并为单一的 Web 开发栈，并内置了依赖注入、统一配置、结构化日志、Swagger/OpenAPI、健康检查、响应缓存、请求限流等一整套工业级能力。
框架的核心设计理念是"管道化"：每个 HTTP 请求经过由一组中间件（Middleware）组成的管线，依次完成路由、认证、异常处理、静态文件、端点执行等环节，开发者可以自由插入自定义中间件来横切关注点。它内置的跨平台 Web 服务器 Kestrel 性能优异，可直接对外服务；同时也支持在 IIS、Nginx、Apache、HTTP.sys 之后作为反向代理的后端运行。
项目由 .NET Foundation 社区治理，采用 MIT 许可证开源，源码托管在 dotnet/aspnetcore 仓库。日常开发节奏非常活跃：官方每周有 Community Standup 线上直播，发布路线图公开透明，并且持续提供每日构建（daily builds）供早期尝鲜与反馈。如果你想深入了解，可参考官方文档 Learn ASP.NET Core。
从生态位来看，ASP.NET Core 是 .NET 整个数据与 Web 链路的"门面"：它向下依赖 dotnet/runtime 提供的跨平台运行时与基类库，横向与 dotnet/efcore（数据访问）、dotnet/razor（Razor 编译工具链）、dotnet/roslyn（编译与分析）深度协作，向上承载 Web、云原生、实时通信等各类应用形态。无论是企业内部管理系统、高并发电商后端，还是基于 Blazor 的单页应用、基于 SignalR 的实时看板，都可以在同一套框架下完成。
二、项目结构
dotnet/aspnetcore 仓库体量庞大，是整个 .NET Web 开发栈的核心。从开发者视角看，源码主要按功能区域划分在 src/ 目录下：Hosting 相关目录承载通用主机（Generic Host）与 Web 主机的实现；Mvc 目录承载 ASP.NET Core MVC（控制器、Razor 视图、模型绑定、Razor Pages）；Routing 目录承载路由系统与端点路由；Http 目录承载 HTTP 抽象、请求/响应模型，以及与 Kestrel 的对接；Servers 目录下包含跨平台 Web 服务器 Kestrel 以及 IIS 集成（ASP.NET Core Module）。
此外，仓库还包含 SignalR（基于 WebSocket 的实时通信）、Identity（身份存储与Cookie认证）、Authentication（各类 OAuth2/OpenID Connect 提供程序）、Caching（内存与分布式缓存）、HealthChecks（健康检查）、StaticAssets（静态资产与压缩）、Middleware（诊断、代理转发、本地开发异常页等）、CORS（跨域）、Localization（全球化本地化）等模块。每个模块几乎都对应一个或多个 NuGet 包，按需引用。
test/ 目录存放海量单元测试、功能测试与集成测试，覆盖框架行为；docs/ 目录则收录了贡献指南、日常构建说明、从源码构建（BuildFromSource.md）、问题分诊流程（TriageProcess.md）等文档；eng/ 与仓库根目录的构建脚本负责仓库自身的工程化、版本生成与官方 CI。
对于普通使用者而言，你并不需要直接编译这个巨型仓库——日常使用时通过 Microsoft.AspNetCore.App 框架引用（FrameworkReference）引入的程序集，已经由官方预编译并随 .NET SDK / 共享框架（Shared Framework）分发。只有当你想为框架本身贡献代码、调试框架内部行为，或体验尚未发布的实验性特性时，才需要从源码构建。
三、版本与环境要求
运行与开发 ASP.NET Core 应用的前提是安装 .NET SDK。ASP.NET Core 的版本与 .NET 运行时版本一一对应：例如 .NET 8 对应 ASP.NET Core 8、.NET 9 对应 ASP.NET Core 9，仓库 main 分支当前面向最新的 .NET 线（README 中的每日构建表已指向 12.0 线）。安装 SDK 时会同时带上 .NET 运行时、ASP.NET Core 共享框架以及命令行工具 dotnet，这也是官方建议的安装方式——README 明确写道：如果你不确定自己需要什么，那就装 SDK，它除了 IIS 插件之外什么都包含了。
平台方面，官方每日构建表覆盖 Windows x64 / x86 / arm64、macOS x64 / arm64、Linux x64 / arm / arm64（含基于 musl 的 Alpine 变体）。Windows 上若要用 IIS 托管，还需单独安装 Hosting Bundle，它一次性包含 ASP.NET Core 共享框架、.NET 运行时以及 IIS 插件 ASP.NET Core Module；README 同时提供了各平台 Shared Framework 的 Installer 与 Binaries（压缩包）下载，方便在无管理员权限的机器上手工部署。
开发工具方面，推荐使用 Visual Studio（Windows，需勾选"ASP.NET 和 Web 开发"工作负载）、Visual Studio for Mac、或免费的 Visual Studio Code + C# Dev Kit。命令行下仅需 dotnet CLI 即可完成创建、还原、构建、运行与发布。需要注意的是，从源码构建框架本身对机器要求更高（需要匹配版本的 .NET SDK、Python、Node.js 以及足够的磁盘与内存），普通应用开发完全无需这些前置条件。
另外，.NET 采用"偶数位长期支持（LTS）+ 最新（STS）"的发布节奏，生产环境建议优先选择 LTS 版本以获得最长的补丁周期；若要尝鲜最新语言与框架特性，再选用 STS 版本。可通过 global.json 文件在仓库根目录锁定团队统一使用的 SDK 版本，避免"我这能跑"的版本漂移问题。
四、本地部署步骤
方式一：通过 .NET SDK 快速创建并运行（最常用）。首先从 dot.net 下载并安装对应版本的 .NET SDK，安装完成后在终端验证：
dotnet --info
dotnet --list-sdks随后创建一个 Web 项目并运行：
dotnet new webapp -o MyWebApp
cd MyWebApp
dotnet rundotnet run 会自动还原依赖、编译并启动 Kestrel 服务器，终端会输出类似 Now listening on: http://localhost:5000 的地址，浏览器打开该地址即可看到默认页面。除 webapp（Razor Pages）外，还可以使用 dotnet new mvc 创建传统 MVC 项目、dotnet new webapi 创建 Web API/最小 API 项目、dotnet new blazor 创建 Blazor 全栈 Web 项目。开发阶段若希望边改边热重载，可使用 dotnet watch run，保存文件后浏览器自动刷新。
方式二：发布为独立产物并在服务器运行。上线时使用发布命令把应用编译为可部署产物：
dotnet publish -c Release -o ./publishpublish 目录下会生成主 dll、运行时配置 json、各平台启动文件以及静态资源。在目标服务器上安装好 ASP.NET Core 运行时后，直接运行：
dotnet MyWebApp.dllASP.NET Core 默认使用内置的 Kestrel 作为 Web 服务器，可直接对外提供 HTTP 服务；生产环境通常在 Kestrel 前面再放一层反向代理（Linux 上用 Nginx，Windows 上用 IIS/HTTP.sys）以获得进程守护、TLS 终结与静态文件分流能力。若要让应用在 SSH 断开后持续运行，需配合 systemd（Linux）或 Windows 服务守护，例如创建 systemd unit 指定 WorkingDirectory、ExecStart=dotnet /path/MyWebApp.dll 并设置 Restart=always 与运行用户。
方式三：使用 Docker 容器。ASP.NET Core 官方提供了 mcr.microsoft.com/dotnet/aspnet 运行时镜像与 sdk 构建镜像。采用多阶段构建的 Dockerfile 示例：
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /app
FROM mcr.microsoft.com/dotnet/aspnet:10.0
WORKDIR /app
COPY --from=build /app .
EXPOSE 8080
ENTRYPOINT ["dotnet", "MyWebApp.dll"]构建并运行：docker build -t mywebapp . 与 docker run -p 8080:8080 mywebapp。容器内 ASP.NET Core 默认监听 8080，符合云原生约定。若要连接数据库或外部配置，建议通过环境变量（如 ConnectionStrings__Default、ASPNETCORE_ENVIRONMENT=Production）注入，而不是写死在 appsettings.json 中。
方式四：从源码构建框架本身（贡献者场景）。按 README 指引，先从 GitHub 仓库 clone 源码，再参考 docs/BuildFromSource.md 在仓库根目录运行构建脚本（Windows 上 build.cmd，类 Unix 上 ./build.sh）。普通使用者不建议走这条路，直接安装 SDK 即可获得官方预编译产物。构建完成后可以在自己的应用中将 Microsoft.AspNetCore.App 指向本地构建的二进制，从而调试框架内部行为或验证尚未发布的修复。
五、浏览器端部署
ASP.NET Core 本身是服务端框架，所谓浏览器端部署指的是把它运行起来后，通过浏览器访问其提供的页面与接口。本地开发时，dotnet run 或 dotnet watch 启动后，控制台会打印监听地址（默认 http://localhost:5000，或 5001 的 HTTPS 端口），直接在浏览器打开即可。若使用 Visual Studio，按 F5 会自动启动并打开默认浏览器，同时附加调试器；VS Code 配合 C# Dev Kit 也支持类似的 Launch 配置与断点调试。
生产环境下，浏览器访问的是反向代理对外暴露的域名与端口。Linux + Nginx 场景需要把 Nginx 配置为反向代理，把请求 proxy_pass 到 Kestrel 的监听端口（如 http://127.0.0.1:5000），并在 ASP.NET Core 侧通过 ForwardedHeaders 中间件正确识别代理传来的 X-Forwarded-For 与 X-Forwarded-Proto，否则 HTTPS 重定向会出现死循环、客户端 IP 也会显示为代理地址。Windows + IIS 场景安装好 Hosting Bundle 后，在 IIS 中新建网站指向发布目录，ASP.NET Core Module 会自动把请求转发给后台的 dotnet 进程，无需手动开放端口。
对于 Web API / 最小 API 项目，启动后可在浏览器访问 /swagger（需引入 Swashbuckle 或 .NET 内置 OpenAPI 包并在开发环境启用），在线查看并调试所有接口；Blazor 项目则在浏览器中直接渲染可交互的 UI 组件。无论哪种形态，应用监听地址与端口都可通过 launchSettings.json（开发期）或环境变量 ASPNETCORE_URLS（运行期、容器中）覆盖。
需要提醒的是，ASP.NET Core 不建议把 Kestrel 直接暴露到公网面向终端用户：Kestrel 定位是应用服务器，缺少完整的进程守护、TLS 证书自动管理、静态文件高性能分流与连接限流能力。在生产拓扑中，推荐"反向代理 + Kestrel"的组合，由反向代理（Nginx/IIS/YARP 等）终结 TLS、承担静态文件与基础安全策略，再把动态请求转发给本机的 Kestrel 进程。
六、API 用法
ASP.NET Core 的最小 API（Minimal API）让你几乎不用任何控制器类就能写出可对外调用的 HTTP 接口。典型的 Program.cs 如下：
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.MapGet("/hello", () => new { message = "Hello, ASP.NET Core!" });
app.MapGet("/products/{id}", (int id) => new { id, name = "Product " + id });
app.MapPost("/orders", (Order order) =>
Results.Created($"/orders/{order.Id}", order));
app.Run();
public record Order(int Id, string Item);启动后即可用 curl 调用：
curl http://localhost:5000/hello
curl http://localhost:5000/products/42
curl -X POST http://localhost:5000/orders \
-H "Content-Type: application/json" \
-d '{"id":1,"item":"book"}'在 MVC / Razor 场景下，控制器通过继承 ControllerBase 并标注 [HttpGet]、[HttpPost]、[Route] 等特性暴露接口；依赖注入通过 builder.Services.AddScoped<IRepo, Repo>() 注册，再以构造函数注入使用。框架内置的关键抽象包括：IConfiguration（统一配置，支持 json/环境变量/命令行/密钥管理）、ILogger<T>（结构化日志）、IHttpClientFactory（带生命周期与重试策略的 HTTP 客户端工厂）、IOptions<T>（强类型选项）、IMediator 风格的管道委托。完整 API 列表可查阅 官方文档。
七、常见问题 FAQ
问一：dotnet run 提示找不到 SDK 或指定的框架版本？
答：这通常是因为本机安装的 .NET 运行时/SDK 版本低于项目目标框架（例如项目面向 .NET 10 但机器只装了 .NET 8）。运行 dotnet --list-sdks 查看已装 SDK，再到 dot.net 安装匹配版本；服务器上若只装运行时，则需安装与项目 TargetFramework 对应的 ASP.NET Core Runtime。
问二：发布后在服务器上运行报"找不到 Microsoft.AspNetCore.App 共享框架"？
答：服务器只装了 .NET Runtime 而没装 ASP.NET Core 共享框架。请安装 ASP.NET Core Runtime 或 Hosting Bundle；若不想装框架，可改用自包含发布：dotnet publish -c Release -r linux-x64 --self-contained true，产物会把运行时一起带过去。
问三：IIS 下站点启动失败，返回 500.30 / 500.31 错误码？
答：500.30/500.31 表示 ASP.NET Core 应用启动异常或框架版本不匹配。先确认已安装 Hosting Bundle 且 IIS 的模块列表中存在 AspNetCoreModuleV2；再到服务器上用命令行直接运行 dotnet MyWebApp.dll 复现真实错误堆栈，通常是连接字符串、配置或迁移问题。
问四：Linux 服务器上 SSH 断开后应用就停了？
答：直接 dotnet xxx.dll 是前台进程，会话结束即被杀。请用 systemd 注册为系统服务，配置 WorkingDirectory、ExecStart=dotnet /path/xxx.dll、Restart=always 与运行用户，再执行 systemctl daemon-reload 与 systemctl enable --now 你的服务名。
问五：Nginx 反代后 HTTPS 重定向死循环，或客户端 IP 全部显示为 127.0.0.1？
答：缺少正向头转发配置。在 Program.cs 中调用 app.UseForwardedHeaders(...) 并限定 KnownProxies/KnownNetworks，同时在 Nginx 配置中传递 proxy_set_header X-Forwarded-For 与 X-Forwarded-Proto $scheme。
问六：如何查看应用实际监听了哪些地址、端口来自哪里？
答：可在启动日志中查看 Now listening on 一行；若被反向代理或 systemd 托管，可设置环境变量 ASPNETCORE_URLS=http://0.0.0.0:8080 显式指定。开发期则修改 Properties/launchSettings.json 中的 applicationUrl，dotnet run 会优先采用该文件中的 profile。
相关链接：官方仓库 · 官方文档 · 快速上手 · 从源码构建 · 下载 .NET SDK
说明：本文命令与版本均参照官方 README 与 .NET 官方文档整理，实际使用时请以仓库 main 分支最新说明为准。建议生产环境优先选择 LTS 版本以获得更长的补丁支持周期。