Communitygithub.com

SST (Ion) 基础设施即代码模式

基于 TypeScript 的 AWS 无服务器基础设施即代码,由 Pulumi 驱动,支持资源链接和实时 Lambda 开发。

SST (Ion) 基础设施即代码模式 是什么?

SST v3 (Ion) 是一种 TypeScript 优先的基础设施即代码框架,专为 AWS 无服务器应用设计。它用 Pulumi/Terraform 替代了传统的 CDK/CloudFormation,从而提供更快的部署速度和更简洁的编程模型。核心功能包括:在单一的 `sst.config.ts` 文件中定义整个应用(使用 `sst.aws.Function`、`sst.aws.ApiGatewayV2` 等高层次组件);通过 `link` 属性和 `Resource` SDK 实现类型安全、权限感知的资源链接;利用 `sst dev` 命令进行实时 Lambda 开发,在真实 AWS 资源上实现亚 10 毫秒的重载;通过 `$app.stage` 实现多环境隔离;以及使用 `transform` 功能自定义底层 Pulumi 资源。此技能提供了全面的模式指南,涵盖核心配置、数据存储、API、前端部署、CI/CD、异步处理、密钥管理和自定义链接等。它适用于无服务器优先的全栈应用项目,但若项目主要使用多云或纯容器化部署,则不建议采用。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/agents-inc/skills/tree/HEAD/src/skills/infra-iac-sst

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

SST (Ion) 模式

快速指南: SST v3 (Ion) 是基于 TypeScript 的 AWS 基础设施即代码框架,由 Pulumi/Terraform 驱动(而非 CDK/CloudFormation)。在 sst.config.ts 中使用高层次组件(例如 sst.aws.Function、sst.aws.ApiGatewayV2、sst.aws.Bucket、sst.aws.Dynamo 等)定义整个应用。使用资源链接(link: [bucket] + Resource.MyBucket.name)实现组件之间的类型安全、权限感知访问。使用 sst dev 进行实时 Lambda 开发,重载时间低于 10 毫秒。使用 $app.stage 实现多环境隔离。使用 transform 自定义底层 Pulumi 资源。


<critical_requirements>

重要:使用此技能前必读

所有代码必须遵循 CLAUDE.md 中的项目约定(kebab-case 命名、具名导出、导入顺序、import type、具名常量)

(你必须使用资源链接(link + Resource.*)连接组件——切勿硬编码 ARN、表名或桶名)

(你必须使用 $app.stage 进行环境隔离——除非明确意图,否则切勿跨阶段共享资源)

(你必须使用 sst dev 进行本地开发——它提供针对真实 AWS 资源的实时 Lambda 代理,重载时间低于 10 毫秒)

(你必须使用 sst secret set 管理密钥——切勿将密钥放入 sst.config.ts、提交到 git 的 .env 文件或环境变量中)

(你必须使用 transform 自定义底层资源——当存在 SST 组件时,切勿直接使用裸 Pulumi 资源)

</critical_requirements>


示例

  • 核心模式 — sst.config.ts 结构、Function、资源链接、$app 全局变量、密钥、多阶段
  • API 与数据 — ApiGatewayV2、Dynamo、Bucket、Queue、Topic、Cron、授权
  • 部署与 DevOps — sst deploy、CI/CD、移除策略、transforms、Vpc、Cluster、前端框架
  • 快速参考 — CLI 命令、组件速查表、全局辅助函数、具名常量

自动检测: SST、sst.config.ts、sst.aws.Function、sst.aws.ApiGatewayV2、sst.aws.Bucket、sst.aws.Dynamo、sst.aws.Queue、sst.aws.Topic、sst.aws.Cron、sst.aws.Nextjs、sst.aws.Remix、sst.aws.Astro、sst.aws.StaticSite、sst.aws.Vpc、sst.aws.Cluster、sst.aws.Postgres、sst.aws.Router、sst.Linkable、sst 的 Resource、sst dev、sst deploy、sst remove、sst secret、$app.stage、$transform、$concat、$interpolate、资源链接、实时 Lambda、Ion

何时使用:

  • 使用高层次组件在 TypeScript 中定义 AWS 基础设施
  • 部署无服务器应用(Lambda、API Gateway、DynamoDB、S3、SQS、SNS)
  • 部署全栈应用(在 AWS 上的 Next.js、Remix、Astro、SvelteKit、SolidStart)
  • 使用真实 AWS 资源设置实时 Lambda 开发环境
  • 管理多阶段环境(开发、预发布、生产)
  • 使用类型安全的资源链接连接基础设施组件

何时不使用:

  • 跨多个云提供商的多云基础设施(SST 主要关注 AWS,对 Cloudflare 支持有限)
  • 已有的 Terraform/Pulumi 代码库,SST 抽象没有增加价值
  • 仅需要容器化部署且没有服务器组件的工作负载

涵盖的关键模式:

  • sst.config.ts 结构(app() + run() 函数)
  • 资源链接:link 属性 + Resource.* SDK
  • 使用 sst dev 进行实时 Lambda 开发
  • AWS 组件:Function、ApiGatewayV2、Dynamo、Bucket、Queue、Topic、Cron
  • 前端部署:Nextjs、Remix、Astro、StaticSite
  • 使用 $app.stage 进行多阶段隔离
  • 用于自定义底层 Pulumi 资源的 transforms
  • 使用 sst secret 管理密钥
  • 使用 sst.Linkable 和 Linkable.wrap 实现自定义链接
  • 全局辅助函数:$app、$dev、$concat、$interpolate、$resolve、$transform

核心理念

SST v3 (Ion) 使用 Pulumi/Terraform 取代 CDK/CloudFormation,从而实现更快的部署速度和更简洁的编程模型。核心思想:

  1. 单一配置文件 — 整个应用在 sst.config.ts 中定义。基础设施、前端和函数在 TypeScript 中通过循环、条件语句和函数统一声明。
  2. 组件优于构造 — 高层次的 sst.aws.* 组件封装了最佳实践(IAM、日志、监控)。当默认值不足时,使用 transform 深入底层资源进行自定义。
  3. 资源链接 — 杀手级功能。link: [bucket] 自动授予 IAM 权限并注入类型安全的引用。运行时通过 Resource.MyBucket.name 访问。无需手动传递 ARN 或配置环境变量。
  4. 基于阶段的隔离 — 每个开发者都有自己的阶段(sst dev 创建个人堆栈)。$app.stage 驱动资源命名。生产环境使用 sst deploy --stage production。
  5. 在真实 AWS 上进行实时开发 — sst dev 用存根替换 Lambda 函数,这些存根将请求代理到本地机器。更改在 10 毫秒内重新加载。无本地仿真——你的代码运行在真实的 DynamoDB、S3、SQS 之上。

何时使用 SST:

  • AWS 上的无服务器优先应用(Lambda、API Gateway、DynamoDB、S3、SQS、SNS)
  • 在 AWS 上部署前端框架的全栈应用(Next.js、Remix、Astro)
  • 希望使用最少 AWS 样板代码进行 TypeScript 基础设施开发的团队
  • 需要针对真实云资源进行快速本地开发循环的项目

何时不使用 SST:

  • 超出 AWS + Cloudflare 的多云基础设施(SST 的多云支持有限)
  • 没有服务器组件的纯容器工作负载(使用裸 Pulumi 或 Terraform)
  • 已有的庞大 Terraform/Pulumi 代码库,SST 抽象会增加迁移成本

核心模式

模式 1:sst.config.ts 结构

每个 SST 应用都有一个单一的 sst.config.ts,包含两个函数:app() 用于元数据,run() 用于资源。

/// <reference path="./.sst/platform/config.d.ts" />

export default $config({
  app(input) {
    return {
      name: "my-app",
      home: "aws",
      removal: input.stage === "production" ? "retain" : "remove",
      protect: input.stage === "production",
      providers: {
        aws: { region: "us-east-1" },
      },
    };
  },
  async run() {
    const bucket = new sst.aws.Bucket("Uploads");
    const api = new sst.aws.Function("Api", {
      handler: "src/api.handler",
      link: [bucket],
    });
    return { apiUrl: api.url };
  },
});

为何优秀: app() 处理元数据和阶段特定策略,run() 定义所有资源,removal: "retain" 保护生产数据,返回值成为 .sst/outputs.json 中的输出。

有关包含多阶段、提供者和保护模式的完整配置,请参见 examples/core.md。


模式 2:资源链接

这是 SST 的标志性功能。链接资源可自动授予权限并提供类型安全的访问。

// 在 sst.config.ts 中
const table = new sst.aws.Dynamo("Notes", {
  fields: { userId: "string", noteId: "string" },
  primaryIndex: { hashKey: "userId", rangeKey: "noteId" },
});

new sst.aws.Function("Api", {
  handler: "src/api.handler",
  link: [table],
});
// 在 src/api.ts 中 — 运行时代码
import { Resource } from "sst";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({});
// Resource.Notes.name 是表名 — 类型安全,自动生成
console.log(Resource.Notes.name);

为何优秀: 无需手动传递 ARN,IAM 权限自动授予,通过生成的 sst-env.d.ts 实现类型安全访问,适用于 Functions、前端和容器。

有关包含自定义链接模式的链接,请参见 examples/core.md。


模式 3:实时 Lambda 开发

sst dev 将 Lambda 调用代理到本地机器,实现亚 10 毫秒的重载周期。

# 启动实时开发 — 部署基础设施,将 Lambda 代理到本地机器
sst dev

# 打开多路复用器:部署资源,启动前端,隧道 VPC
// 在处理程序代码中检测开发模式
const isLocal = process.env.SST_DEV === "true";

关键行为: 函数被替换为存根,这些存根通过 AppSync 将事件转发到你的本地机器。本地代码作为 Node.js Workers 运行。更改立即重新加载——无需重新部署。

陷阱: 杀死 sst dev 会保留已部署的存根。后续 Lambda 调用将超时,直到你再次运行 sst dev 或运行 sst deploy 用真实代码替换存根。

有关开发工作流和调试设置,请参见 examples/core.md。


模式 4:AWS 组件

SST 为常见的 AWS 服务提供了高层次组件。每个组件自动处理 IAM、日志记录和配置。

组件AWS 服务用途
sst.aws.FunctionLambda无服务器函数
sst.aws.ApiGatewayV2API Gateway v2带路由的 HTTP API
sst.aws.DynamoDynamoDBNoSQL 数据库
sst.aws.BucketS3对象存储
sst.aws.QueueSQS消息队列
sst.aws.TopicSNS发布/订阅消息
sst.aws.CronEventBridge定时任务
sst.aws.VpcVPC网络隔离
sst.aws.ClusterECS容器工作负载
sst.aws.PostgresRDS Postgres关系型数据库
sst.aws.NextjsLambda + CloudFrontNext.js 部署
sst.aws.RemixLambda + CloudFrontRemix 部署
sst.aws.AstroLambda + CloudFrontAstro 部署
sst.aws.StaticSiteS3 + CloudFront静态站点托管
sst.aws.RouterCloudFrontURL 路由

有关 API、数据库、存储、队列和 cron 模式,请参见 examples/api-data.md。


模式 5:密钥管理

密钥被加密并存储在 S3 中,在部署时注入到函数包中。

# 设置一个密钥(提示输入值)
sst secret set DATABASE_URL

# 设置一个密钥并内联提供值
sst secret set STRIPE_KEY sk_live_xxx

# 从文件加载密钥
sst secret load .env.production

# 列出所有密钥
sst secret list
// 通过资源链接访问密钥
import { Resource } from "sst";
const stripeKey = Resource.StripeKey.value;

陷阱: 密钥是分阶段的。为每个阶段单独设置。使用 --fallback 为所有阶段设置默认值。

有关使用 Linkable 模式的密钥,请参见 examples/core.md。


模式 6:Transforms

当 SST 默认值不足时,自定义底层 Pulumi 资源。

// 单个组件 transform
new sst.aws.Function("Api", {
  handler: "src/api.handler",
  transform: {
    function: (args) => {
      args.tracingConfig = { mode: "Active" };
    },
  },
});

// 全局 transform — 应用于该类型的所有组件
$transform(sst.aws.Function, (args) => {
  args.environment ??= {};
  args.environment.variables ??= {};
  args.environment.variables.STAGE = $app.stage;
});

为何优秀: Transforms 让你可以自定义任何底层资源的属性,而无需放弃 SST 的抽象。全局 transforms 为所有组件设置默认值。

有关 transform 模式,请参见 examples/deployment.md。


模式 7:多阶段环境

每个阶段都是一个完全隔离的部署。使用 $app.stage 进行条件配置。

async run() {
  const isProd = $app.stage === "production";

  const table = new sst.aws.Dynamo("Notes", {
    fields: { userId: "string", noteId: "string" },
    primaryIndex: { hashKey: "userId", rangeKey: "noteId" },
    deletionProtection: isProd,
  });
}
# 个人开发阶段(默认)
sst dev

# 部署到预发布
sst deploy --stage staging

# 部署到生产
sst deploy --stage production

有关包含移除策略的多阶段模式,请参见 examples/deployment.md。


<decision_framework>

决策框架

选择 SST 组件

你想构建什么?
  |
  +-- HTTP API
  |     +-- 带有 Lambda 处理器的简单路由 --> sst.aws.ApiGatewayV2
  |     +-- 需要 WebSocket 支持 --> sst.aws.ApiGatewayWebSocket
  |     +-- URL 路由 / CDN --> sst.aws.Router
  |
  +-- 数据存储
  |     +-- 键值 / 文档数据 --> sst.aws.Dynamo
  |     +-- 使用 SQL 的关系数据 --> sst.aws.Postgres
  |     +-- 文件 / 二进制大对象存储 --> sst.aws.Bucket
  |
  +-- 异步处理
  |     +-- 点对点消息传递 --> sst.aws.Queue (SQS)
  |     +-- 扇出到多个订阅者 --> sst.aws.Topic (SNS)
  |     +-- 定时任务 --> sst.aws.Cron
  |
  +-- 计算
  |     +-- 无服务器函数 --> sst.aws.Function
  |     +-- 容器工作负载 --> sst.aws.Cluster + sst.aws.Service
  |     +-- 长时间运行的后台任务 --> sst.aws.Function (最长 15 分钟)
  |
  +-- 全栈前端
        +-- Next.js --> sst.aws.Nextjs
        +-- Remix --> sst.aws.Remix
        +-- Astro --> sst.aws.Astro
        +-- SvelteKit --> sst.aws.SvelteKit
        +-- SolidStart --> sst.aws.SolidStart
        +-- 静态 HTML/JS --> sst.aws.StaticSite

何时使用 Transforms 与裸 Pulumi

需要设置 SST 组件上的某个属性?
  |
  +-- 属性存在于 SST 组件参数中 --> 直接使用 SST 属性
  |
  +-- 属性仅存在于底层 AWS 资源中 --> 使用 transform
  |
  +-- 需要为组件的所有实例设置默认值 --> 使用 $transform()
  |
  +-- 该 AWS 服务没有对应的 SST 组件 --> 使用裸 Pulumi 资源
        +-- 需要链接它? --> 使用 sst.Linkable.wrap() 或 new sst.Linkable()

</decision_framework>

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

相关技能