# @aws-cdk/cfn-property-mixins 中文文档

规范地址：https://npmcn.com/package/%40aws-cdk/cfn-property-mixins/

版本：2\.275\.0
npm 元数据更新时间：2026-10-26T19:17:10.775Z
中文译文更新时间：2026-11-07T14:14:32.911Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：45.7 MB，1596 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 20\.0\.0
- 运行依赖：0 个
- peer 依赖：constructs ^10\.5\.0，aws-cdk-lib ^2\.275\.0
- 首次发布：2026-03-11T16:04:24.769Z
- 最新版本发布：2026-10-26T19:17:09.709Z
- 近 30 天下载量：25151（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 38 个）

## 中文简介

为 CloudFormation 资源属性自动生成的 CDK Mixins.

## 安装

```sh
npm install @aws-cdk/cfn-property-mixins
```

也可以使用：`pnpm add @aws-cdk/cfn-property-mixins`、`yarn add @aws-cdk/cfn-property-mixins`、`bun add @aws-cdk/cfn-property-mixins`

## README

# CDK 云格式属性混合

* * *

![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge)

* * *

每个 CloudFormation 资源属性的自动生成,类型安全 CDK Mixins. 这些允许您将 L1 属性应用到任何使用 Mixins 机制的构造( L1, L2 或自定义) `aws-cdk-lib`。 。 。 .

## 使用量

对于每一个 CloudFormation 资源,此软件包提供 `CfnXxxPropsMixin` 课. 应用它 `.with()` 或者说 `Mixins.of()`数字 :

```typescript
new s3.Bucket(scope, "MyBucket")
  .with(new CfnBucketPropsMixin({
    versioningConfiguration: { status: "Enabled" },
    publicAccessBlockConfiguration: {
      blockPublicAcls: true,
      blockPublicPolicy: true,
    },
  }));
```

### 跨服务参考资料

深嵌属性支持跨服务引用:

```typescript
const myKey = new kms.Key(scope, "MyKey");

new s3.Bucket(scope, "EncryptedBucket")
  .with(new CfnBucketPropsMixin({
    bucketEncryption: {
      serverSideEncryptionConfiguration: [{
        serverSideEncryptionByDefault: {
          sseAlgorithm: "aws:kms",
          kmsMasterKeyId: myKey,
        },
      }],
    },
  }));
```

### 合并策略

当使用混音时,其属性会使用合并策略被合并到目标资源上. 策略控制了混合和现有资源定义同一属性时会发生什么.

有两个内在战略:

#### `PropertyMergeStrategy.combine()` (默认)

深地将从混合物中嵌入的物体合并入目标. 当一个属性的现有值和新值都是平面对象时,它们的键会相继被合并——保留了现有的键并添加了新的键. 初级、数组和不匹配类型被混合值所取代.

如果您想要在不丢失已经设置的内容的情况下添加配置, 这样做是有用的 :

```typescript
const combineBucket = new s3.CfnBucket(scope, "CombineBucket");
combineBucket.publicAccessBlockConfiguration = { blockPublicAcls: true };

// Adds blockPublicPolicy while preserving the existing blockPublicAcls
combineBucket.with(new CfnBucketPropsMixin({
  publicAccessBlockConfiguration: { blockPublicPolicy: true },
}));
// Result: { blockPublicAcls: true, blockPublicPolicy: true }
```

#### `PropertyMergeStrategy.override()`

用混合值取代已有属性值. 每个财产都按原样复制,而不检查嵌入物. 目标上任何先前的值都会被丢弃.

当您想要完全替换配置时, 这样做是有用的 :

```typescript
const overrideBucket = new s3.CfnBucket(scope, "OverrideBucket");
overrideBucket.publicAccessBlockConfiguration = { blockPublicAcls: true };

// Replaces the entire publicAccessBlockConfiguration
overrideBucket.with(new CfnBucketPropsMixin(
  { publicAccessBlockConfiguration: { blockPublicPolicy: true } },
  { strategy: PropertyMergeStrategy.override() },
));
// Result: { blockPublicPolicy: true } — blockPublicAcls is gone
```

#### 自定义策略

您可以执行 `IMergeStrategy` 定义自己的合并行为. 这个 `apply` 方法接收目标对象、源对象和属性密钥允许列表:

```typescript
class ArrayAppendStrategy implements IMergeStrategy {
  public apply(target: any, source: any, allowedKeys: string[]) {
    for (const key of allowedKeys) {
      if (key in source) {
        if (Array.isArray(target[key])) {
          // append to target
          target[key] = target[key].concat(source[key]);
        } else {
          // override
          target[key] = source[key];
        }
      }
    }
  }
}
```

### 递延值(框)

属性混合支持 **框后值**中的大多数 L2 构造 `aws-cdk-lib` 内部使用 Boxes 将属性计算推迟到合成时间。 当混音在目标上遇到Box时,合并会被自动推迟——一旦Box解决,合并策略就会运行,确保它运行在最终值上.

这意味着混合剂与使用 Boxes 属性的 L2 构造正确工作,例如 `replicas`, (中文(简体) ), `rules`,或 `tags`,无需用户的特殊处理:

```typescript
// TableV2 uses a Box internally for replicas.
// The mixin defers the merge and appends the new replica at synthesis time.
const table = new dynamodb.TableV2(scope, 'Table', {
  partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
  // L2 prop: pointInTimeRecovery is a boolean
  replicas: [{ region: 'us-east-1', pointInTimeRecovery: true }],
});

// Mixins always use L1 (CloudFormation) property names and shapes,
// regardless of what the L2 API looks like.
table.with(new CfnGlobalTablePropsMixin({
  replicas: [{
    region: 'eu-west-1',
    // L1 prop: pointInTimeRecoverySpecification is an object
    pointInTimeRecoverySpecification: { pointInTimeRecoveryEnabled: true },
  }],
}, { strategy: PropertyMergeStrategy.combine({ arrays: ArrayMergeStrategy.append() }) }));

// Result (synthesized CloudFormation):
// Replicas:
//   - Region: us-east-1
//     PointInTimeRecoverySpecification:
//       PointInTimeRecoveryEnabled: true
//   - Region: us-west-2        <-- primary region, added by L2
//   - Region: eu-west-1        <-- added by mixin
//     PointInTimeRecoverySpecification:
//       PointInTimeRecoveryEnabled: true
```

大多数 L2 构造在 `aws-cdk-lib` 内部使用 Boxes 或 Lazys 将属性计算推迟到合成时间。 属性混和器自动检测到这些并推迟合并直到数值解决,所以合并策略总是在最终值上运行——不需要用户的特殊处理. 无法推迟合并的唯一情况是原始 `Token` 没有盒子支持。 这在AWS Construction 库中非常罕见,但可能在第三方包中出现. 如果你遇到一个建筑 合并没有预期的效果,请 [打开一个问题](https://github.com/aws/aws-cdk/issues/new?template=bug-report.yml) 这样我们就可以调查了.

### 每个服务的云格式属性混合

这个软件包为所有AWS服务的每个CloudFormation资源提供自动生成的地产混接器. 每个服务都有自己的子模块来反映 `aws-cdk-lib` 模块结构. 从相应的服务子模块导入您想要配置的资源的混音 :

```typescript
import { CfnBucketPropsMixin } from '@aws-cdk/cfn-property-mixins/aws-s3';
import { CfnFunctionPropsMixin } from '@aws-cdk/cfn-property-mixins/aws-lambda';
import { CfnTablePropsMixin } from '@aws-cdk/cfn-property-mixins/aws-dynamodb';
import { CfnLogGroupPropsMixin } from '@aws-cdk/cfn-property-mixins/aws-logs';
import { CfnDistributionPropsMixin } from '@aws-cdk/cfn-property-mixins/aws-cloudfront';
import { CfnDBInstancePropsMixin } from '@aws-cdk/cfn-property-mixins/aws-rds';
```

命名公约遵循一个一致的模式: 用于 Cloud Formation 资源 `AWS::S3::Bucket`,混音类是 `CfnBucketPropsMixin` 并生活在一个 `aws-s3` 子模块. 混合道具接口的名称 `CfnBucketMixinProps` 而所有属性都是可选的,所以只需要指定要设置的属性.

属性混合与任何以目标资源为默认子的构造相配合. 这意味着您可以将其应用于 L1 构造, L2 构造,以及自定义构造 :

```typescript
// L1 construct
new s3.CfnBucket(scope, "L1Bucket")
  .with(new CfnBucketPropsMixin({ versioningConfiguration: { status: "Enabled" } }));

// L2 construct — the mixin finds the CfnBucket default child
new s3.Bucket(scope, "L2Bucket")
  .with(new CfnBucketPropsMixin({ versioningConfiguration: { status: "Enabled" } }));
```

## 常见问题

### @aws-cdk/cfn-property-mixins 是什么？

为 CloudFormation 资源属性自动生成的 CDK Mixins\.

### 如何安装 @aws-cdk/cfn-property-mixins？

在项目目录运行 npm install @aws-cdk/cfn-property-mixins，或使用 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/cfn-property-mixins 支持 TypeScript 吗？

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

### @aws-cdk/cfn-property-mixins 支持 ESM 还是 CommonJS？

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

### @aws-cdk/cfn-property-mixins 需要什么版本的 Node\.js？

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

### @aws-cdk/cfn-property-mixins 可以商用吗？

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

### @aws-cdk/cfn-property-mixins 的下载量有多少？

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

### @aws-cdk/cfn-property-mixins 还在维护吗？

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