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,从而实现更快的部署速度和更简洁的编程模型。核心思想:
- 单一配置文件 — 整个应用在
sst.config.ts中定义。基础设施、前端和函数在 TypeScript 中通过循环、条件语句和函数统一声明。 - 组件优于构造 — 高层次的
sst.aws.*组件封装了最佳实践(IAM、日志、监控)。当默认值不足时,使用transform深入底层资源进行自定义。 - 资源链接 — 杀手级功能。
link: [bucket]自动授予 IAM 权限并注入类型安全的引用。运行时通过Resource.MyBucket.name访问。无需手动传递 ARN 或配置环境变量。 - 基于阶段的隔离 — 每个开发者都有自己的阶段(
sst dev创建个人堆栈)。$app.stage驱动资源命名。生产环境使用sst deploy --stage production。 - 在真实 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.Function | Lambda | 无服务器函数 |
sst.aws.ApiGatewayV2 | API Gateway v2 | 带路由的 HTTP API |
sst.aws.Dynamo | DynamoDB | NoSQL 数据库 |
sst.aws.Bucket | S3 | 对象存储 |
sst.aws.Queue | SQS | 消息队列 |
sst.aws.Topic | SNS | 发布/订阅消息 |
sst.aws.Cron | EventBridge | 定时任务 |
sst.aws.Vpc | VPC | 网络隔离 |
sst.aws.Cluster | ECS | 容器工作负载 |
sst.aws.Postgres | RDS Postgres | 关系型数据库 |
sst.aws.Nextjs | Lambda + CloudFront | Next.js 部署 |
sst.aws.Remix | Lambda + CloudFront | Remix 部署 |
sst.aws.Astro | Lambda + CloudFront | Astro 部署 |
sst.aws.StaticSite | S3 + CloudFront | 静态站点托管 |
sst.aws.Router | CloudFront | URL 路由 |
有关 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>