你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure 静态 Web 应用 CLI 参考

2025-07-28

Azure 静态 Web 应用 CLI 命令的参考。

Commands

Command	Description	类型	Status
swa login	登录到 Azure。	SWA Core	GA
swa init	配置新的 Azure Static Web Apps 项目。	SWA Core	GA
swa build	生成应用程序。如果有 Node.js 应用程序，则首先安装依赖项。	SWA Core	GA
swa start	从目录启动 Azure Static Web Apps 模拟器或绑定到正在运行的开发服务器。	SWA Core	GA
swa deploy	将当前项目部署到 Azure Static Web Apps。	SWA Core	GA
swa db	生成和编辑 Static Web Apps 数据库连接配置。	SWA Core	GA

Global Parameters

Parameter	Summary
--version, -v	显示版本号。
--verbose、--V [level]	启用详细输出。级别值包括 `silly`、 `info`（ `log` 默认值）和 `silent`。
--config，-c [path]	swa-cli.config.json 文件的路径。
--config-name, -cn	CLI 使用的配置。
--print-config, -g	打印所有已解析的选项。默认值为 `false`。
--help, -h	显示上下文相关的帮助。

登录到 Azure。

使用 Azure 进行身份验证，以便使用 swa deploy 命令获取 Azure Static Web Apps 的部署令牌。

Syntax

swa login
          [--subscription-id]
          [--resource-group]
          [--tenant-id]
          [--client-id]
          [--client-secret]
          [--app-name]
          [--clear-credentials]
          [--use-keychain]
          [--no-use-keychain]

Examples

示例 1：交互式登录到 Azure

swa login

Parameters

--subscription-id, -S

此项目使用的 Azure 订阅 ID。默认值为 process.env.AZURE_SUBSCRIPTION_ID。

--resource-group, -R

资源组的名称。可以使用 az configure --defaults group=<name>配置默认组。

--tenant-id, -T

Azure 租户 ID。默认值为 process.env.AZURE_TENANT_ID。

--client-id, -C

Azure 客户端 ID。

--client-secret, -CS

Azure 客户端密码。

--app-name, -n

Azure Static Web Apps 应用名称。

--clear-credentials -cc

在登录之前清除持久保存的凭据。默认值为 false。

--use-keychain, -u

将操作系统本机密钥链用于持久性凭据。默认值为 true。

--no-use-keychain, -nu

禁用操作系统本机密钥链的使用。

Global Parameters

swa init

配置新的 Azure Static Web Apps 项目。

使用 Static Web Apps CLI 配置新的 Azure Static Web Apps 项目。交互模式会提示输入配置名称、检测项目设置和使用的框架。完成后，将创建新的静态 Web 应用，并在 swa-cli.config.json 当前目录中生成文件。

可以多次运行 swa init，为项目创建不同的配置。如果正在处理 monorepo 并想要配置不同的项目，则可能需要执行此操作。

生成的配置文件用于使用 Static Web Apps CLI 运行的每个命令。如果有多个命名配置，可以使用位置参数或 --config-name 选项来指定要使用的配置。

下面是由 init 命令生成的示例配置：

{
  "$schema": "https://aka.ms/azure/static-web-apps-cli/schema",
  "configurations": {
    "myApp": {
      "appLocation": ".",
      "apiLocation": "api",
      "outputLocation": "dist",
      "appBuildCommand": "npm run build",
      "apiBuildCommand": "npm run build --if-present",
      "run": "npm run dev",
      "appDevserverUrl": "http://localhost:8080"
    }
  }
}

Syntax

swa init
          [--yes]

Examples

示例 1：以交互方式创建新配置。

swa init

示例 2：使用所有选项的默认值创建新配置。

swa init --yes

示例 3：使用 swa-cli.config.json 文件中名为“myApp”的配置初始化项目。

swa init --config-name myApp

Parameters

--yes, -y

对所有禁用交互模式的提示回答“是”。默认值为 false。

Global Parameters

swa build

生成应用程序。如果有 Node.js 应用程序，则首先安装依赖项。

常见用例包括：为前端应用和 API 安装依赖项，并为这两者运行生成命令，仅当前端或 API 项目没有生成步骤时，才能生成。

Syntax

swa build
          [--app-location]
          [--api-location]
          [--output-location]
          [--app-build-command]
          [--api-build-command]
          [--auto]

Examples

示例 1：生成应用，并选择性地安装依赖项。

swa build

示例 2：检测如何在安装依赖项后生成应用并运行生成命令。

swa build --auto

示例 3：安装前端应用程序的依赖项。

swa build --app-location ./client

示例 4：使用 swa-cli.config.json 中指定的`myApp`配置生成前端应用程序。

swa build myApp

Parameters

--app-location, -a

包含前端应用程序的源代码的文件夹。默认值为 .。

--api-location, -i

包含 API 应用程序的源代码的文件夹。

--output-location, -O

包含前端应用程序的生成源的文件夹。此路径是相对于 --app-location 的路径。默认值为 .。

--app-build-command, -A

生成前端应用程序。

--api-build-command, -I

生成 API 应用程序。

--auto

自动检测如何生成前端和 API 应用程序。默认值为 false。

Global Parameters

swa start

从目录启动 Azure Static Web Apps 模拟器或绑定到正在运行的开发服务器。

从文件夹提供服务

默认情况下，CLI 启动并提供当前工作目录 ./ 中的任何静态内容：

swa start

如果静态应用的项目文件夹位于其他文件夹（例如，./my-dist），请运行 CLI 并提供该文件夹：

swa start ./my-dist

从开发服务器提供服务

在本地开发前端应用时，使用前端框架 CLI 附带的开发服务器通常很有用。使用框架 CLI 让你可以使用内置功能，如“livereload”和 HMR（热模块更换）。

若要将 SWA CLI 用于本地开发服务器，请执行以下两个步骤：

照常启动本地开发服务器。例如，如果使用 Angular：ng serve（或 npm start）。
在单独的终端中，使用开发服务器提供的 URI 运行 swa start，格式如下：

swa start http://<APP_DEV_SERVER_HOST>:<APP_DEV_SERVER_PORT>

下面是一些常用开发服务器使用的默认端口和命令的列表：

Tool	Port	Command
Angular	`4200`	`swa start http://localhost:4200`
Blazor WebAssembly	`5000`	`swa start http://localhost:5000`
Gatsby	`8000`	`swa start http://localhost:8000`
Hugo	`1313`	`swa start http://localhost:1313`
Next.js	`3000`	`swa start http://localhost:3000`
React （创建 React 应用）	`3000`	`swa start http://localhost:3000`
Svelte (sirv-cli)	`5000`	`swa start http://localhost:5000`
Vue	`3000`	`swa start http://localhost:3000`

可以向 CLI 提供启动命令，而不是单独启动开发服务器。

# npm start script (React)
swa start http://localhost:3000 --run "npm start"

# dotnet watch (Blazor)
swa start http://localhost:5000 --run "dotnet watch run"

# Jekyll
swa start http://localhost:4000 --run "jekyll serve"

# custom script
swa start http://localhost:4200 --run "./startup.sh"

然后使用模拟服务从 http://localhost:4280 访问应用程序

为前端应用和 API 提供服务

如果项目包含 API 函数，CLI 将检查 Azure Functions Core Tools 是否已安装并可用。否则，CLI 会下载并安装正确的 Azure Functions Core Tools 版本。

自动启动 API 服务器

运行 CLI 并提供包含 API 后端的文件夹（有效的 Azure Functions 应用项目）：

# static content plus an API
swa start ./my-dist --api-location ./api

# front-end dev server plus an API
swa start http://localhost:3000 --api-location ./api

手动启动 API 服务器

在本地开发后端时，有时单独运行 Azure Functions Core Tools 来为 API 提供服务会很有用。这样就可以使用内置功能，例如调试和丰富的编辑器支持。

若要将 CLI 与本地 API 后端开发服务器配合使用，请执行以下两个步骤：

使用 Azure Functions Core Tools 启动 API：func host start 或在 VS Code 中开始调试。
在单独的终端中，使用以下格式运行具有 --api-location 标志和本地 API 服务器的 URI 的 SWA CLI：

swa start ./my-dist --api-location http://localhost:7071

Database connections

若要使用数据库连接启动应用程序，请使用 --data-api-location 参数并指向包含 staticwebapp.database.config.json 文件的文件夹。

swa start ./src --data-api-location swa-db-connections

Syntax

swa start

Examples

示例 1：使用默认值启动应用程序。

swa start

示例 2：使用前端开发服务器启动应用程序。

swa start http://<APP_DEV_SERVER_HOST>:<APP_DEV_SERVER_PORT>

示例 3：使用前端和后端开发服务器启动应用程序。

swa start http://<APP_DEV_SERVER_HOST>:<APP_DEV_SERVER_PORT> --api-location http://localhost:7071

Parameters

--app-location, -a <PATH>

包含前端应用程序的源代码的文件夹。默认值为 .。

--api-location, -i <PATH>

包含 API 应用程序的源代码的文件夹。

--output-location, -O <PATH>

包含前端应用程序的生成源的文件夹。此路径是相对于 --app-location 的路径。默认值为 .。

--data-api-location

包含 staticwebapp.database.config.json 文件的文件夹。

--app-devserver-url, -D <URL>

通过此 URL 连接到应用开发服务器，而不是使用输出位置。

--api-devserver-url, -is <URL>

通过此 URL 连接到 API 服务器，而不是使用输出位置。

--api-port, -j <API_PORT>

传递给 func start 的 API 服务器端口。默认值为 7071。

--host, -q <HOST>

用于 CLI 开发服务器的主机地址。默认值为 localhost。

--port, -p <PORT>

用于 CLI 开发服务器的端口值。默认 4280。

--ssl, -s

通过 HTTPS 提供前端应用程序和 API。默认值为 false。

--ssl-cert, -e <SSL_CERT_LOCATION>

启用 HTTPS 时使用的 SSL 证书 (.crt)。

--ssl-key, -k <SSL_KEY_LOCATION>

启用 HTTPS 时使用的 SSL 密钥 (.key)。

--run, -r <STARTUP_SCRIPT>

在启动时运行的自定义 shell 命令或脚本文件的位置。

--devserver-timeout, -t <TIME>

连接到前端应用程序的开发服务器或 API 服务器时等待的时间（以秒为单位）。默认值为 60。

--swa-config-location, -w <SWA_CONFIG_FILE_LOCATION>

staticwebapp.config.json 文件的目录位置。

--open, -o

打开浏览器到开发服务器。默认值为 false。

--func-args, -f <FUNCTION_ARGUMENTS>

传递到 func start 命令的其他参数。

Global Parameters

swa deploy

将当前项目部署到 Azure Static Web Apps。

常见用例包括：

在没有 API 的情况下部署前端应用
使用 API 部署前端应用
部署 Blazor 应用

Deployment token

SWA CLI 支持使用部署令牌进行部署。从 CI/CD 环境进行部署时，这通常很有用。可以从以下任一获取部署令牌：

Azure 门户：主页→静态 Web 应用→实例→概述→管理部署令牌
如果使用 Azure CLI，可以使用以下命令获取项目的部署令牌：

az staticwebapp secrets list --name <APPLICATION_NAME> --query "properties.apiKey"

如果使用 Azure Static Web Apps CLI，可以使用以下命令：

swa deploy --print-token

然后，可以将该值与 --deployment-token <TOKEN> 一起使用，也可以创建名为 SWA_CLI_DEPLOYMENT_TOKEN 的环境变量并将其设置为部署令牌。

Important

不要将部署令牌存储在公共存储库中。此值必须保持机密。

在没有 API 的情况下部署前端应用

可以通过运行以下步骤，将没有 API 的前端应用程序部署到 Azure Static Web Apps：

如果前端应用程序需要生成步骤，请运行 swa build 或参考应用程序生成说明。

选项 1： 在要部署的生成文件夹中，运行 deploy 命令：

cd build/
swa deploy

Note

文件夹 build 必须包含要部署的应用的静态内容。

选项 2： 还可以部署特定文件夹：

如果前端应用程序需要生成步骤，请运行 swa build 或参考应用程序生成说明。
部署应用：

swa deploy ./my-dist

使用 API 部署前端应用

若要将前端应用和 API 部署到 Azure Static Web Apps，请使用以下步骤：

如果前端应用程序需要生成步骤，请运行 swa build 或参考应用程序生成说明。
确保正确设置 staticwebapp.config.json 文件中的 API 语言运行时版本，例如：

{
  "platform": {
    "apiRuntime": "node:16"
  }
}

Note

如果项目没有任何 staticwebapp.config.json 文件，请在文件夹 outputLocation 下添加一个文件。

部署应用：

swa deploy ./my-dist --api-location ./api

部署 Blazor 应用

若要将具有可选 API 的 Blazor 应用部署到 AAzure Static Web Apps，请使用以下步骤：

在发布模式下生成 Blazor 应用：

dotnet publish -c Release -o bin/publish

从项目的根运行 deploy 命令：

swa deploy ./bin/publish/wwwroot --api-location ./Api

使用 `swa-cli.config.json` 进行部署

Note

outputLocation 的路径必须是相对于 appLocation 的路径。

如果在项目中使用 swa-cli.config.json 配置文件并具有单个配置条目，请使用如下所示的配置：

{
  "configurations": {
    "my-app": {
      "appLocation": "./",
      "apiLocation": "api",
      "outputLocation": "frontend",
      "start": {
        "outputLocation": "frontend"
      },
      "deploy": {
        "outputLocation": "frontend"
      }
    }
  }
}

然后，可以通过运行以下步骤来部署应用程序：

如果前端应用程序需要生成步骤，请运行 swa build 或参考应用程序生成说明。
部署应用：

swa deploy

如果有多个配置条目，可以提供条目 ID 来指定要使用的条目 ID：

swa deploy my-otherapp

Syntax

swa deploy
           [--yes]

Examples

示例 1：使用部署令牌进行部署。

swa deploy ./dist/ --api-location ./api/ --deployment-token <TOKEN>

示例 2：使用环境变量中的部署令牌进行部署

SWA_CLI_DEPLOYMENT_TOKEN=123 swa deploy ./dist/ --api-location ./api/

示例 3：使用 `swa-cli.config.json` 文件进行部署

swa deploy
swa deploy myconfig

示例 4：打印部署令牌

swa deploy --print-token

示例 5：部署到特定环境

swa deploy --env production

Global Parameters

swa db

生成和编辑 Static Web Apps 数据库连接配置。

用于 swa db init 生成示例 swa-db-connections 文件夹以及 staticwebapp.database.config.json 配置文件。如果使用 Cosmos DB for NoSQL 数据库，则还会生成示例 staticwebapp.database.schema.gql 架构文件。

Syntax

swa db init --database-type <DATABASE_TYPE>

Examples

示例 1：为 Azure SQL 数据库生成示例数据库连接配置文件夹。

swa db init --database-type mssql

Parameters

--database-type, -t <DATABASE_TYPE>

（必需）要连接的数据库的类型（mssql、postgresql、cosmosdb_nosql、mysql）。

--folder-name, -f <FOLDER_NAME>

用于替代约定数据库连接配置文件夹名称的文件夹名称（确保相应地更新 CI/CD 工作流文件）。默认值是 swa-db-connections。

---connection-string, -cs <CONNECTION_STRING>

要连接的数据库的连接字符串。

--cosmosdb_nosql-database, -nd <COSMOSDB_NOSQL_DATABASE>

要连接的 Cosmos DB 帐户的数据库（仅当使用 cosmosdb_nosql 数据库类型时才需要）。

--cosmosdb_nosql-container, -nc <COSMOSDB_NOSQL_CONTAINER>

要连接的 Cosmos DB 帐户的容器。

--help, -h

显示命令的帮助。

Global Parameters

通过

Azure 静态 Web 应用 CLI 参考

Commands

Global Parameters

swa login

Syntax

Examples

示例 1：交互式登录到 Azure

Parameters

swa init

Syntax

Examples

示例 1：以交互方式创建新配置。

示例 2：使用所有选项的默认值创建新配置。

示例 3：使用 swa-cli.config.json 文件中名为“myApp”的配置初始化项目。

Parameters

swa build

Syntax

Examples

示例 1：生成应用，并选择性地安装依赖项。

示例 2：检测如何在安装依赖项后生成应用并运行生成命令。

示例 3：安装前端应用程序的依赖项。

示例 4：使用 swa-cli.config.json 中指定的myApp配置生成前端应用程序。

Parameters

swa start

从文件夹提供服务

从开发服务器提供服务

为前端应用和 API 提供服务

自动启动 API 服务器

手动启动 API 服务器

Database connections

Syntax

Examples

示例 1：使用默认值启动应用程序。

示例 2：使用前端开发服务器启动应用程序。

示例 3：使用前端和后端开发服务器启动应用程序。

Parameters

swa deploy

Deployment token

在没有 API 的情况下部署前端应用

使用 API 部署前端应用

部署 Blazor 应用

使用 swa-cli.config.json 进行部署

Syntax

Examples

示例 1：使用部署令牌进行部署。

示例 2：使用环境变量中的部署令牌进行部署

示例 3：使用 swa-cli.config.json 文件进行部署

示例 4：打印部署令牌

示例 5：部署到特定环境

swa db

Syntax

Examples

示例 1：为 Azure SQL 数据库生成示例数据库连接配置文件夹。

Parameters

反馈

其他资源

示例 4：使用 swa-cli.config.json 中指定的`myApp`配置生成前端应用程序。

使用 `swa-cli.config.json` 进行部署

示例 3：使用 `swa-cli.config.json` 文件进行部署