Aspire CLI

更新: 2026-10-16 15:20:09   字数: 0 字   时长: 0 分钟

aspire 是 Aspire 的命令行工具，负责创建、运行、观察、发布与部署应用。它默认是交互式的：不带参数运行时会引导您选择模板、资源等；加上 --non-interactive 或者提供完整参数后即可用于脚本与 CI。

全局选项

以下选项适用于 aspire 本身以及大部分子命令：

选项	说明
-h, /h	显示帮助与用法。
-v, --version	打印 Aspire CLI 版本号。
-l, --log-level <级别>	设置控制台最小日志级别：Critical、Debug、Error、Information、None、Trace、Warning。
--non-interactive	非交互模式，关闭所有交互式提示与动画，适合脚本与 CI。
--nologo	不显示启动横幅与遥测提示。
--banner	显示 Aspire CLI 的欢迎横幅。
--wait-for-debugger	在运行命令前等待调试器附加。
--apphost <路径>	显式指定要处理的 AppHost 项目文件。
-f, --follow	用于 aspire describe 等命令，持续输出变化。

--format Json

许多命令支持 --format Json 输出结构化结果，便于脚本解析与 AI 编码代理消费。

AppHost 的查找顺序

除了 aspire new、aspire init 这类创建型命令，其余命令都需要先确定要操作哪个 AppHost。CLI 按以下顺序查找：

1. --apphost 选项指定的路径。
2. 当前目录（或逐级向上查找）中的 aspire.config.json，它记录了上次选中的 AppHost。
3. 从当前目录向下搜索 AppHost 项目：只找到一个时自动选用；找到多个时列出让您选择。

首次选中后，结果会写入 aspire.config.json，后续命令直接复用。

命令速查

创建与初始化

命令	说明
aspire new [模板] [选项]	按模板创建新的 Aspire 项目或解决方案。
aspire init	在已有代码库中初始化 Aspire 支持（生成 C# 或 TypeScript AppHost）。
aspire add [<集成>]	为 AppHost 添加集成包。
aspire restore	还原依赖并为 AppHost 生成 SDK 代码。

运行与观察

命令	说明
aspire run	以开发模式前台运行 AppHost，构建并启动资源、打开仪表板。
aspire start	在后台启动 AppHost，达到稳定运行状态后返回。
aspire stop	优雅停止正在运行的 AppHost，按依赖顺序拆除资源。
aspire ps	列出正在运行的 AppHost。
aspire ls	列出当前目录下可作为 AppHost 的项目候选。
aspire describe	描述运行中 AppHost 的资源状态（旧名 aspire resources）。
aspire wait	等待某个资源达到目标状态。
aspire logs	显示运行中 AppHost 内资源的日志。
aspire resource	对某个资源执行命令。
aspire export	把遥测与资源数据导出为 zip 文件。

遥测检索

命令	说明
aspire otel	查看运行中 AppHost 的 OpenTelemetry 数据总入口。
aspire otel logs	查看结构化日志。
aspire otel traces	查看分布式追踪。
aspire otel spans	查看跨度（span）。

发布与部署

命令	说明
aspire publish	为 AppHost 生成部署产物（清单、Compose、Helm 等）。
aspire deploy	把应用部署到配置好的目标环境。
aspire do	执行指定的流水线步骤及其依赖。
aspire destroy	拆除此前部署的 Aspire 环境。

配置与维护

命令	说明
aspire update	更新项目中的 Aspire 包、模板与 SDK 版本。
aspire update --self	更新 Aspire CLI 自身。
aspire config	管理 CLI 配置（含特性开关）。子命令：get、set、list、delete。
aspire secret	管理 AppHost 用户机密。子命令：set、get、list、delete、path。
aspire certs	管理 HTTPS 开发证书。子命令：trust、clean。
aspire cache	管理 CLI 磁盘缓存。子命令：clear。
aspire doctor	诊断 Aspire 环境问题、校验安装是否正常。
aspire dashboard	管理 Aspire 仪表板。子命令：run。
aspire docs	在终端中浏览与检索 aspire.dev 文档。
aspire mcp	调用资源暴露的 MCP 工具。子命令：tools、call。
aspire terminal	管理资源的交互式终端会话。
aspire agent	管理 AI 编码代理环境配置。子命令：init、mcp。

命令状态

部分命令仍标记为 Preview（例如 aspire deploy、aspire publish、aspire otel、aspire dashboard、aspire do），接口可能在未来版本中调整。用于生产流水线前请留意版本变更。

典型工作流

本地开发

# 创建项目
aspire new aspire-starter -n AspireApp -o AspireApp
cd AspireApp

# 添加一个 PostgreSQL 集成
aspire add postgresql

# 前台运行（Ctrl+C 退出）
aspire run

后台运行 + 检索遥测

# 后台启动
aspire start

# 查看资源状态
aspire describe

# 查看日志
aspire logs

# 查看最近的追踪
aspire otel traces

# 等待某个资源就绪（脚本中常用）
aspire wait apiservice --status Healthy

# 停止
aspire stop

发布部署产物

aspire publish
aspire deploy

版本管理

# 查看版本
aspire --version

# 更新 CLI 自身
aspire update --self

# 更新项目中的 Aspire 包 / 模板 / SDK
aspire update

aspire update --self 的行为取决于安装方式：

• 使用 npm 安装时，它会打印 npm install -g @microsoft/aspire-cli@latest 让您执行，而不是直接替换二进制。
• 使用 Nix 安装时，它会打印对应的 Nix 更新命令，因为 Nix store 是只读的。

配置文件

aspire.config.json 会记录当前解决方案的 AppHost 路径、使用的集成包（TypeScript AppHost）等信息，通常应提交到版本库。更早版本使用 .aspire/settings.json，CLI 在迁移期间仍会读取。

下一步

• AppHost 应用主机
• 服务发现
• 遥测与 OpenTelemetry