Context Hub 中 `@aws-sdk/client-acm` 完整实践：AWS SDK for JavaScript v3 下的 TLS 证书全生命周期管理

本文基于 Context Hub 仓库中维护的aws/acmJavaScript 文档（content/aws/docs/acm/javascript/DOC.md），系统讲解如何在 Node.js 中用@aws-sdk/client-acm完成 ACM 证书的申请、DNS 验证、轮询等待、分页列举、PEM 导入与清理等全生命周期操作。读完本文，你可以直接在可信后端服务中落地一套可运行的证书管理代码，并理解该文档在 Context Hub 中如何被检索、分发和消费。

在 Context Hub 中获取本文对应文档

Context Hub 为编码 Agent 提供"按语言、按版本"分发的 API 文档。本仓库中该文档位于多语言目录结构下，符合 Content Guide 定义的多语言约定：

author/docs/entry-name/ javascript/ DOC.md # JavaScript 变体

文件的 YAML frontmatter 声明了它的元数据：name: acm、languages: "javascript"、versions: "3.1007.0"、source: maintainer，这些字段与 Content Guide 中 DOC.md frontmatter 的必填项（name、description、metadata.languages、metadata.versions、metadata.revision、metadata.updated-on、metadata.source）一一对应，用于构建注册表和搜索索引。

安装 CLI 后，通过以下命令即可取回该文档：

npm install -g @aisuite/chub chub search "aws acm" # 搜索，得到条目 ID aws/acm chub get aws/acm --lang js # 拉取 JavaScript 变体

从源码结构看，chub get的解析链路是：get.js 调用 registry.js 中的getEntry()按 ID 定位条目，再用resolveDocPath(entry, lang, version)根据语言与recommendedVersion选出具体版本的path，最后由resolveEntryFile()拼接出DOC.md的文件路径。frontmatter 的解析由 frontmatter.js 中的parseFrontmatter()完成——它会抛出带行列位置的FrontmatterParseError，保证构建期能报出文件级准确的错误位置。

安装与前置条件

安装包

npm install @aws-sdk/client-acm

如果应用代码中需要显式的 profile、SSO 或 assume-role 凭证提供者，按需安装凭证辅助包：

npm install @aws-sdk/credential-providers

ACM 是区域化（Regional）服务

客户端必须创建在证书所在（或即将创建）的 AWS 区域。典型的本地环境配置：

export AWS_REGION="us-east-1" export AWS_PROFILE="dev"

或使用直连凭证：

export AWS_REGION="us-east-1" export AWS_ACCESS_KEY_ID="..." export AWS_SECRET_ACCESS_KEY="..." export AWS_SESSION_TOKEN="..."

在 Node.js 中，如果凭证已经来自环境变量、共享 AWS 配置文件、ECS、EC2 实例元数据或 IAM Identity Center，默认凭证链通常就够用。

一个重要的安全前提：ACM 管理操作应放在可信的后端或自动化代码中，而不是不受信任的浏览器端。

客户端配置

最小 Node.js 客户端

import { ACMClient } from "@aws-sdk/client-acm"; const acm = new ACMClient({ region: process.env.AWS_REGION ?? "us-east-1", });

显式指定 profile 的凭证

import { ACMClient } from "@aws-sdk/client-acm"; import { fromIni } from "@aws-sdk/credential-providers"; const acm = new ACMClient({ region: "us-east-1", credentials: fromIni({ profile: "dev" }), });

fromIni读取本地~/.aws/credentials/~/.aws/config中指定的 profile，适合在 CI 或多人共用机器上避免依赖环境变量。

核心调用模式：client.send(new Command(input))

AWS SDK v3 的客户端统一采用"客户端 + 显式命令"的调用方式，每条 API 都是一个独立的 Command 类：

import { ACMClient, DescribeCertificateCommand, } from "@aws-sdk/client-acm"; const acm = new ACMClient({ region: "us-east-1" }); const response = await acm.send( new DescribeCertificateCommand({ CertificateArn: "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012", }), ); console.log(response.Certificate?.Status);

新代码建议采用ACMClient加显式命令导入的组合，命令按需导入，便于打包器做 tree-shaking。

常见工作流

1. 申请公网证书并做 DNS 验证

RequestCertificateCommand只返回证书 ARN，不会返回 DNS 验证记录。需要再调用DescribeCertificateCommand，从Certificate.DomainValidationOptions[].ResourceRecord中读出要发布的 DNS 记录：

import { ACMClient, DescribeCertificateCommand, RequestCertificateCommand, } from "@aws-sdk/client-acm"; const acm = new ACMClient({ region: "us-east-1" }); const request = await acm.send( new RequestCertificateCommand({ DomainName: "api.example.com", SubjectAlternativeNames: ["www.example.com"], ValidationMethod: "DNS", IdempotencyToken: "api-example-com", Tags: [{ Key: "service", Value: "edge-api" }], }), ); const certificateArn = request.CertificateArn; if (!certificateArn) { throw new Error("RequestCertificate did not return a certificate ARN"); } const details = await acm.send( new DescribeCertificateCommand({ CertificateArn: certificateArn, }), ); for (const option of details.Certificate?.DomainValidationOptions ?? []) { const record = option.ResourceRecord; if (record) { console.log({ domain: option.DomainName, name: record.Name, type: record.Type, value: record.Value, }); } }

要点说明：

• ValidationMethod: "DNS"表示通过 DNS TXT 记录完成域名所有权验证；若改用邮件验证，ACM 还提供ResendValidationEmailCommand用于重试邮件验证流程。
• IdempotencyToken保证重复提交同一申请时的幂等性，适合脚本化申请证书。
• 每个 SAN（SubjectAlternativeNames中的域名）都会产生一条独立的验证记录，循环打印时可以逐条发布。

2. 轮询等待验证完成

SDK 内置的 ACM waiter 会轮询DescribeCertificate，直到所有域名的验证状态都变为SUCCESS；如果证书状态变成FAILED，waiter 会抛错：

import { ACMClient, waitUntilCertificateValidated, } from "@aws-sdk/client-acm"; const acm = new ACMClient({ region: "us-east-1" }); await waitUntilCertificateValidated( { client: acm, maxWaitTime: 30 * 60 }, { CertificateArn: "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012", }, );

maxWaitTime单位为秒，示例中设置为 30 分钟，覆盖 DNS 记录生效与 ACM 完成验证所需的窗口。

3. 用分页器列举证书

ACM 暴露一个ListCertificates分页器。当证书数量超过单页返回上限时，用paginateListCertificates逐页扫描：

import { ACMClient, paginateListCertificates, } from "@aws-sdk/client-acm"; const acm = new ACMClient({ region: "us-east-1" }); for await (const page of paginateListCertificates( { client: acm }, { CertificateStatuses: ["ISSUED", "PENDING_VALIDATION"], }, )) { for (const cert of page.CertificateSummaryList ?? []) { console.log(cert.CertificateArn, cert.DomainName, cert.Status); } }

CertificateStatuses允许只关注特定状态的证书（如ISSUED、PENDING_VALIDATION），减少无意义的翻页。

4. 读取已签发证书的主体与证书链

GetCertificateCommand返回证书 PEM 与证书链 PEM，不返回私钥：

import { ACMClient, GetCertificateCommand, } from "@aws-sdk/client-acm"; const acm = new ACMClient({ region: "us-east-1" }); const response = await acm.send( new GetCertificateCommand({ CertificateArn: "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012", }), ); console.log(response.Certificate); console.log(response.CertificateChain);

这两个字段可以直接拼进需要证书材料的配置（例如配合 client-cloudfront 一类文档完成分发配置）。

5. 导入已有 PEM 证书

当你已经持有证书 PEM 与私钥 PEM 时，使用ImportCertificateCommand。在 Node.js 中，readFileSync()返回Buffer，可直接作为 ACM blob 输入：

import { readFileSync } from "node:fs"; import { ACMClient, ImportCertificateCommand, } from "@aws-sdk/client-acm"; const acm = new ACMClient({ region: "us-east-1" }); const response = await acm.send( new ImportCertificateCommand({ Certificate: readFileSync("./tls/certificate.pem"), PrivateKey: readFileSync("./tls/private-key.pem"), CertificateChain: readFileSync("./tls/certificate-chain.pem"), Tags: [{ Key: "environment", Value: "production" }], }), ); console.log(response.CertificateArn);

安全红线：私钥只保留在可信基础设施上，绝不能提交到源代码库。

6. 打标签与移除标签

import { ACMClient, AddTagsToCertificateCommand, RemoveTagsFromCertificateCommand, } from "@aws-sdk/client-acm"; const acm = new ACMClient({ region: "us-east-1" }); const certificateArn = "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012"; await acm.send( new AddTagsToCertificateCommand({ CertificateArn: certificateArn, Tags: [ { Key: "service", Value: "payments" }, { Key: "owner", Value: "platform" }, ], }), ); await acm.send( new RemoveTagsFromCertificateCommand({ CertificateArn: certificateArn, Tags: [{ Key: "owner" }], }), );

标签对成本分摊和批量运维（例如按owner标签找出某团队的证书）很有用，建议在申请证书时（RequestCertificateCommand的Tags）就打好标签。

7. 删除不再使用的证书

import { ACMClient, DeleteCertificateCommand, } from "@aws-sdk/client-acm"; const acm = new ACMClient({ region: "us-east-1" }); await acm.send( new DeleteCertificateCommand({ CertificateArn: "arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012", }), );

如果 AWS 报告证书仍在使用中，先把它从依赖服务（ALB、CloudFront 等）上解绑，再重试删除。

常见陷阱（Common Pitfalls）

以下是原文档总结的高频踩坑点，排查问题时优先对照：

• RequestCertificateCommand的响应中不包含DNS 验证记录。必须调用DescribeCertificateCommand并读取Certificate.DomainValidationOptions[].ResourceRecord。
• ACM 是区域化的：在错误的区域执行列举或描述，找不到你期望的 ARN。
• GetCertificateCommand返回证书主体和证书链，不返回私钥。
• ImportCertificateCommand要求证书 PEM 字节和私钥字节。在 Node.js 中传入Buffer值，例如readFileSync()的结果。
• DeleteCertificateCommand在证书仍被其他服务引用时会失败（ResourceInUseException）。
• 如果使用ExportCertificateCommand，Passphrase需要按字节传递，且只对开启了导出的证书生效。

配套 SDK 包

围绕证书申请后的自动化，常用的相关包包括：

• @aws-sdk/credential-providers：显式 profile、SSO、Cognito 与 assume-role 凭证流程。
• @aws-sdk/client-route-53：如果你用 Route 53 管理 DNS，可自动创建 DNS 验证记录。
• @aws-sdk/client-elastic-load-balancing-v2：把 ACM 证书挂到 ALB / NLB 监听器。
• @aws-sdk/client-cloudfront：在 CloudFront 分发中引用 ACM 证书。

版本说明与适用前提

• 本文对应@aws-sdk/client-acm版本3.1007.0（即 frontmatter 中metadata.versions的取值，与 Content Guide 中"versions字段始终指 npm 上的包版本"的约定一致）。
• 当前 ACM API 模型暴露一个ListCertificates分页器和一个证书验证 waiter，对应 SDK 中的paginateListCertificates与waitUntilCertificateValidated。
• 文中所有代码以 Node.js + ESMimport为前提；凭证来自环境变量、共享配置文件、实例元数据或 IAM Identity Center 之一。

如果你发现文档遗漏了某个操作细节（例如某区域的行为差异、特殊错误码），可以直接用本地注解沉淀下来，供后续会话复用：

chub annotate aws/acm "在 us-east-1 之外区域，CloudFront 证书必须创建在 us-east-1" chub feedback aws/acm up "DNS 验证工作流示例完整可运行"

注解的语义与信任边界见 Feedback and Annotations，命令的完整参数见 CLI Reference。