SST (Ion) 基礎設施即程式碼

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 開發，享受低於 10ms 的重新載入速度。使用 $app.stage 進行多環境隔離。使用 transform 來客製化底層的 Pulumi 資源。

---

<critical_requirements>

關鍵：使用此技能前必讀

所有程式碼必須遵循 CLAUDE.md 中的專案慣例（kebab-case、具名匯出、匯入順序、import type、具名常數）

（你必須使用資源連結 (link + Resource.*) 來連接元件 — 絕不能將 ARN、資料表名稱或儲存桶名稱寫死）

（你必須使用 $app.stage 進行環境隔離 — 除非明確意圖，否則絕不能跨階段共用資源）

（你必須使用 sst dev 進行本地開發 — 它可針對真實 AWS 資源提供低於 10ms 重新載入的即時 Lambda 代理）

（你必須使用 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, Resource from sst, sst dev, sst deploy, sst remove, sst secret, $app.stage, $transform, $concat, $interpolate, resource linking, live Lambda, Ion

何時使用：

• 使用 TypeScript 與高階元件定義 AWS 基礎設施
• 部署無伺服器應用程式（Lambda、API Gateway、DynamoDB、S3、SQS、SNS）
• 部署全端應用程式（Next.js、Remix、Astro、SvelteKit、SolidStart 到 AWS）
• 設定使用真實 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 函數替換為代理到您本機機器的存根 (stubs)。變更在 10ms 內重新載入。無需本地模擬 — 程式碼直接對真實的 DynamoDB、S3、SQS 執行。

何時使用 SST：

• 在 AWS 上優先採用無伺服器的應用程式（Lambda、API Gateway、DynamoDB、S3、SQS、SNS）
• 將全端應用程式（Next.js、Remix、Astro）部署到 AWS
• 希望以最少 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 了解包含多階段、提供者和 protect 模式的完整設定。

---

模式 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 呼叫代理到您的本機機器，實現低於 10ms 的重新載入循環。

# 啟動即時開發 — 部署基礎設施，將 Lambda 代理到本機
sst dev

# 開啟多工器：部署資源、啟動前端、打通 VPC 隧道

// 在處理器程式碼中偵測開發模式
const isLocal = process.env.SST_DEV === "true";

關鍵行為： 函數會被替換為存根 (stubs)，這些存根透過 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 路由

請參閱 examples/api-data.md 了解 API、資料庫、儲存、佇列和 cron 模式。

---

模式 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 為所有階段設定一個預設值。

請參閱 examples/core.md 了解搭配 Linkable 模式的機密用法。

---

模式 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 可為所有元件設定預設值。

請參閱 examples/deployment.md 了解 transform 模式。

---

模式 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>

---

<red_flags

…

[爲翻譯而截斷]