企业官网建设流程全解析

• AI 技能
• AI 插件
• 人工智能

导读

本文围绕 agentic-awesome-skills 仓库中的aws-sst-development技能（SKILL.md，同版副本见 plugins/agentic-awesome-skills/skills/aws-sst-development/SKILL.md）展开，系统讲解 SST v4（"Ion" 引擎）这一 Pulumi 驱动的基础设施即代码（IaC）框架的实战方法论：如何定向阅读 SST 项目、如何区分通用约定与项目特定约定、如何编写/链接/测试/部署并排障sst.config.ts与infra/模块，以及避免生产事故的关键红线。读完本文，你将掌握一套从"读仓库"到"改代码"再到"安全部署"的完整工作节奏，并理解每条规则背后的技术原理（$transform、$interpolate、Pulumi 的 create-before-destroy 语义等），可直接迁移到自己的 SST v4 + AWS 项目。

说明：本技能在仓库中被登记为risk: critical、source_type: community、MIT 许可的开源技能，其目录与索引元数据可在 data/catalog.json 与 data/skills_index.json 中检索到。

一、技能定位：SST v4（Ion）是什么，什么时候该用它

1.1 SST v4 的核心模型

SST v4（"Ion" 引擎）是一个Pulumi 驱动的 IaC 框架：你用 TypeScript 描述 AWS 资源，由 SST/Pulumi 负责将声明对账（reconcile）到你的 AWS 账户中。它提供了两类资源表达方式：

• 高层组件sst.aws.*：如Function、Bucket、Dynamo、Cron、Service、Router等，一个组件会展开成多个底层 AWS 资源，屏蔽大量样板；
• 原始 Pulumi 资源aws.*：作为"逃生舱"（escape hatch），当高层组件覆盖不到的长尾需求出现时，可以编写任意原始 Pulumi 资源。

⚠️ 判断版本：运行npx sst version确认你处于 v4/Ion（识别特征是$config语法与.sst/platform/目录）。v2/v3（"SST Classic"，基于 CDK）是完全不同的框架，本文所有模式均不适用。

1.2 When to Use：何时调用本技能

根据 SKILL.md 的定义，当你处于以下场景时应使用该技能：

• 编写或编辑sst.config.ts；
• 构建infra/模块（sst.aws.Function/Bucket/Dynamo/Cron/Service/Router、sst.Secret、sst.Linkable、原始aws.*Pulumi 资源）；
• 编写资源链接（wiring resource links）；
• 编写基础设施测试、执行部署、处理部署失败、迁移资源类型或重命名物理名称。

1.3 外部事实的验证纪律

SKILL.md 特别强调：SST 与 Pulumi 均为第三方项目，语法细节应以 Context7（resolve-library-id→query-docs，对象为sst或pulumi-aws）为准；AWS 侧事实（服务配额、模型 ID、IAM action 名称、区域可用性）应以 AWS 文档为准，绝不能凭记忆。技能给出的模式是how（怎么做），官方文档是what（是什么）。

二、模式选择：被调用时的快速路由

SKILL.md 提供了一个"按情境跳转"的决策表，这是使用该技能的第一入口。原文档将其路由到references/authoring.md、references/testing.md、references/deploy-and-troubleshoot.md三个参考章节；在本文中，我们把对应章节内容直接展开，供读者对照：

注意：每次编辑前都应先读对应参考内容——它们承载着每条规则背后的why（为什么），这比规则本身更重要。

三、Orient：动手前先读懂仓库

SST 项目"约定俗成但不完全相同"。SKILL.md 建议在编辑前按以下顺序建立项目地图，让你的改动匹配"房子风格"（house style）而不是与之对抗：

1. sst.config.ts：应用名、home、provider/region、defaultTags、任何全局$transform（Node 运行时固定、bundle 修复），以及run()中importinfra/模块的顺序。导入顺序就是依赖顺序，务必尊重它；
2. infra/：每个领域一个文件（storage、functions、api、observability……），资源在这里声明。检查是否存在infra/CLAUDE.md——这些项目会把 IaC 专属规则放在那里，它是首先要读的、价值最高的单个文件；
3. infra/tests/：源码级 Vitest 断言，用于钉住资源不变量。若存在，你的改动必须让它们保持绿色，且很可能需要新增断言；
4. package.json/.nvmrc：包管理器（npm 还是 pnpm）、Node 版本，以及实际安装的sst/pulumi版本。

这一"读仓库优先"的思想与本仓库整体理念一致：catalog 数据与技能内容索引（data/skills_index.json、data/aas-v1/skill-content-index.v1.json）同样强调在引用技能前先建立完整上下文。

四、Author：编写与链接资源

4.1 通用约定（Universal）：任何 SST v4 + AWS 项目都适用

以下原则对所有 SST v4 + AWS 项目成立，可以放心到处应用：

① 在一个地方刻意控制 Node 运行时。不要让运行时取决于安装的 SST 的默认值。惯用法是在run()中加入单个全局 transform：

$transform(sst.aws.Function, (args) => { args.runtime ??= "nodejs24.x"; });

这里用??=是正确的：transform 运行在组件应用自身默认值之前，因此只在用户未显式设置时兜底。较新的 SST 默认已经是较新的 Node 运行时，所以先通过 Context7 检查已安装版本的默认值；该 transform 本质上是"版本无关保险"——防止未来 SST 降级时静默改变你的整个函数舰队运行时。

② 绝不要把 PulumiOutput<T>插进普通 JS 模板字符串。必须使用$interpolate（或pulumi.interpolate）。一个裸的顶层`${bucket.arn}/*`会把Output字符串化成一个[Output<T>]占位符，产生一个只能在部署时才失败的坏 ARN（它类型检查能过、sst dev也能正常跑）。修复方式是$interpolate```${bucket.arn}/*` ``。这个问题曾经造成过生产部署中断。

// ❌ 错误：类型检查通过、dev 正常，但部署时 ARN 是坏的 const policy = new aws.iam.PolicyStatement({ actions: ["s3:GetObject"], resources: [`${bucket.arn}/*`], }); // ✅ 正确：$interpolate 延迟求值 const policy = new aws.iam.PolicyStatement({ actions: ["s3:GetObject"], resources: $interpolate`${bucket.arn}/*`, });

③ 在 Pulumi 类型之间迁移资源，默认走两个 PR。Pulumi 是 create-before-destroy 语义，因此对于有唯一性约束的 AWS 名称（bucket、IAM role、gateway），旧资源仍占用该名称，创建新资源会以ConflictException失败。两个连续部署（先拆除、再重建）是保守默认；aliases:、pulumi import、状态手术（state surgery）在某些情况下可以桥接身份，但必须经过评审的计划。

④ 优先使用类型化的sst.aws.*/aws.*资源，而不是aws.cloudcontrol.Resource逃生舱。CloudControl 的输出是字符串类型（stringly-typed），且oneOf字段无法干净地 patch。仅在尚无类型化资源时使用它，一旦有类型化资源发布就应迁离。

4.2 项目特定默认（Project-specific）：采纳但需逐仓库确认

以下是这些项目共同选择的默认值，可为了保持一致性而采纳，但每个仓库可能不同，需确认：

• 区域ap-northeast-1、home: "aws"、defaultTags携带Project/Stage/ManagedBy: "sst"；
• 按 Stage 门控生命周期：

removal: stage === "prod" ? "retain" : "remove", protect: stage === "prod",

这样生产资源在栈拆除时得以保留，非生产预览环境能自动清理；

• SSM Parameter Store 作为图外契约（out-of-graph contract），前缀为/{app}/{stage}/{domain}/...——供不在 Pulumi 图内的消费者使用（CI 脚本、兄弟应用、运维人员）。同一应用的 Lambda 之间优先用 SSTlink:（它会接通真实依赖边并授予 IAM），不要把同应用共享绕道 SSM；
• run()内使用懒加载await import("./infra/<module>")，让sst dev热重载保持轻量。（注意：对测试而言，模块顶层new sst.aws.*在 import 时仍会执行，除非包在工厂函数里——见下节）；
• 每个 infra 模块配源码级 Vitest 测试——轻量、符合房子风格的回归网，直接断言源码文本（资源名、索引形状、IAM 范围）。这是一个刻意选择，不是 SST 的限制：Pulumi 确实支持运行时 mock（@pulumi/pulumi/runtime）来对带真实逻辑的模块做行为图测试。源码断言不能替代 preview-deploy + smoke test；
• 可观测性门禁：每个新的 Lambda/queue/schedule 在合并前都要有 alarm 和结构化日志。是否强制取决于项目，但这是廉价的保险。

当你引入一条约定时，要说明它属于哪个桶（"这是通用规则"还是"匹配本仓库风格"），让用户能刻意覆盖项目特定约定。

4.3 共享模式速查

• 图内共享（in-graph）：同一 SST 应用内，用link:传递资源引用——它建立真实依赖边并自动授予 IAM 权限；
• 图外共享（out-of-graph）：CI 脚本、兄弟应用、运维人员等非图内消费者，通过 SSM Parameter Store（/{app}/{stage}/{domain}/...前缀）读取产出值；
• IAM 范围：跨资源引用配合$interpolate进行最小权限作用域限定。

五、Test：源码级 Vitest 断言

基础设施测试的推荐做法是对每个 infra 模块写源码级 Vitest 测试：断言对象是源码文本本身——资源名称、索引形状（index shapes）、IAM 作用域。这类测试：

• 是轻量级的回归网，能在不真正对 AWS 发起调用的情况下钉住资源不变量；
• 是对"改一处、悄悄破坏另一处"的廉价防护；
• 运行时执行npx vitest（或仓库test脚本）。

需要指出的是，源码断言不能替代preview-deploy + smoke test；当模块包含真实逻辑时，也可选用 Pulumi 运行时 mock（@pulumi/pulumi/runtime）做行为级图测试——这是刻意权衡，而非框架限制。

六、Deploy/Operate：部署与排障

6.1 部署前检查

• 运行npx sst diff和/或tsc --noEmit，在部署前捕获类型错误和计划错误；
• 任何sst deploy之前，先用aws sts get-caller-identity确认目标账户——防止把资源部署到错误的 AWS 账户；
• 部署后清理导出的状态文件：它们包含账户 ID 和 ARN，绝不能残留在/tmp或聊天历史中。

6.2 迁移（Migrations）要点

• 在 Pulumi 类型之间迁移资源、或重命名物理名称时，默认拆成两个 PR（teardown → recreate），规避 create-before-destroy 下的ConflictException；
• 如需保留身份连续性，可选aliases:、pulumi import或状态手术，但必须先有经过评审的计划；
• 任何不可逆操作（部署、sst remove、资源类型迁移）都要向用户标明目标账户，迁移按两个 PR 而非一个规划。

6.3 可观测性门禁

每个新增的 Lambda/queue/schedule 在合并前都应配套 alarm 与结构化日志。这条规则是否强制取决于项目，但从实践看是"廉价的保险"——生产事故往往始于无告警的静默失败。

七、工作节奏（Working Rhythm）：六步闭环

SKILL.md 将完整流程归纳为六步，可直接照做：

1. Orient：按第三节建立 config、模块、测试、工具链的项目地图；
2. Verify：任何不明显的语法都用 Context7 / AWS docs MCP 验证，不要猜组件选项名；
3. Author：按第四节编写资源/模块，并匹配周边文件的注释密度与命名——这些项目大量注释why，在注释密集的文件里写一行简短的注释会像是一种回归；
4. Test：新增或更新源码级断言并运行npx vitest（或test脚本），再跑npx sst diff/tsc --noEmit捕获计划与类型错误；
5. Deploy/operate：按第六节执行，部署前用aws sts get-caller-identity确认账户；
6. Clean up：清理导出的状态文件（含账户 ID 与 ARN），不要留在/tmp或对话历史中。

八、What good looks like：做对了应该是什么样

• 改动是满足需求的最小 diff，落在正确的infra/模块，并按依赖顺序接入run()；
• 每个 Lambda 通过全局 transform 获得正确运行时（没有手设runtime，除非刻意偏离——例如 Python 函数）；
• 跨资源引用使用link:（图内）和/或$interpolate作用域的 IAM；其他工具消费的产出值发布到 SSM 的 stage 前缀下；
• 新基础设施有匹配的源码级测试，且既有测试套件保持绿色；
• AWS 侧事实通过 docs MCP、SST/Pulumi 语法通过 Context7 确认，而非依赖记忆；
• 任何不可逆操作（部署、sst remove、资源类型迁移）都向用户标注目标账户，迁移按两个 PR 规划。

九、使用示例与限制

9.1 调用示例

User request: > Use @aws-sst-development for this task: SST v4 (Ion) expert for managing AWS resources as code with the Pulumi-backed framework.

9.2 使用限制（Limitations）

• 仅当任务与上游来源和本地项目上下文明确匹配时使用本技能；
• 在应用改动前，务必验证命令、生成的代码、依赖、凭据及外部服务行为；
• 不要把示例当作环境特定测试、安全评审或用户对破坏性/高成本操作的批准之替代品。

十、小结

aws-sst-development技能将 SST v4（Ion）的生产级实践浓缩为一套可执行的约定体系：以定向读仓库为前提，以"通用 vs 项目特定"二分法组织约定，以源码级测试兜底，以双 PR 迁移守护生产安全。其核心红线——Output<T>必须用$interpolate、运行时集中用$transform控制、部署前确认账户、图内用link:图外用 SSM——每一条都来自真实多栈项目以生产事故换来的教训。读者可将本文作为使用该技能的完整工作手册，也可以把它当作自建 SST v4 项目规范时的参照蓝本；涉及具体组件选项与 AWS 侧事实时，请始终按文档要求回到 Context7 与 AWS 官方文档做最终核验。

• AI 技能
• AI 插件
• 人工智能