aws-amplify

AWS Amplify Gen2

基于 AWS Amplify Gen2 的 TypeScript 代码优先（code-first）范式构建并部署全栈应用。本 Skill 涵盖后端资源创建、跨 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 还是移动端，须先询问确认后再继续——框架选型会直接影响后续每一步。
• 仅限后端： 若仅要求修改后端逻辑且未提及前端框架，则完全跳过前端集成步骤。

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

• 包管理器： 默认使用 npm，除非用户明确要求使用 yarn 或 pnpm。
• 开发语言： 默认使用 TypeScript。Gen2 后端必须使用 TypeScript；前端语言则保持与项目现有语言一致。
• Next.js： 默认使用 App Router，除非用户明确要求 Pages Router。
• React Native： 询问用户使用 Expo 还是 原生 React Native CLI (bare)。
• 身份认证： 必须 询问用户希望采用的登录方式（邮箱/密码、社交账号登录、SAML、无密码登录等），切勿直接套用默认配置。
• 数据授权： 默认采用 publicApiKey (allow.publicApiKey())——这是 Starter 模板的初始默认值。一旦引入身份认证，即切换为 基于所有者 (owner-based) 的授权 (allow.owner())，并设置 defaultAuthorizationMode: 'userPool'。

快速上手——按需查阅参考文档

步骤 1：确认任务类型

任务类型	查阅文档 / 后续步骤
创建新项目	→ 先参考 scaffolding.md，再执行步骤 2 与/或步骤 3
新增或修改后端功能	→ 查阅步骤 2（后端功能指南）
将前端连接至现有后端	→ 查阅步骤 3（前端集成指南）
部署应用程序	→ deployment.md

步骤 2：后端功能指南

根据具体所需的后端功能，阅读对应的参考文档：

功能模块	参考文档	适用场景
身份认证 (Auth)	auth-backend.md	邮箱/密码登录、社交账号登录、多因素认证 (MFA)、SAML/OIDC
数据模型 (Data)	data-backend.md	GraphQL schema、DynamoDB、关联关系、授权规则
文件存储 (Storage)	storage-backend.md	S3 文件上传/下载、访问权限控制规则
云函数与 API	functions-and-api.md	Lambda、自定义解析器 (resolver)、REST/HTTP API、客户端调用
AI 功能	ai.md	基于 Bedrock 的对话、内容生成、AI 工具*(后端配置 + React/Next.js 前端)*
地理/PubSub/CDK 扩展	geo-pubsub-cdk.md	仅后端：自定义 CDK Stack、覆盖配置、自定义输出；后端+前端：Geo 地理信息、PubSub 消息订阅、Face Liveness 人脸活体检测

每个后端功能参考文档都是独立的，按需读取即可。

路由说明： 无论是新增还是修改功能，均适用同一份文档。不论用户说“添加 Auth”还是“修改 Auth 配置”，都统一跳转到对应的参考文件——每份文档都涵盖了该 API 属性的完整配置说明。

步骤 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 模块和云函数/API 的前端接入模式已分别直接包含在 ai.md 与 functions-and-api.md 中，未拆分为独立的 Web/Mobile 文件。

核心概念

Amplify Gen2 架构

• 代码优先 (Code-first)： 所有后端资源均在 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() 消费读取。须写入 .gitignore——它由 npx ampx sandbox（本地开发）或 npx ampx pipeline-deploy（CI/CD 构建）自动生成，严禁提交至 Git 仓库。

目录结构

amplify/ 目录与 src/ 目录必须在项目根目录下保持同级——如果层级错乱会导致沙箱检测失效。（例外情况：在 Monorepo 架构中，amplify/ 可以放在 packages/ 子目录下，核心在于前端代码的入口必须能正常访问到 amplify_outputs.json。）

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/                      # 前端源码
├── amplify_outputs.json      # 自动生成，必须忽略（不可手动修改或提交）
└── package.json

核心 API 包说明

包名 (Package)	主要用途
@aws-amplify/backend	后端定义：defineAuth、defineData、defineStorage、defineFunction、defineBackend
aws-amplify	前端 SDK：Amplify.configure()、generateClient()、身份认证/数据/存储等 API
@aws-amplify/ui-react	预置 UI 组件：<Authenticator>、<StorageBrowser>
@aws-amplify/ui-react-ai	AI 交互组件：<AIConversation>、useAIConversation

框架配置与接入

这些配置范式适用于 所有 Web 任务——不仅仅是新建项目。在实现具体功能前，请务必先逐一校验。

Gen2 项目识别

在修改任何代码之前，先检查当前项目是否已经是 Gen2：

1. 存在 amplify/ 目录且包含 backend.ts
2. package.json 的 devDependencies 中包含 @aws-amplify/backend

如果两条件均满足，说明项目已是 Gen2——直接跳到对应功能实现即可。如果发现存在的是 amplify/.config/ 目录，则说明这是 Gen1 项目——请勿继续操作（需调用单独的迁移 Skill）。

前端初始化配置

导入自动生成的配置文件，并在对应框架的 正确入口文件 中配置 Amplify。如果加错了文件，会导致“无报错静默失效”——即 Amplify API 调用直接返回 undefined 或空响应且没有任何报错信息。

警告： 项目编译前必须保证 amplify_outputs.json 文件已存在——否则构建会直接报 module-not-found 错误。请先运行 npx ampx sandbox（或 npx ampx sandbox --once）生成该文件。正确的执行顺序请参考 scaffolding.md。

React (Vite) — src/main.tsx：

import { Amplify } from 'aws-amplify';
import outputs from '../amplify_outputs.json';
Amplify.configure(outputs);

Next.js (App Router) — app/layout.tsx：

重要提示： 在 App Router 中，layout.tsx 是服务端组件 (Server Component)。请按下方方式使用 ConfigureAmplifyClientSide 客户端组件范式进行配置。

{ ssr: true } 是 Next.js 专属 参数（Vue、Angular 或 React SPA 无需配置）。App Router 和 Pages Router 均使用该配置，但配置方式有所不同：

• App Router — 在客户端组件 ConfigureAmplifyClientSide 中进行全局配置
• Pages Router — 在需要服务端访问的各个具体文件内单独配置

Next.js App Router：客户端配置

Next.js App Router 需要单独创建一个客户端组件，以在浏览器端初始化 Amplify：

// components/ConfigureAmplifyClientSide.tsx
"use client";
import { Amplify } from "aws-amplify";
import outputs from "@/amplify_outputs.json";

Amplify.configure(outputs, { ssr: true });

export default function ConfigureAmplifyClientSide() {
  return null;
}

在根布局文件中导入：

// app/layout.tsx
import ConfigureAmplifyClientSide from "@/components/ConfigureAmplifyClientSide";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <ConfigureAmplifyClientSide />
        {children}
      </body>
    </html>
  );
}

原理说明： App Router 下 layout.tsx 属于服务端组件，而客户端组件需要在浏览器环境运行 Amplify.configure()。若缺失此配置，会触发 "Auth UserPool not configured" 错误。

Vue — src/main.js：

import { Amplify } from 'aws-amplify';
import outputs from '../amplify_outputs.json';
Amplify.configure(outputs);

Angular — src/main.ts：

import { Amplify } from 'aws-amplify';
import outputs from '../amplify_outputs.json';
Amplify.configure(outputs);

Next.js Pages Router

Pages Router 不需要 在 _app.tsx 中配置 { ssr: true }。改为在需要服务端访问的具体文件里按需配置：

// pages/api/protected.ts 或 getServerSideProps 中
import { Amplify } from 'aws-amplify';
import outputs from '@/amplify_outputs.json';
Amplify.configure(outputs, { ssr: true });

核心差异： App Router 使用全局客户端组件进行初始化；Pages Router 则按文件单独配置。

如需使用 Auth 上下文，需要在 layout.tsx 中包裹 <Authenticator.Provider>。

React Native

React Native 与 Web 框架共用同一个 aws-amplify JS SDK 包（属于 amplify-js，而非原生移动端 SDK）。所有 Web 端 API 均适用于 RN，只需额外补充以下依赖和配置。

必需依赖包

npm install aws-amplify @aws-amplify/react-native \
  @react-native-async-storage/async-storage \
  react-native-get-random-values

`@react