# @aws-cdk/aws-apprunner-alpha 中文文档

规范地址：https://npmcn.com/package/%40aws-cdk/aws-apprunner-alpha/

版本：2\.275\.0-alpha\.0
npm 元数据更新时间：2026-10-26T19:16:16.821Z
中文译文更新时间：2026-11-07T13:56:14.996Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk/aws-apprunner-alpha
原文对照：https://npmcn.com/package/%40aws-cdk/aws-apprunner-alpha/?lang=original
项目主页：https://github.com/aws/aws-cdk
源码仓库：https://github.com/aws/aws-cdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：829 kB，23 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 20\.0\.0
- 运行依赖：0 个
- peer 依赖：constructs ^10\.5\.0，aws-cdk-lib ^2\.275\.0
- 首次发布：2021-10-13T18:38:08.432Z
- 最新版本发布：2026-10-26T19:16:15.935Z
- 近 30 天下载量：45033（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：380（近 12 个月 64 个）

## 中文简介

AWS: AppRunner 的 CDK 构造库

## 安装

```sh
npm install @aws-cdk/aws-apprunner-alpha
```

也可以使用：`pnpm add @aws-cdk/aws-apprunner-alpha`、`yarn add @aws-cdk/aws-apprunner-alpha`、`bun add @aws-cdk/aws-apprunner-alpha`

## README

# AWS: AppRunner 构造库

* * *

![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)

> 本单元中更高层次的构件的API是实验性的并正在积极开发中. 在今后任何版本中,它们都须作非背向相容的修改或去除。 这些是 不适用 [语义版本](https://semver.org/) 模型和断开的更改 在发行笔记中宣布. 这意味着虽然你可能使用它们,但可能需要更新 当更新到此软件包的更新版本时,您的源代码.

* * *

这个模块是 [AWS 云开发套件](https://github.com/aws/aws-cdk) 项目.

```ts
import * as apprunner from '@aws-cdk/aws-apprunner-alpha';
```

## 导言

AWS App Runner是一种完全管理的服务,它使得开发者能够快速地部署集装箱化的网络应用程序和API,在规模上,不需要事先的基础设施经验. 从您的源代码或容器图像开始 。 App Runner自动构建并部署网络应用程序,并用加密方式加载流量平衡. App Runner 也自动缩放上下,以满足您的流量需要. 有了App Runner,而不是考虑服务器或缩放,你有更多的时间专注于你的应用程序.

## 服务

这个 `Service` 构造允许您使用 `ECR Public`, (中文(简体) ), `ECR` 或者说 `Github` 与 `source` 在下列情况下的属性:

-   `Source.fromEcr()` - 定义源寄存器 `ECR`。 。 。 .
-   `Source.fromEcrPublic()` - 定义源寄存器 `ECR Public`。 。 。 .
-   `Source.fromGitHub()` - 从 `Github repository`。 。 。 .
-   `Source.fromAsset()` - 从本地资产目录中定义来源.

这个 `Service` 构造工具 `IGrantable`。 。 。 .

## ECR 公众

创建 `Service` eCR 公开 :

```ts
new apprunner.Service(this, 'Service', {
  source: apprunner.Source.fromEcrPublic({
    imageConfiguration: { port: 8000 },
    imageIdentifier: 'public.ecr.aws/aws-containers/hello-app-runner:latest',
  }),
});
```

## ECR( 电子格式)

创建 `Service` 从现有的ECR存储器中:

```ts
import * as ecr from 'aws-cdk-lib/aws-ecr';

new apprunner.Service(this, 'Service', {
  source: apprunner.Source.fromEcr({
    imageConfiguration: { port: 80 },
    repository: ecr.Repository.fromRepositoryName(this, 'NginxRepository', 'nginx'),
    tagOrDigest: 'latest',
  }),
});
```

创建 `Service` 从本地 docker 图像资产目录创建并被推到 Amazon ECR:

您可以指定是否允许从源寄存器与 `autoDeploymentsEnabled` 旗帜.

```ts
import * as assets from 'aws-cdk-lib/aws-ecr-assets';

const imageAsset = new assets.DockerImageAsset(this, 'ImageAssets', {
  directory: path.join(__dirname, 'docker.assets'),
});
new apprunner.Service(this, 'Service', {
  source: apprunner.Source.fromAsset({
    imageConfiguration: { port: 8000 },
    asset: imageAsset,
  }),
  autoDeploymentsEnabled: true,
});
```

## GitHub 图像

创建 `Service` 从 GitHub 寄存器中, 您需要指定一个已有的 App 运行器 `Connection`。 。 。 .

见 [管理 App 运行器连接](https://docs.aws.amazon.com/apprunner/latest/dg/manage-connections.html) 更多细节.

```ts
new apprunner.Service(this, 'Service', {
  source: apprunner.Source.fromGitHub({
    repositoryUrl: 'https://github.com/aws-containers/hello-app-runner',
    branch: 'main',
    configurationSource: apprunner.ConfigurationSourceType.REPOSITORY,
    connection: apprunner.GitHubConnection.fromConnectionArn('CONNECTION_ARN'),
  }),
});
```

使用 `codeConfigurationValues` 以 `API` 配置源类型 .

```ts
new apprunner.Service(this, 'Service', {
  source: apprunner.Source.fromGitHub({
    repositoryUrl: 'https://github.com/aws-containers/hello-app-runner',
    branch: 'main',
    configurationSource: apprunner.ConfigurationSourceType.API,
    codeConfigurationValues: {
      runtime: apprunner.Runtime.PYTHON_3,
      port: '8000',
      startCommand: 'python app.py',
      buildCommand: 'yum install -y pycairo && pip install -r requirements.txt',
    },
    connection: apprunner.GitHubConnection.fromConnectionArn('CONNECTION_ARN'),
  }),
});
```

## IAM 角色

您可以定义 `instanceRole` 财务报告和审定财务报表 `accessRole` 联 合 国 `Service`。 。 。 .

`instanceRole` - 为您的 App Runner 服务提供权限的 IAM 角色 。 这些是权限 当代码调用 AWS API 时, 您需要代码 。 如果没有定义, 将生成一个新的实例角色 必要时.

将IAM政策声明添加到这一角色中,使用 `addToRolePolicy()`数字 :

```ts
import * as iam from 'aws-cdk-lib/aws-iam';

const service = new apprunner.Service(this, 'Service', {
  source: apprunner.Source.fromEcrPublic({
    imageConfiguration: { port: 8000 },
    imageIdentifier: 'public.ecr.aws/aws-containers/hello-app-runner:latest',
  }),
});

service.addToRolePolicy(new iam.PolicyStatement({
  effect: iam.Effect.ALLOW,
  actions: ['s3:GetObject'],
  resources: ['*'],
}))
```

`accessRole` - 赋予App Runner服务访问源存储器的IAM角色。 这是需要的 ECR图像存储器(但不用于ECR公共存储器). 如果没有定义,将产生一个新的访问角色 必要时.

见 [App 运行器 IAM 角色](https://docs.aws.amazon.com/apprunner/latest/dg/security_iam_service-with-iam.html#security_iam_service-with-iam-roles) 更多细节.

## 自动缩放配置

将 App Runner 服务与自定义自动缩放配置关联起来, 定义 `autoScalingConfiguration` 为服务.

```ts
const autoScalingConfiguration = new apprunner.AutoScalingConfiguration(this, 'AutoScalingConfiguration', {
  autoScalingConfigurationName: 'MyAutoScalingConfiguration',
  maxConcurrency: 150,
  maxSize: 20,
  minSize: 5,
});

new apprunner.Service(this, 'DemoService', {
  source: apprunner.Source.fromEcrPublic({
    imageConfiguration: { port: 8000 },
    imageIdentifier: 'public.ecr.aws/aws-containers/hello-app-runner:latest',
  }),
  autoScalingConfiguration,
});
```

## VPC 连接器

要将 App Runner 服务与自定义的 VPC 连接,请定义 `vpcConnector` 为服务.

```ts
import * as ec2 from 'aws-cdk-lib/aws-ec2';

const vpc = new ec2.Vpc(this, 'Vpc', {
  ipAddresses: ec2.IpAddresses.cidr('10.0.0.0/16')
});

const vpcConnector = new apprunner.VpcConnector(this, 'VpcConnector', {
  vpc,
  vpcSubnets: vpc.selectSubnets({ subnetType: ec2.SubnetType.PUBLIC }),
  vpcConnectorName: 'MyVpcConnector',
});

new apprunner.Service(this, 'Service', {
  source: apprunner.Source.fromEcrPublic({
    imageConfiguration: { port: 8000 },
    imageIdentifier: 'public.ecr.aws/aws-containers/hello-app-runner:latest',
  }),
  vpcConnector,
});
```

## VPC 入侵连接

让您的 App Runner 服务私有化, 并且只能从 VPC 内部访问 `isPubliclyAccessible` 财产并与之关联 `VpcIngressConnection` 资源.

设立 `VpcIngressConnection`,指定一个 VPC,一个 VPC 界面端点,以及 App Runner 服务. 还有,你必须准备好 `isPubliclyAccessible` 属性在 r `Service` 改为 `false`。 。 。 .

更多信息见 [允许进入的私人端口](https://docs.aws.amazon.com/apprunner/latest/dg/network-pl.html)。 。 。 .

```typescript
import * as ec2 from 'aws-cdk-lib/aws-ec2';

declare const vpc: ec2.Vpc;

const interfaceVpcEndpoint = new ec2.InterfaceVpcEndpoint(this, 'MyVpcEndpoint', {
  vpc,
  service: ec2.InterfaceVpcEndpointAwsService.APP_RUNNER_REQUESTS,
  privateDnsEnabled: false,
});

const service = new apprunner.Service(this, 'Service', {
  source: apprunner.Source.fromEcrPublic({
    imageConfiguration: {
      port: 8000,
    },
    imageIdentifier: 'public.ecr.aws/aws-containers/hello-app-runner:latest',
  }),
  isPubliclyAccessible: false, // set false
});

new apprunner.VpcIngressConnection(this, 'VpcIngressConnection', {
  vpc,
  interfaceVpcEndpoint,
  service,
});
```

## 双堆叠

要使用双堆栈( IPv4 和 IPv6) 来配置您的 公共网络, 设置 `ipAddressType` 改为 `IpAddressType.DUAL_STACK`。 。 。 .

```ts
new apprunner.Service(this, 'Service', {
  source: apprunner.Source.fromEcrPublic({
    imageConfiguration: { port: 8000 },
    imageIdentifier: 'public.ecr.aws/aws-containers/hello-app-runner:latest',
  }),
  ipAddressType: apprunner.IpAddressType.DUAL_STACK,
});
```

**说明**:目前,App Runner只支持公共端点的双堆栈. 私人端点只支持IPv4. 如果你更新了一个使用双层公共端点到私人端点的服务, 您的 App Runner 服务将默认仅支持私人端点的 IPv4 并失败 以接收来自IPv6端点的流量.

## 机密管理器

要纳入与 AWS 保密管理器整合的环境变量,请使用 `environmentSecrets` 属性. 你可以用这个 `addSecret` 来自 App 运行器的方法 `Service` 分类包括来自外部的秘密 服务定义.

```ts
import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
import * as ssm from 'aws-cdk-lib/aws-ssm';

declare const stack: Stack;

const secret = new secretsmanager.Secret(stack, 'Secret');
const parameter = ssm.StringParameter.fromSecureStringParameterAttributes(stack, 'Parameter', {
  parameterName: '/name',
  version: 1,
});

const service = new apprunner.Service(stack, 'Service', {
  source: apprunner.Source.fromEcrPublic({
    imageConfiguration: {
      port: 8000,
      environmentSecrets: {
        SECRET: apprunner.Secret.fromSecretsManager(secret),
        PARAMETER: apprunner.Secret.fromSsmParameter(parameter),
        SECRET_ID: apprunner.Secret.fromSecretsManagerVersion(secret, { versionId: 'version-id' }),
        SECRET_STAGE: apprunner.Secret.fromSecretsManagerVersion(secret, { versionStage: 'version-stage' }),
      },
    },
    imageIdentifier: 'public.ecr.aws/aws-containers/hello-app-runner:latest',
  })
});

service.addSecret('LATER_SECRET', apprunner.Secret.fromSecretsManager(secret, 'field'));
```

## 使用客户管理的密钥

要使用客户管理的密钥进行源加密,请使用 `kmsKey` 属性.

```ts
import * as kms from 'aws-cdk-lib/aws-kms';

declare const kmsKey: kms.IKey;

new apprunner.Service(this, 'Service', {
  source: apprunner.Source.fromEcrPublic({
    imageConfiguration: { port: 8000 },
    imageIdentifier: 'public.ecr.aws/aws-containers/hello-app-runner:latest',
  }),
  kmsKey,
});
```

## 健康检查

要配置服务的健康检查,请使用 `healthCheck` 属性.

您可以用静态方法指定 `HealthCheck.http` 或者说 `HealthCheck.tcp`。 。 。 .

```ts
new apprunner.Service(this, 'Service', {
  source: apprunner.Source.fromEcrPublic({
    imageConfiguration: { port: 8000 },
    imageIdentifier: 'public.ecr.aws/aws-containers/hello-app-runner:latest',
  }),
  healthCheck: apprunner.HealthCheck.http({
    healthyThreshold: 5,
    interval: Duration.seconds(10),
    path: '/',
    timeout: Duration.seconds(10),
    unhealthyThreshold: 10,
  }),
});
```

## 可观察性配置

要将 App Runner 服务与自定义可观察配置关联起来,请使用 `observabilityConfiguration` 属性.

```ts
const observabilityConfiguration = new apprunner.ObservabilityConfiguration(this, 'ObservabilityConfiguration', {
  observabilityConfigurationName: 'MyObservabilityConfiguration',
  traceConfigurationVendor: apprunner.TraceConfigurationVendor.AWSXRAY,
});

new apprunner.Service(this, 'DemoService', {
  source: apprunner.Source.fromEcrPublic({
    imageConfiguration: { port: 8000 },
    imageIdentifier: 'public.ecr.aws/aws-containers/hello-app-runner:latest',
  }),
  observabilityConfiguration,
});
```

## 常见问题

### @aws-cdk/aws-apprunner-alpha 是什么？

AWS: AppRunner 的 CDK 构造库

### 如何安装 @aws-cdk/aws-apprunner-alpha？

在项目目录运行 npm install @aws-cdk/aws-apprunner-alpha，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：constructs（^10\.5\.0）、aws-cdk-lib（^2\.275\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-cdk/aws-apprunner-alpha 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws-cdk/aws-apprunner-alpha 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws-cdk/aws-apprunner-alpha 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aws-cdk/aws-apprunner-alpha 可以商用吗？

@aws-cdk/aws-apprunner-alpha 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-cdk/aws-apprunner-alpha 的下载量有多少？

根据 npm 官方下载统计，@aws-cdk/aws-apprunner-alpha 在 2026/10/07 – 2026/11/05 这 30 天内被下载 45,033 次，日均约 1,501 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws-cdk/aws-apprunner-alpha 还在维护吗？

最新版本 2\.275\.0-alpha\.0 发布于 2026/10/27（12 天前）；至今共发布 380 个版本，其中过去 12 个月发布了 64 个；首次发布于 2021/10/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。