# Amazon CloudFormation 语言服务器
<a name="ide-extension"></a>

Amazon CloudFormation 语言服务器提供加速撰写基础设施即代码（IaC）和安全、自信地部署 Amazon 资源的功能。它遵循[语言服务器协议](https://microsoft.github.io/language-server-protocol/)（LSP），以提供有关悬停、自动补全、通过静态验证进行的诊断、转至定义以及代码操作的相关文档。除了这些传统语言服务器功能外，该服务器还添加了在线功能，可用于通过 CloudFormation 浏览和部署 Amazon 资源。这包括使用更改集来验证和部署模板的能力；查看堆栈差异、事件、资源和输出；列出堆栈并按类型浏览资源；以及直接将实时资源状态插入到 CloudFormation 模板中。

**Topics**
+ [IDE 与 Amazon CloudFormation 语言服务器集成](#ide-extension-supported-ides)
+ [开始使用](#ide-extension-getting-started)
+ [在 IDE 中初始化 CloudFormation 项目（仅限 VS Code）](#ide-extension-initialize-project)
+ [开源](#ide-extension-open-source)
+ [需要帮助？](#ide-extension-need-help)

## IDE 与 Amazon CloudFormation 语言服务器集成
<a name="ide-extension-supported-ides"></a>

Amazon 通过 Amazon 工具包为以下 IDE 提供与 CloudFormation 语言服务器的现成集成：
+ [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=AmazonWebServices.aws-toolkit-vscode)
+ [JetBrains IDE](https://plugins.jetbrains.com/plugin/11349-aws-toolkit)（版本 2025.3 或更高版本），包括 IntelliJ IDEA、WebStorm 和 PyCharm

以下 IDE 还支持 CloudFormation 语言服务器：
+ [Kiro](https://kiro.dev/downloads/)
+ [Cursor](https://cursor.com/)
+ 大多数 VS Code 分叉和分配

CloudFormation 语言服务器遵守[语言服务器协议](https://microsoft.github.io/language-server-protocol/)（LSP），因此其他集成是可配置的。有关将语言服务器与其他编辑器集成的说明，请参阅[安装指南](https://github.com/aws-cloudformation/cloudformation-languageserver/blob/main/INSTALLATION.md)。

## 开始使用
<a name="ide-extension-getting-started"></a>

**Topics**
+ [先决条件](#ide-extension-prerequisites)
+ [第 1 步：安装或升级 Amazon 工具包](#ide-extension-install-toolkit)
+ [第 2 步：在 Amazon 工具包中访问 CloudFormation](#ide-extension-access-toolkit-panel)
+ [第 3 步：验证、测试和优化您的模板](#ide-extension-validate-test-refine)
+ [第 4 步：浏览模板](#ide-extension-navigate-template)
+ [第 5 步：验证和部署](#ide-extension-validate-deploy)

### 先决条件
<a name="ide-extension-prerequisites"></a>

在您开始之前，请确保：
+ 您正在支持的操作系统（macOS、Windows 或 Linux）上使用支持的 IDE。
+ 您已为自己的 IDE 安装或升级到最新版本的 Amazon 工具包。

Amazon CloudFormation 语言服务器中的某些功能需要有效的 Amazon Web Services 账户和已配置的凭证。您必须使用有效的凭证通过 Amazon 工具包登录您的 Amazon Web Services 账户。

### 第 1 步：安装或升级 Amazon 工具包
<a name="ide-extension-install-toolkit"></a>

从 IDE 的扩展程序或插件管理器中安装或更新到最新版本的 Amazon 工具包，然后重新启动 IDE。

安装后，Amazon 工具包会自动启用 CloudFormation IDE 支持。首次安装或升级带有 Amazon CloudFormation 语言服务器的 Amazon 工具包时，系统会提示您授予 Amazon 收集匿名使用数据的权限。这些数据有助于 Amazon 改进 CloudFormation 语言服务器并增强撰写体验。不会收集任何敏感信息，Amazon 也不会记录或存储模板内容、资源配置或任何可识别身份的客户数据。您可以随时从 IDE 设置中更改遥测首选项。重新启动 IDE 以使更改生效。所收集的使用数据仅涵盖功能交互和性能指标。这些见解有助于 Amazon 识别并确定需要改进方面优先顺序，例如加快验证速度、增强自动补全功能以及改进错误诊断机制。

### 第 2 步：在 Amazon 工具包中访问 CloudFormation
<a name="ide-extension-access-toolkit-panel"></a>

安装 Amazon 工具包后，在 IDE 中打开 CloudFormation 面板。在 VS Code 中，从活动栏打开 Amazon 工具包面板，然后选择 **CLOUDFORMATION**。在 JetBrains IDE 中，从侧栏打开 **Amazon 工具包**工具窗口，然后选择 **CloudFormation** 选项卡。

CloudFormation 面板包含以下部分：
+ **区域**：显示当前 Amazon Web Services 区域。在 VS Code 中，您可以通过选择区域名称或使用命令面板中的 **Amazon CloudFormation: Select Region** 命令来更改区域。在 JetBrains IDE 中，区域是通过 Amazon 工具包连接设置配置的。
+ **堆栈**：显示您的账户中 CloudFormation 堆栈的分页列表。展开堆栈，以便查看其**更改集**节点，其中列出了与该堆栈关联的更改集。使用“查看堆栈详细信息”操作打开堆栈详细信息视图，该视图显示堆栈概述、事件、输出和资源。
+ **资源**：添加资源类型后，面板将显示您账户中该类型的 Amazon 资源。您可以查看、刷新、复制或将它们导入到您的模板中。

在 JetBrains IDE 中，树上方的工具栏可快速访问常见操作，包括**验证和部署**、**重新运行、验证和部署**、**添加资源类型**和**刷新**。也可以通过右键单击树节点上的上下文菜单来执行操作。

### 第 3 步：验证、测试和优化您的模板
<a name="ide-extension-validate-test-refine"></a>

在您编写 CloudFormation 模板时，IDE 会提供智能的撰写辅助功能，以帮助您更快速地创建准确且符合规范的基础设施。CloudFormation 语言服务器在后台运行，并提供以下撰写功能：
+ 代码完成：根据 CloudFormation 架构来建议资源类型、参数和属性。
+ 添加现有的 Amazon 资源：允许您将现有资源从您的 Amazon Web Services 账户导入您的模板。IDE 使用 [Amazon 云端控制 API（CCAPI）](https://docs.amazonaws.cn/cloudcontrolapi/latest/userguide/what-is-cloudcontrolapi.html)检索资源的实时配置和属性，从而帮助您克隆或重复使用模板中的现有基础设施。
+ 提取到参数：当光标位于模板中的字面值（例如，类似 `t2.micro` 的字符串）上时，IDE 会提供重构操作，用于将该值提取到 `Parameters` 部分中，并将字面值替换为指向新参数的 `!Ref`。如果在多个位置出现相同的字面值，则可以选择一次提取所有出现的字面值。

#### 要向模板添加资源
<a name="ide-extension-add-resources-to-template"></a>
+ **添加资源类型**：在 Amazon 工具包 CloudFormation 面板的**资源**下，添加要浏览的资源类型。在 VS Code 中，单击**添加 \$1** 图标或使用命令面板中的 **Amazon CloudFormation: Add Resource Types** 命令。在 JetBrains 中，单击工具栏中的**添加资源类型**按钮或右键单击**资源**节点。
+ **搜索资源类型**：在搜索对话框中，键入要添加的 Amazon 资源类型。示例：
  + `AWS::S3::Bucket`
  + `AWS::Lambda::Function`
+ **浏览资源**：在**资源**部分，将显示您的账户中检测到的 Amazon 资源的分页列表。如果您拥有大量资源，则只会显示第一页。使用导航控件来浏览其他页面并查看所有可用资源。
+ 选择要包含在您的模板中的资源。
+ 您可以通过两种方式将资源插入到您的模板中，具体方式取决于您的目标：
  + **克隆现有资源**：使用现有 Amazon 资源的实时配置和属性在模板中创建新资源。
  + **导入现有资源**：通过将资源的实时状态添加到模板中，将其插入到您的堆栈中。

**提示**
+ 您可以随时刷新**资源**部分，查看您的账户或区域中可用的最新资源列表。
+ 如果您正在导入资源，请不要在同一个账户中添加属于现有 CloudFormation 堆栈的已存在资源。
+ 要确认资源是否已由 CloudFormation 管理，请使用资源旁边的信息操作。在 VS Code 中，单击 **i** 图标。在 JetBrains IDE 中，右键单击资源并选择**获取堆栈管理信息**。

##### 添加相关资源
<a name="ide-extension-add-related-resources"></a>

在 VS Code 中，您可以使用命令 **Amazon CloudFormation: Add Related Resources by Type** 将相关资源添加到所选资源。一旦您从模板中已定义的资源类型中选择了一个资源类型，IDE 就会显示与该类型通常相关联或依赖于该类型的资源列表。例如，如果您选择 `AWS::EC2::Instance`，IDE 可能会建议添加相关资源，例如 `AWS::EC2::SecurityGroup` 或 `AWS::EC2::Subnet`。此功能可帮助您快速构建相互连接的基础设施组件，而无需手动搜索兼容的资源类型。此功能目前在 JetBrains IDE 中不受支持。

#### 静态验证
<a name="ide-extension-static-validation"></a>

CloudFormation 语言服务器提供了由 [Amazon CloudFormation Linter (cfn-lint)](https://github.com/aws-cloudformation/cfn-lint) 和 [Amazon CloudFormation Guard](https://docs.amazonaws.cn/cfn-guard/latest/ug/what-is-guard.html) 提供支持的内置静态验证。在您撰写模板的过程中，这些验证会在后台进行，帮助您在部署前发现语法错误、合规性缺口以及最佳实践方面的问题。

**静态验证概述**

您将在 IDE 中看到两种类型的实时静态验证：
+ CloudFormation Linter（`cfn-lint`）：根据 CloudFormation 资源规范和架构规则验证您的模板。
+ Guard（`cfn-guard`）：根据合规性规则和组织策略包验证您的模板。

##### CloudFormation Linter（cfn-lint）
<a name="ide-extension-cfn-linter-details"></a>

CloudFormation Linter 已集成到 IDE 中，以在您键入时自动检查模板的语法和结构。
+ **架构验证**：检测语法和架构错误，以确保您的模板符合 CloudFormation 资源架构。
+ **错误突出显示**：在出现问题时，会显示内联标记，这些标记代表部署拦截器或警告信息。
+ **悬停获取帮助**：将鼠标悬停在错误上方时，IDE 会显示与该问题相关的诊断消息。如果有快速修复方案可用，也会提供。

##### Guard 集成
<a name="ide-extension-cfn-guard-integration"></a>

Guard 会根据定义合规性和安全策略的规则集来验证您的模板。IDE 通过 CloudFormation 语言服务器实时运行 Guard 验证，以在您撰写模板时为您提供即时反馈。
+ **默认规则包**：IDE 包含了一套预先注册好的 Guard 规则，这些规则侧重于资源安全和配置维护方面的基本最佳实践。要了解更多信息，请参见 [guard 规则注册表](https://github.com/aws-cloudformation/aws-guard-rules-registry)。
+ **添加规则包**：要添加或修改规则集，请打开“IDE 设置”，导航到“Guard 配置”部分，然后选择或上传其他 Guard 规则包。

**提示**：了解诊断指示器
+ 蓝色指示器：最佳实践提示或优化建议。
+ 黄色指示器：关于非拦截问题的警告（例如，缺少标签或参数）。
+ 红色指示器：部署拦截器，例如无效的属性名称、缺少必填字段或架构不匹配。

### 第 4 步：浏览模板
<a name="ide-extension-navigate-template"></a>

IDE 提供 CloudFormation 模板的结构化分层视图，该视图分为 `Parameters`、`Resources`、`Outputs` 和 `Mappings` 等部分，显示了每种资源类型和逻辑 ID。这使得在大型模板中能够轻松快速地定位并导航到特定的资源或参数。在 VS Code 中，**探索器**侧栏中的**大纲**面板显示此结构。在 JetBrains IDE 中，打开**结构**工具窗口，查看当前打开的文件的模板结构。

您可以将**转到定义**用于 `GetAtt` 和 `Ref` 之类的内置函数，从而使您可以直接跳转到模板中引用的资源或参数。这可以帮助您跟踪依赖项、了解资源关系并更高效地进行编辑。

### 第 5 步：验证和部署
<a name="ide-extension-validate-deploy"></a>

当您准备好部署 CloudFormation 模板时，请使用“验证和部署”功能来创建更改集。IDE 会验证您的模板，如果未发现任何拦截错误，则会继续创建[偏差感知更改集](drift-aware-change-sets.md)。然后 IDE 会显示差异视图，以便您可以在执行更改集之前查看所有提议的更改。

在 VS Code 中，打开命令面板并运行 **Amazon CloudFormation: Validate and Deploy**。命令面板将引导您逐步选择模板、堆栈名称、参数、功能和其他部署选项。在 JetBrains IDE 中，使用**验证和部署**工具栏按钮，在编辑器中右键单击模板文件或右键单击树中的堆栈。JetBrains 会显示一个向导对话框，您可以在其中配置所有部署选项，包括模板选择、堆栈名称、参数、功能、标签和高级选项。

#### 验证的工作原理
<a name="ide-extension-how-validation-works"></a>

IDE 会在[部署前自动执行验证检查](validate-stack-deployments.md)，并根据常见的故障原因对模板进行验证，包括：
+ 无效的属性语法或架构不匹配：这些问题通常在撰写过程中被 `cfn-lint` 检测出来，但如果您在未解决这些问题的情况下继续进行部署，那么在创建或更新堆栈时，CloudFormation 的部署时验证也会显示出同样的错误。
+ 资源名称与您账户中的现有资源冲突。
+ 特定于服务的约束，例如 S3 存储桶名称冲突或缺少加密。

如果验证检测到错误，IDE 会直接在模板中突出显示问题，并在诊断面板中列出错误。每个问题都包括导致故障的特定属性或资源，并附上相应的解决建议。如果没有阻止错误，则可以继续进入部署阶段。

如果发现警告（非阻止问题），会出现一个对话框，让您可以选择继续进行部署操作，或者取消操作并进行修正。

IDE 将打开一个[偏差感知更改集](drift-aware-change-sets.md)，其中显示当前模板与已部署堆栈配置之间的任何差异。这使您能够在执行之前查看、确认或取消更改集。取消部署会删除更改集。

偏差感知更改集能够增强 CloudFormation 的部署流程，使您能够安全地处理堆栈的偏差问题。当您的资源的实际状态与 CloudFormation 模板中所定义的内容不一致时，就会出现堆栈偏差，这种情况通常因通过 Amazon Web Services 管理控制台、CLI 或 SDK 进行的手动更改导致。CloudFormation [偏差感知更改集](drift-aware-change-sets.md)将处理后的堆栈配置与实时资源状态进行比较，IDE 会显示这些差异，这样您就可以在部署之前使资源恢复合规性。

#### 查看堆栈事件
<a name="ide-extension-view-stack-events"></a>

部署开始后，您可以从 CloudFormation 面板实时监控进度。在**堆栈事件**下，您将看到部署期间执行的操作列表。每个事件都包含详细信息，例如：
+ **时间戳**：事件发生的时间
+ **资源**：正在创建、更新或删除的特定 Amazon 资源
+ **状态**：操作的当前状态（例如 `CREATE_IN_PROGRESS`、`UPDATE_COMPLETE` 或 `ROLLBACK_IN_PROGRESS`）
+ **原因**：其他背景信息或错误消息（如果适用）

您也可以通过此面板查看堆栈的**资源**和**输出**。**堆栈事件**视图有助于您跟踪部署进度、识别潜在问题，并确认您的堆栈是否已成功完成部署。

## 在 IDE 中初始化 CloudFormation 项目（仅限 VS Code）
<a name="ide-extension-initialize-project"></a>

在 IDE 中初始化 CloudFormation 项目可以帮助您使用正确的文件夹、环境配置和 Amazon 凭证设置结构化工作区，以便您可以可靠地验证和部署模板。您可以直接从 IDE 来初始化一个新的 CloudFormation 项目，从而创建此建议设置。此功能目前仅在 VS Code 中可用，在 JetBrains IDE 中不受支持。

**要初始化 CloudFormation 项目，请执行以下操作：**
+ **打开命令面板**
  + 从 VS Code，打开命令面板（macOS 上的 `Ctrl+Shift+P` 或 `Cmd+Shift+P`）。
  + 选择 **Amazon CloudFormation：CFN Init：初始化项目**。
+ **选择项目目录**
  + 默认情况下，IDE 将使用您当前的工作目录。
  + 您可以将此路径更改为您希望存储 CloudFormation 模板所在的任何文件夹。
+ **选择您的 Amazon 凭证配置文件**
  + 系统将提示您选择 Amazon 凭证配置文件。所选配置文件用于环境检测、验证和部署。
+ **设置环境**
  + 系统将提示您创建或选择环境。
  + 环境定义了您的模板在何处以及以何种方式进行部署或验证（例如，开发环境、测试环境或生产环境）。您可以使用 **Amazon CloudFormation：CFN Init：添加环境**来选择或更改您的环境。
  + 您可以使用 **Amazon CloudFormation: CFN Init: Remove Environment** 移除您选择的环境。
+ **（可选）导入参数文件**
  + 如果您已经有现有的参数文件，那么该 IDE 会在初始化时允许您导入这些文件。
  + IDE 会自动检测兼容的文件，并将它们链接到您的项目中，以便在模板验证和部署过程中使用。
+ **命名并最终确定项目**
  + 提供项目名称，例如 beta-environment，然后完成设置。
  + IDE 将为您创建初始项目结构和配置文件。

您可以直接从 IDE 中进行验证、预览部署操作，或者在不同环境中进行切换。

## 开源
<a name="ide-extension-open-source"></a>

Amazon CloudFormation 语言服务器根据 Apache-2.0 许可开源，让客户能够全面了解模板诊断、架构验证以及静态分析是如何进行的。对于在采用工具之前需要来源级可见性的客户来说，这减少了安全性和合规性方面的摩擦。

该代码库已在 GitHub 上公开发布：[https://github.com/aws-cloudformation/cloudformation-languageserver/](https://github.com/aws-cloudformation/cloudformation-languageserver/)。

## 需要帮助？
<a name="ide-extension-need-help"></a>

在 Amazon Web Services re:Post 上试用 [CloudFormation 社区](https://repost.aws/tags/TAm3R3LNU3RfSX9L23YIpo3w)。