amplify-workflow

AWS Amplify Gen2

使用 AWS Amplify Gen2 的 TypeScript 代码优先方式构建和部署全栈应用。此技能涵盖后端资源创建、跨 8 种框架的前端集成，以及部署工作流。

前提条件

• Node.js ^18.19.0 || ^20.6.0 || >=22 和 npm
• 已配置 AWS 凭证（aws sts get-caller-identity 执行成功）
• 对于沙盒：npx ampx --version 返回有效版本
• 对于移动端：特定平台的工具（Xcode、Android Studio、Flutter SDK）

默认选项与假设

当用户未指定框架时：

• Web： 你应该默认使用 React（Vite），并说明选择理由。
• 移动端： 你必须询问用户想使用哪个平台（Flutter、Swift、Android 或 React Native）。移动端没有通用默认选项。
• 两者都未指定： 如果用户说“构建一个应用”，但未说明是 Web 还是移动端，你必须先询问再继续。
• 仅后端： 如果用户只要求修改后端，且未提及前端框架，则完全跳过前端集成步骤。

当用户未指定工具或策略时：

• 包管理器： 除非用户指定 yarn 或 pnpm，否则你应该默认使用 npm。
• 语言： 你应该默认使用 TypeScript。Gen2 后端仅支持 TypeScript；前端应该遵循项目现有的语言。
• Next.js： 除非用户指定 Pages Router，否则你应该默认使用 App Router。
• React Native： 询问用户使用的是 Expo 还是 bare React Native CLI。
• 身份验证： 你必须询问用户想使用哪种登录方式（电子邮件/密码、社交登录、SAML、无密码登录等）。不要自行假设默认选项。
• 数据授权： 默认使用 publicApiKey（allow.publicApiKey()）——这是入门模板的默认选项。添加身份验证后，切换为基于所有者的授权（allow.owner()），并将 defaultAuthorizationMode 设为 'userPool'。

快速开始 — 找到合适的参考文档

步骤 0：阅读核心参考文档（始终执行）

在阅读任何其他参考文件之前，你必须先阅读目标平台的核心参考文档。其中包含 Gen2 检测、各框架中 Amplify.configure() 的位置、沙盒命令、必需的软件包和目录结构规则——这些模式适用于所有任务，而不仅仅是新项目。

• Web（React、Next.js、Vue、Angular、React Native）：你必须阅读 core-web.md
• 移动端（Flutter、Swift、Android）：你必须阅读 core-mobile.md
• 仅后端（无前端工作）：跳至步骤 1。

步骤 1：确定任务类型

任务	前往
创建新项目	→ scaffolding.md，然后执行步骤 2 和/或步骤 3
添加或修改后端功能	→ 步骤 2（后端功能）
将前端连接到现有后端	→ 步骤 3（前端集成）
部署应用程序	→ deployment.md

步骤 2：后端功能

对于每项后端功能，必须阅读对应的参考文档：

功能	参考文档	适用场景
身份验证	auth-backend.md	电子邮件/密码、社交登录、多因素身份验证、SAML/OIDC
数据模型	data-backend.md	GraphQL 架构、DynamoDB、关系、授权规则
文件存储	storage-backend.md	S3 上传/下载、访问规则
函数与 API	functions-and-api.md	Lambda、自定义解析器、REST/HTTP API、从客户端调用
AI 功能	ai.md	对话、生成、通过 Bedrock 使用 AI 工具 (后端配置 + React/Next.js 前端)
地理位置、PubSub、CDK	advanced-features.md	仅后端：自定义 CDK 堆栈、覆盖、自定义输出。后端 + 前端：地理位置、PubSub、人脸活体检测

每个后端功能文件都包含完整内容。仅加载所需内容。

路由说明： 这些文件适用于添加和修改功能。无论用户说“添加身份验证”还是“更改身份验证配置”，都路由到同一个文件——每份参考文档都涵盖完整的定义范围。

步骤 3：前端集成

配置后端资源后，连接前端。根据平台和功能选择：

Web（React、Next.js、Vue、Angular、React Native）：

功能	参考文档
身份验证 UI 与流程	auth-web.md
数据 CRUD 与订阅	data-web.md
存储上传/下载	storage-web.md

移动端（Flutter、Swift、Android）：

功能	参考文档
身份验证 UI 与流程	auth-mobile.md
数据 CRUD 与订阅	data-mobile.md
存储上传/下载	storage-mobile.md

注意： AI 和函数的前端模式分别包含在 ai.md 和 functions-and-api.md 中—— 它们不会拆分为单独的 Web/移动端文件。

核心概念

Amplify Gen2 架构

• 代码优先： 所有后端资源均在 amplify/ 下使用 TypeScript 定义
• 主配置： amplify/backend.ts 通过 defineBackend() 导入并组合所有资源
• 资源文件： amplify/auth/resource.ts、amplify/data/resource.ts、 amplify/storage/resource.ts、amplify/functions/<name>/resource.ts
• 生成的输出： amplify_outputs.json——由前端的 Amplify.configure() 使用。已加入 Git 忽略——由 npx ampx sandbox （本地开发）或 npx ampx pipeline-deploy（CI/CD）生成，绝不提交。

目录结构

project-root/
├── amplify/
│   ├── backend.ts            # defineBackend({ auth, data, ... })
│   ├── auth/resource.ts      # defineAuth({ ... })
│   ├── data/resource.ts      # defineData({ schema })
│   ├── storage/resource.ts   # defineStorage({ ... })
│   └── functions/
│       └── my-func/
│           ├── resource.ts   # defineFunction({ ... })
│           └── handler.ts    # export const handler = ...
├── src/                      # Frontend code
├── amplify_outputs.json      # Generated — DO NOT edit or commit (gitignored)
└── package.json

核心 API

包	用途
@aws-amplify/backend	defineAuth、defineData、defineStorage、defineFunction、defineBackend
aws-amplify	前端：Amplify.configure()、generateClient()、身份验证/数据/存储 API
@aws-amplify/ui-react	预构建 UI：<Authenticator>、<StorageBrowser>
@aws-amplify/ui-react-ai	AI UI：<AIConversation>、useAIConversation

文档与资源验证

需要 AWS 文档（高级 CDK 构造、服务限制、特定提供商的身份验证配置）时：

1. 如果有可用的 AWS 文档工具（例如通过 AWS MCP），你应当 使用这些工具搜索并检索相关文档页面。
2. 如果没有可用的 AWS 文档工具，你必须改用网络搜索或 aws CLI 验证资源。

为何有条件： Amplify Gen2 采用代码优先的方式——主要工作流是 编辑 TypeScript 文件并运行 npx ampx 命令。AWS MCP 工具 对部署后验证很有用，但并非必需。

安全注意事项

• 所有凭证和 API 密钥都使用 secret()——切勿硬编码，也不要使用普通环境变量存储敏感值
• 仔细检查 allow.guest() 的开放范围——默认启用访客访问，并允许未认证用户访问经 IAM 授权的资源
• 将 IAM 策略范围限定为特定资源 ARN——在生产环境中避免使用 resources: ['*']
• 切勿记录机密信息，也不要将其包含在错误消息中
• 启用 CloudTrail 和 CloudWatch 警报，监控由 Amplify 部署的资源；为 S3、AppSync 和 API Gateway 启用访问日志记录
• 为 Web 应用配置安全标头——通过 amplify.yml 中的 customHeaders 设置 CSP、HSTS、X-Frame-Options 和 X-Content-Type-Options
• 为面向公网的 AppSync API 和 API Gateway 端点附加 AWS WAF，增强纵深防御
• 在 API Gateway 和 AppSync API 上启用节流和速率限制，以防止滥用
• 为 CI/CD 流水线和 Lambda 执行角色使用带有临时凭证的 IAM 角色——切勿使用长期有效的访问密钥
• 如果 CloudWatch Logs 日志组可能包含 PII、令牌或机密信息，请使用 KMS（aws:kms）加密；启用日志保留策略
• 启用 AppSync 架构验证和 API Gateway 请求验证器，以便在边缘拒绝格式错误的输入
• 为 Amplify Hosting 的自定义域使用由 ACM 管理的 TLS 证书——在部署配置中通过 customDomain 进行配置

链接

所有文档链接默认使用 react 作为平台 slug。将任何 URL 中的 /react/ 替换为目标框架对应的 slug：

框架	Slug
React	react
Next.js	nextjs
Vue	vue
Angular	angular
React Native	react-native
Flutter	flutter
Swift	swift
Android	android

• 面向 LLM 的 Amplify 文档
• Amplify 文档
• Gen2 文档
• 入门指南
• 快速入门
• 账户设置
• Amplify 的工作原理
• 核心概念
• 构建后端
• 部署和托管
• 故障排除
• CLI 命令
• Amplify 输出
• 项目结构
• Amplify UI