构建规范的命令和设置特定于分支的构建设置导航到子文件夹为第 1 代应用程序部署带有前端的后端设置输出文件夹在构建过程中安装软件包使用私有 npm 注册表安装操作系统软件包每个构建的键/值存储跳过某个提交的构建禁用自动构建启用或禁用基于 diff 的前端构建和部署为第 1 代应用启用或禁用基于差异的后端构建

配置构建设置

当您使用 Amplify Hosting 部署应用程序时，它会通过检查存储库中的 package.json 文件来自动检测前端框架和相关的构建设置。您可以使用以下选项来存储应用程序构建设置：

在 Amplify 控制台中保存构建设置 – Amplify 控制台会自动检测构建设置并将其保存，以便可以通过 Amplify 控制台访问它们。Amplify 会将这些设置应用于所有分支，除非存储库中存储有 amplify.yml 文件。
将构建设置保存在您的存储库中：下载 amplify.yml 文件并将其添加到存储库的根位置。

您可以在 Amplify 控制台中编辑应用程序的编译设置，方法是在导航窗格中选择 “托管”，然后选择 “编译设置”。这些构建设置将应用于您的应用程序中的所有分支，在存储库中保存了 amplify.yml 文件的分支除外。

注意

只有将应用程序@@ 设置为持续部署并连接到 git 存储库时，构建设置才会显示在 Amplify 控制台的 “托管” 菜单中。有关此类部署的说明，请参阅入门。

构建规范的命令和设置

构建规范 YAML 包含一系列构建命令和相关设置，Amplify 会使用这些命令和设置来运行构建。下表描述了这些设置及其使用方式。

版本

Amplify YAML 版本号。

appRoot

此应用程序所在存储库中的路径。除非定义了多个应用程序，否则忽略。

env

向此部分中添加环境变量。您还可以使用控制台添加环境变量。

后端

在持续部署过程中，运行 Amplify CLI 命令来预置后端、更新 Lambda 函数或 GraphQL 架构。

frontend

运行前端构建命令。

测试

在测试阶段运行命令。了解如何为应用程序添加测试。

构建阶段

前端和后端都具有三个阶段，表示在每个构建序列中运行的命令。

preBuild：预构建脚本在实际构建启动之前、Amplify 安装依赖项之后运行。
build – 您的构建命令。
postBuild – 构建后脚本在构建已完成并且 Amplify 已将所有必要项目都复制到输出目录后运行。

buildpath

用于运行构建程序的路径。Amplify 使用此路径来查找您的构建构件。如果您没有指定路径，Amplify 会使用单一存储库应用程序根目录，例如 apps/app。

artifacts>base-directory

您的构建构建所位于的目录。

artifacts>files

指定要部署的构件中的文件。输入 **/* 以包含所有文件。

cache

构建规范的缓存字段用于缓存构建时的依赖项，例如 node_modules 文件夹，并根据客户应用程序内置的软件包管理器和框架自动推荐。第一次构建时会缓存这里的任何路径，在随后的构建中，我们会重新填充缓存，并尽可能使用这些缓存的依赖项来加快构建时间。

以下构建规范示例演示了基本的 YAML 语法：


version: 1
env:
  variables:
    key: value
backend:
  phases:
    preBuild:
      commands:
        - *enter command*
    build:
      commands:
        - *enter command*
    postBuild:
        commands:
        - *enter command*
frontend:
  buildpath:
  phases:
    preBuild:
      commands:
        - cd react-app
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    files:
        - location
        - location
    discard-paths: yes
    baseDirectory: location
  cache:
    paths:
        - path
        - path
test:
  phases:
    preTest:
      commands:
        - *enter command*
    test:
      commands:
        - *enter command*
    postTest:
      commands:
        - *enter command*
  artifacts:
    files:
        - location
        - location
    configFilePath: *location*
    baseDirectory: *location*

特定于分支的构建设置

您可以使用 bash shell 脚本设置特定于分支的构建设置。例如，如果分支名称为 main，则以下脚本使用系统环境变量 $AWS_ BRANCH 运行一组命令；如果分支名称为 dev，则使用另一组命令。


frontend:
  phases:
    build:
      commands:
        - if [ "${AWS_BRANCH}" = "main" ]; then echo "main branch"; fi
        - if [ "${AWS_BRANCH}" = "dev" ]; then echo "dev branch"; fi

导航到子文件夹

对于单一存储库，用户希望能够通过 cd 命令进入文件夹以运行构建。运行 cd 命令后，它将应用于构建的所有阶段，因此您无需在单独的阶段中重复该命令。


version: 1
env:
  variables:
    key: value
frontend:
  phases:
    preBuild:
      commands:
        - cd react-app
        - npm ci
    build:
      commands:
        - npm run build

为第 1 代应用程序部署带有前端的后端

注意

本节仅适用于 Amplify Gen 1 应用程序。第一代后端是使用 Amplify Studio 和 Amplify 命令行界面 (CLI) 创建的。

该 amplifyPush 命令是一个帮助程序脚本，可以帮助您进行后端部署。下面的构建设置自动为当前分支确定正确的待部署后端环境。


version: 1
env:
  variables:
    key: value
backend:
  phases:
    build:
      commands:
        - amplifyPush --simple

设置输出文件夹

以下构建设置将输出目录设置为公用文件夹。


frontend:
  phases:
    commands:
      build:
        - yarn run build
  artifacts:
    baseDirectory: public

在构建过程中安装软件包

您可以在构建过程中使用 npm 或 yarn 命令来安装软件包。


frontend:
  phases:
    build:
      commands:
        - npm install -g <package>
        - <package> deploy
        - yarn run build
  artifacts:
    baseDirectory: public

使用私有 npm 注册表

您可以在构建设置中添加对私有注册表的引用或将其添加为环境变量。


build:
  phases:
    preBuild:
      commands:
        - npm config set <key> <value>
        - npm config set registry https://registry.npmjs.org
        - npm config set always-auth true
        - npm config set email hello@amplifyapp.com
        - yarn install

安装操作系统软件包

Amplify 的 AL2023 镜像使用名为的非特权用户运行你的代码。amplifyAmplify 授予该用户使用 Linux sudo 命令运行操作系统命令的权限。如果要为缺少的依赖项安装操作系统包，则可以使用诸如yum和之类rpm的命令sudo。

以下示例构建部分演示了使用sudo命令安装操作系统软件包的语法。


build:
  phases:
    preBuild:
      commands:
        - sudo yum install -y <package>

每个构建的键/值存储

envCache 在构建时提供键/值存储。envCache 中存储的值只能在构建期间进行修改并可在下次构建时重复使用。使用 envCache，我们可以存储有关已部署环境的信息并将其提供给连续构建中的构建容器。与存储在 envCache 中的值不同，构建期间对环境变量的更改不会持久保存，无法在将来的构建中使用。

示例用法：


envCache --set <key> <value>
envCache --get <key>

跳过某个提交的构建

要跳过对特定提交的自动构建，请在提交消息的末尾添加文本 [skip-cd]。

禁用自动构建

您可以配置 Amplify，禁用在每次提交代码时自动构建。要进行设置，请选择 “应用程序设置”、“分支设置”，然后找到列出已连接分支的 “分支” 部分。选择一个分支，然后依次选择 “操作”、“禁用自动构建”。对该分支的新提交将不再启动新构建。

启用或禁用基于 diff 的前端构建和部署

您可以将 Amplify 配置为使用基于 diff 的前端构建。如果启用，则默认情况下，Amplify 会在每次构建开始时尝试对您的 appRoot 或 /src/ 文件夹运行 diff。如果 Amplify 未发现任何差异，它将跳过前端构建、测试（如果已配置）和部署步骤，并且不会更新托管的应用程序。

配置基于 diff 的前端构建和部署

登录 AWS Management Console 并打开 Amplify 控制台。
选择要为其配置基于 diff 的前端构建和部署的应用程序。
在导航窗格中，选择主机，环境变量。
在环境变量部分中，选择管理变量。
配置环境变量的过程会有所不同，具体取决于您是启用还是禁用基于 diff 的前端构建和部署。
- 启用基于 diff 的前端构建和部署
  1. 在管理变量部分，请在变量下输入 AMPLIFY_DIFF_DEPLOY。
  2. 对于值，请输入 true。
- 禁用基于 diff 的前端构建和部署
  1. 请执行以下操作之一：
    - 在管理变量部分，找到 AMPLIFY_DIFF_DEPLOY。对于值，请输入 false。
    - 删除 AMPLIFY_DIFF_DEPLOY 环境变量。
选择保存。

或者，您可以将环境变量 AMPLIFY_DIFF_DEPLOY_ROOT 设置为使用存储库根目录的相对路径来覆盖默认路径，例如 dist。

为第 1 代应用启用或禁用基于差异的后端构建

注意

本节仅适用于 Amplify Gen 1 应用程序。第一代后端是使用 Amplify Studio 和 Amplify 命令行界面 (CLI) 创建的。

您可以使用环境变量 AMPLIFY_DIFF_BACKEND 将 Amplify Hosting 配置为使用基于 diff 的后端构建。当您启用基于 diff 的后端构建时，Amplify 会在每次构建开始时尝试对存储库中的 amplify 文件夹运行 diff。如果 Amplify 没有发现任何差异，它将跳过后端构建步骤，并且不会更新您的后端资源。如果您的项目存储库中没有 amplify 文件夹，Amplify 会忽略 AMPLIFY_DIFF_BACKEND 环境变量的值。

如果您当前在后端阶段的构建设置中指定了自定义命令，则有条件的后端构建将不起作用。如果要运行这些自定义命令，则必须将其移至应用程序 amplify.yml 文件中构建设置的前端阶段。

配置基于 diff 的后端构建

登录 AWS Management Console 并打开 Amplify 控制台。
选择要为其配置基于 diff 的后端构建的应用程序。
在导航窗格中，选择主机，环境变量。
在环境变量部分中，选择管理变量。
配置环境变量的过程会有所不同，具体取决于您是启用还是禁用基于 diff 的后端构建。
- 启用基于 diff 的后端构建
  1. 在管理变量部分，请在变量下输入 AMPLIFY_DIFF_BACKEND。
  2. 对于值，请输入 true。
- 禁用基于 diff 的后端构建
  1. 请执行以下操作之一：
    - 在管理变量部分，找到 AMPLIFY_DIFF_BACKEND。对于值，请输入 false。
    - 删除 AMPLIFY_DIFF_BACKEND 环境变量。
选择保存。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

自定义域问题排查

单一存储库构建设置