aws-sst-development

面向 AWS 的 SST v4

SST v4（“Ion”引擎）是一个由 Pulumi 支持的 IaC 框架：你用 TypeScript 描述 AWS 资源，SST/Pulumi 会将其协调到你的账户中。它提供高级 sst.aws.* 组件（Function、Bucket、Dynamo、Cron、 Service 等），这些组件会展开为许多底层资源；对于长尾需求，还可以直接使用 任意原始 Pulumi aws.* 资源。这项技能总结了在 AWS 上编写、关联、测试、部署和排查 SST 堆栈的生产验证方法——这些方法来自真实的多堆栈项目，每一条经验都曾通过生产事故换来。

SST 和 Pulumi 均为第三方产品——不确定组件选项时，请通过 Context7 验证当前语法 （对 sst 或 pulumi-aws 执行 resolve-library-id → query-docs）。验证 AWS 侧事实（服务限制、 模型 ID、IAM 操作名称、区域可用性）时，请使用 AWS 文档 MCP，切勿凭记忆判断。这里介绍的是 如何操作；文档说明的是是什么。

调用时

判断当前属于哪种情况，然后跳转到相应参考文档：

情况	前往
新建项目，或向现有 SST 应用添加资源／模块	编写 → references/authoring.md
将一个模块的输出接入另一个模块（关联、SSM、IAM 范围）	编写 → references/authoring.md § Sharing
为基础设施编写测试，避免更改悄然造成问题	测试 → references/testing.md
执行部署，或部署刚刚失败	部署／运维 → references/deploy-and-troubleshoot.md
在 Pulumi 类型之间迁移资源，或重命名物理名称	部署／运维 → references/deploy-and-troubleshoot.md § Migrations

编辑前务必阅读相关参考文档——其中说明了每条规则背后的原因，这比规则本身更重要。

了解项目：动手前先阅读仓库

SST 项目通常遵循惯例，但彼此并不完全相同。编辑前，先快速梳理项目结构，确保你的更改符合项目既有风格，而不是与之冲突：

1. sst.config.ts — 应用名称、home、提供商／区域、defaultTags、 任意全局 $transform（Node 运行时固定、打包修正），以及 run() 导入 infra/ 模块的顺序。 导入顺序就是依赖顺序；请遵循它。
2. infra/ — 每个领域各有一个文件（存储、函数、API、可观测性等）。 资源在此声明。检查是否有 infra/CLAUDE.md——这些项目会在那里记录 IaC 专属规则，这是最值得优先阅读的文件。
3. infra/tests/ — 在源码层通过 Vitest 断言固定资源不变量。如果这些测试存在，你的更改必须确保它们通过，而且很可能需要新增断言。
4. package.json / .nvmrc — 包管理器（npm 或 pnpm）、Node 版本，以及实际安装的 sst/pulumi 版本。

运行 npx sst version，确认你使用的是 v4/Ion（具有 $config + .sst/platform/ 特征）。v2/v3（“SST Classic”，基于 CDK）是不同的框架——这里的模式不适用于它们。

约定，以及哪些通用、哪些可调整

本技能所依据的项目采用了一套经过斟酌的项目风格。其中一些属于通用约定（适用于任何 SST v4 + AWS 项目——应在所有项目中遵循）；另一些属于项目特定约定（这些项目选择的合理默认做法——为保持一致性可以采用，但也要认识到其他项目可能有所不同）。

通用约定——这些原则适用于任何 SST v4 + AWS 项目：

• 在一个位置有意识地控制 Node 运行时。 不要任由已安装的 SST 使用其默认值。惯用做法是在 run() 中设置一个全局的 $transform(sst.aws.Function, (args) => { args.runtime ??= "nodejs24.x" })——这里使用 ??= 才正确（transform 会在组件应用自身默认值之前运行，因此只有用户未设置运行时的时候才会填充）。 较新的 SST 已经默认使用当前版本的 Node 运行时，因此请先检查已安装版本的默认值（Context7）；之后添加 transform，是为了确保版本无关性，避免未来降级 SST 时悄然变更整个服务集。参见 references/authoring.md。
• 绝不要将 Pulumi Output<T> 插入普通 JS 模板字面量。 使用 $interpolate（或 pulumi.interpolate）。直接写顶层字符串 `${bucket.arn}/*` 会将 Output 转换为 [Output<T>] 占位符，生成无效 ARN，直到部署时才会失败（类型检查会通过，sst dev 也能正常运行）。正确写法是 $interpolate​`${bucket.arn}/*`。这曾导致生产环境部署中断。参见 references/authoring.md § Outputs。
• 在 Pulumi 类型之间迁移资源时，默认拆成两个 PR——Pulumi 会先创建再销毁，因此对于名称必须唯一的 AWS 资源（存储桶、IAM 角色、网关），旧资源仍占用该名称，导致创建失败并返回 ConflictException。保守的默认做法是按顺序进行两次部署（先拆除，再重新创建）；在某些情况下，aliases: / pulumi import / 状态调整可以衔接资源身份，但必须先审查计划。参见 references/deploy-and-troubleshoot.md § Migrations。
• 优先使用类型化的 sst.aws.* / aws.* 资源，而不是 aws.cloudcontrol.Resource 这一逃生方案。 CloudControl 的输出以字符串为类型，oneOf 字段也无法顺利进行补丁更新。仅当尚无类型化资源时才使用它，并在类型化资源推出后迁移出去。

项目特定默认值——为保持一致性而采用，但请按仓库逐一确认：

• 区域 ap-northeast-1、home: "aws"，以及包含 Project / Stage / ManagedBy: "sst" 的 defaultTags。
• 按 Stage 控制生命周期：使用 removal: stage === "prod" ? "retain" : "remove" 和 protect: stage === "prod"，使生产资源在堆栈拆除后保留，并清理非生产预览环境。
• 将 SSM Parameter Store 作为图外契约，使用 /{app}/{stage}/{domain}/... 前缀——供不在 Pulumi 图中的使用方使用（CI 脚本、同级应用、运维人员）。对于同一应用中的 Lambda，优先使用 SST link:（它会建立真实的依赖边并授予 IAM 权限）；不要通过 SSM 实现同一应用内的共享。参见 references/authoring.md § Sharing。
• 在 run() 中延迟执行 await import("./infra/<module>")，以便让 sst dev 的热重载保持轻量。（测试时，模块导出仍会运行其顶层的 new sst.aws.*，除非将其包装在工厂函数中——有关如何测试基础设施，请参见 references/testing.md。）
• 在每个基础设施模块上编写源代码级 Vitest 测试——这是一种轻量的项目内回归防护模式，可断言源文本（资源名称、索引形状、IAM 作用域）。这是有意的选择，并非 SST 的限制：当模块包含实际逻辑时，Pulumi 确实支持使用运行时模拟（@pulumi/pulumi/runtime）进行行为图测试。源代码断言不能替代预览部署和冒烟测试。参见 references/testing.md。
• 设置可观测性门槛：每个新增的 Lambda / 队列 / 定时计划，在合并前都必须配置告警和结构化日志。是否强制执行取决于项目，但这是成本很低的保障措施。参见 references/deploy-and-troubleshoot.md § Observability。

引入约定时，请说明它属于哪一类（“这是通用做法”还是“遵循此仓库的项目内风格”），以便用户有意地调整项目特定的约定。

工作节奏

1. 熟悉项目（见上文）——梳理配置、模块、测试和工具。
2. 验证语法：遇到不明确之处时，使用 Context7 / AWS 文档 MCP。 不要猜测组件的选项名称。
3. 编写资源/模块时遵循 references/authoring.md。保持与相邻文件相当的注释密度和命名风格——这些项目会详细注释 原因；在注释密集的文件中只写一句简略注释，会显得像是退步。
4. 测试——添加或更新源代码级断言（references/testing.md），并运行 npx vitest（或仓库的 test 脚本）。部署前运行 npx sst diff 和/或 tsc --noEmit，以发现类型和计划错误。
5. 按照 references/deploy-and-troubleshoot.md 部署/运维。运行任何 sst deploy 前，使用 aws sts get-caller-identity 确认目标账户。
6. 清理所有导出的状态文件——其中包含账户 ID 和 ARN，不得遗留在 /tmp 或聊天记录中。

做得好的标准

• 改动是满足需求所需的最小差异，位于正确的 infra/ 模块中，并按依赖顺序接入 run()。
• 每个 Lambda 都通过全局转换获得正确的运行时（除非有意采用不同设置，例如 Python 函数，否则不要手动设置 runtime）。
• 跨资源引用使用 link:（图内引用）和/或 $interpolate 限定范围的 IAM；其他工具要使用的输出会发布到 stage 前缀下的 SSM。
• 新增的基础设施有配套的源代码级测试，现有测试套件也全部通过。
• 通过文档 MCP 确认 AWS 侧信息，并通过 Context7 确认 SST/Pulumi 语法，而不是依赖记忆。
• 任何不可逆操作（部署、sst remove、资源类型迁移）都已向用户说明，并注明目标账户；迁移已规划为两个 PR，而不是一个。