环境准备
更新: 2026-10-16 15:20:09 字数: 0 字 时长: 0 分钟
在开始使用 Aspire 之前，请先确认本机具备以下环境。Aspire 本身对系统要求不高，但它会启动容器、运行多进程并按端口转发流量，因此容器运行时和开发证书是最常见的两个「卡点」。
必备条件
| 组件 | 版本要求 | 说明 |
|---|---|---|
| .NET SDK | 9.0 或更高 | 使用 C# AppHost 与 .NET 服务时必备；建议使用最新的 LTS 版本。 |
| 容器运行时 | Docker Desktop / Podman / Rancher Desktop | 用于运行 PostgreSQL、Redis、RabbitMQ 等容器化资源。 |
| Aspire CLI | 最新稳定版 | 提供 aspire 命令，见 安装。 |
| 代码编辑器 | 见下方 | Visual Studio、VS Code 或 JetBrains Rider 均可。 |
使用 TypeScript AppHost？
TypeScript AppHost 需要 Node.js 20 或更高版本，且不强制要求安装 .NET SDK。如果您的服务本身是 .NET 应用，则 .NET SDK 仍然是必需的。
容器运行时
Aspire 在本地开发时会把数据库、缓存、消息中间件等「后备服务」作为容器启动。容器运行时不是强制的——如果您的应用只由 .NET 项目组成，也可以不安装——但绝大多数 Aspire 入门场景都会用到它。
- 推荐直接安装 Docker Desktop，Windows 上请启用 WSL 2 后端。
- 也可以使用 Podman 或 Rancher Desktop 等兼容容器运行时。
- 容器运行时未启动时，
aspire run会报出找不到容器运行时的错误，请先确认 Docker 已经处于运行状态。
代码编辑器
Visual Studio 2022 17.9 及以上版本，安装「ASP.NET 和 Web 开发」工作负载。
Aspire 的编排、仪表板与容器工具链已内置，直接 F5 即可调试整个应用。安装 C# Dev Kit 与 Aspire 扩展。
扩展可以从命令面板执行 Aspire: Install Aspire CLI (stable) 一键安装 CLI，
也可以通过 Aspire: Configure launch.json file 生成调试配置。Rider 2024.3 及以上版本内置 Aspire 支持，可以识别 AppHost 并一键启动编排。HTTPS 开发证书
Aspire 会为转发到您服务的端点启用 HTTPS。首次运行前请确保开发证书已被信任：
aspire certs trust如果浏览器提示证书不受信任，可以重新执行上面的命令；也可以使用 aspire certs clean 清理后重新生成：
aspire certs trustaspire certs clean验证环境
安装完成后，可以用 aspire doctor 检查开发环境中的常见问题（CLI 版本、证书状态、容器运行时等）：
aspire doctor也可以先确认 CLI 是否安装成功：
aspire --version常见问题
提示找不到 dotnet 或 SDK 版本过低
请安装 .NET SDK 9.0 或更高版本，并使用 dotnet --list-sdks 确认版本。注意运行时（Runtime）不等于 SDK，只安装运行时无法构建项目。
提示无法连接到容器运行时
确认 Docker Desktop（或 Podman）已经启动。Windows 下还需要确认 WSL 2 已安装并更新到最新版本，可以通过 wsl --update 更新。
浏览器提示「连接不是私密连接」
开发证书未被信任。执行 aspire certs trust 重新信任证书；若仍然失败，可执行 aspire certs clean 后再执行一次信任命令。
端口被占用
Aspire 默认使用随机端口代理资源，通常不会冲突。如果确实遇到端口占用，可以先执行 aspire ps 查看正在运行的 AppHost，再用 aspire stop 停止它。
