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

Azure Static Web Apps 常见问题解答

生成和部署

Static Web Apps 可以自动生成哪些前端框架?

Static Web Apps 可以自动生成:

  • 流行的单页应用程序 (SPA),包括:React、Vue.js、Angular、Blazor WebAssembly
  • 常用的静态站点生成器,包括:Next.js、Nuxt.js、Gatsby、Hugo、Jekyll、Eleventy

有关详细信息,请参阅配置前端框架

在生成过程中会发生什么情况?

Azure Static Web Apps 的生成引擎由 Oryx 提供支持,Oryx 可生成应用的前端和 API。

生成应用时,Oryx 会检测并自动执行生成步骤。 例如,如果你的应用使用 Node.js,则 Oryx 会使用 npm 或 Yarn 安装包。 然后,Oryx 运行该应用的 package.json 文件中提供的 buildbuild:azure 脚本。

是否可以自定义生成过程?

如果你想要完全控制应用的生成方式,可以在应用的 GitHub 工作流或 Azure DevOps 管道中配置自己的生成步骤。 然后,可以使用 Static Web Apps GitHub Actions 或 Azure Pipelines 任务来部署该应用。 确保将 skip_app_build 设置为 true。 有关详细信息,请参阅生成配置

只有前端应用支持 skip_app_build 命令。 API 应用必须通过 Azure Static Web Apps GitHub Actions 或 Azure Pipelines 任务生成。

我的 React 应用程序无法生成并显示消息“由于 process.env.CI = true,正在将警告视为错误”。 如何修复此错误?

如果你的应用使用 create-react-app,则在 GitHub Actions 或 Azure Pipelines 等持续集成 (CI) 环境中运行时,该应用的生成命令会将警告视为错误。 如果应用中出现警告,它将无法生成。 若要解决这些问题,请修改应用以消除警告。 如果你希望即使出现警告也能成功生成,请更新 package.json 中的生成脚本,来取消设置 CI 环境变量:

"scripts": {
  "build": "CI= react-scripts build"
}

如何更改 GitHub 中的分支?

若要更改要从中进行生成和部署的分支,请更新应用的 GitHub 工作流中的分支名称。 例如,如果要更改应用以从名为 release 的分支进行生成和部署,请更新工作流的 on 部分:

on:
  push:
    branches:
      - release
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - release

对于在预览期创建的静态 Web 应用,可能需要重置部署令牌

是否必须在 Linux GitHub Actions 或 Azure Pipelines 生成代理上运行 Static Web Apps 操作/任务?

Azure Static Web Apps 的生成引擎在 Linux Docker 容器中运行,因此它只能在 Linux 生成代理上运行。

如何部署使用 Git 大文件存储 (LFS) 的应用?

在 GitHub 工作流中,配置 actions/checkout 操作以启用 LFS:

- uses: actions/checkout@v2
  with:
    submodules: true
    lfs: true

部署后是否必须手动清除缓存或使缓存失效?

Azure Static Web Apps 会自动处理缓存失效。 部署完成后,将为所有请求提供最新版本的文件。 但是,文件仍可缓存在用户的浏览器中,或 CDN(如果已配置)中。 若要控制浏览器和 CDN 缓存内容的方式,请在应用的配置文件中配置相应的头。

如果使用 Azure Pipelines 进行部署,是否可以使用预生产环境?

目前,只有 GitHub Actions 支持预生产环境

Hosting

Static Web Apps 是否支持自定义域和 TLS 证书?

可以将应用配置为使用自定义域,包括顶点域。 添加自定义域时,Static Web Apps 会自动提供免费的 TLS 证书。 有关详细信息,请参阅使用免费证书设置自定义域

是否可以自定义应用的 404 错误页?

可以使用配置文件responseOverrides 部分配置自定义错误页。

如何确保我的应用部署到特定的 Azure 区域?

Azure Static Web Apps 是一个全球性的服务。 应用的静态资产分布在全球。 创建应用时,请选择托管的 Azure Functions 应用所部署到的区域。 如果需要在不支持托管函数的区域中部署 Functions 应用,可以将自带 Functions 应用功能用于单独部署的 Functions 应用。

如何在 Azure 应用程序网关或 Azure Front Door 之类的 CDN 后面配置静态 Web 应用?

Azure Static Web Apps 包括全球分布的应用静态资产。 若要最大限度地扩大全球覆盖范围或需要高级功能,可以添加专用的内容分发网络 (CDN) 或 Azure 应用程序网关。

若要将流量限制为特定的 CDN,请配置该 CDN 以在每个请求中添加一个包含预定义机密值的头,并将 Static Web Apps 配置为需要头。 若要将流量限制为某个 Azure 应用程序网关,请配置应用,以便仅允许来自该应用程序网关的 IP 的流量。

此外,将应用配置为允许 CDN 或应用程序网关主机名的转发

若要了解如何配置 Azure Front Door,请参阅此教程

如何启用 Gzip 或 Brotli 压缩?

对于使用流行文本格式文件扩展名(例如 .html.css.js)的资产,Azure Static Web Apps 会自动提供静态资产的 GzipBrotli 压缩版本(如果客户端支持的话)。

对于其他文件类型,Static Web Apps 允许包含使用 .br 扩展名的文件的 Brotli 压缩版本。 例如,如果你有一个名为 app.wasm 的非压缩文件,可以向应用添加名为 app.wasm.br 的压缩版本。 如果支持 Brotli 的客户端请求 app.wasm,将自动提供此版本。

当我访问某个存在的路由时,我的静态 Web 应用为何返回 404 错误?

大多数前端框架(例如 React、Angular 或 Blazor WebAssembly)都使用客户端路由来处理导航。 只有在浏览器中运行的应用才知道客户端路由。 如果从 Static Web Apps 请求客户端路由,则它会返回 404 错误,因为该路由在应用的已部署资产中并不存在。 若要解决此问题,请将回退路由添加到应用的配置文件

配置

如何为应用配置环境变量?

可为应用设置不同类型的环境变量。 在应用的生成配置中配置影响应用前端生成过程的变量。 若要配置应用的 API 使用的变量,请使用应用程序设置。 有关详细信息,请参阅配置概述

Static Web Apps 是否支持托管标识?

Static Web Apps 支持托管标识,但托管标识仅用于从密钥保管库检索身份验证机密

如果需要在 API 中使用托管标识或密钥保管库引用,请通过自带 Functions 应用功能来利用单独的、使用托管标识的 Functions 应用。

身份验证

有多少用户可以登录到我的静态 Web 应用?

Static Web Apps 对可以登录到应用的用户数没有限制。 可以使用内置的邀请系统为最多 25 个用户分配自定义角色。 如果需要为更多用户分配自定义角色,可以使用 API 函数以编程方式分配角色

如何从标识提供者检索用户的访问令牌或声明?

使用 API 函数进行角色管理时,可以检索用户的访问令牌和声明。

我是否仅限于使用单个标识提供者?

使用 Static Web Apps 的内置身份验证时,用户可以使用任何受支持的标识提供者登录。 如果你想要防止用户使用特定的标识提供者登录,可以阻止他们这样做。

如果使用自定义身份验证,可以配置一个或多个标识提供者。

API 函数

如何使用 Static Web Apps 不支持的语言或语言版本编写 API?

Static Web Apps 的托管函数应用不支持 Azure Functions 所支持的部分语言或语言版本。 可以使用自带 Functions 应用功能将单独的 Functions 应用链接到你的静态 Web 应用。

如何创建响应除 HTTP 以外的事件的无服务器函数?

Static Web Apps 中的托管函数应用已针对 API 方案进行优化,仅支持 HTTP 触发器。 如果需要使用 Azure Functions 支持的其他触发器类型(例如用于有状态工作流的 cron 作业或 Durable Functions),可以使用自带 Functions 应用功能将单独的 Functions 应用链接到你的静态 Web 应用。

常规

免费计划有哪些限制?

免费计划包括许多与标准计划相同的功能,例如全球分发、自定义域、免费 TLS 证书、托管 API 函数等。 但是,如果你需要更高的带宽、服务级别协议 (SLA) 或高级功能,则应考虑标准计划。 有关详细信息,请参阅托管计划配额

创建应用后是否可以更改托管计划?

可以随时从免费计划升级到标准计划。 如果不使用需要标准计划的功能,则还可以从标准计划降级到免费计划。

是否可以在本地开发静态 Web 应用而不部署它?

大多数前端框架提供一个用于在本地运行应用的开发服务器。 但是,若要使用身份验证或 API 函数,在不将应用部署到 Azure 情况下,很难测试该应用的所有功能。 若要在本地运行应用,可以使用 Static Web Apps 命令行接口 (CLI),它可以模拟云体验(包括身份验证)并与 Azure Functions Core Tools 集成以运行 API 函数。 还可以使用一个 Static Web Apps Visual Studio Code 扩展将应用部署到 Azure。

如何获得帮助或建议新功能?

如果需要帮助或想要提出建议,可以在 Static Web Apps GitHub 存储库中创建问题。

如需我们立即帮助解决问题,请联系 Azure 支持部门