aws-amplify

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 还是移动端，请先询问再继续——框架选择会影响后续每个步骤。
• 仅后端： 如果用户只要求修改后端，且未提及前端框架，则完全跳过前端集成步骤。

如果用户未指定工具或策略：

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

快速开始 — 跳转到相应参考文档

第 1 步：确定任务类型

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

步骤 2：后端功能

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

功能	参考文档	使用场景
身份验证	auth-backend.md	电子邮件/密码、社交登录、多因素身份验证（MFA）、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	geo-pubsub-cdk.md	仅后端：自定义 CDK 堆栈、覆盖、自定义输出。后端 + 前端：地理位置、PubSub、Face Liveness

每个后端功能文件都是独立完整的。仅加载所需内容。

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

步骤 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 和 Functions 的前端模式分别包含在 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）生成，绝不提交。

目录结构

amplify/ 和 src/ 必须是项目根目录下的同级目录——将它们放在不同的目录层级会导致沙盒检测失败。（例外：在单体仓库中，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/                      # Frontend code
├── amplify_outputs.json      # Generated, gitignored — never edit or commit
└── 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

框架设置

这些模式适用于所有 Web 任务，而不仅是新项目。在实现任何功能之前，请逐项确认。

Gen2 检测

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

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

如果两项都满足，项目已经是 Gen2——跳到功能实现。如果存在 amplify/.config/，则这是 Gen1 项目——请勿继续（需要使用单独的迁移技能）。

前端配置

在适合框架的正确入口点中导入生成的输出并配置 Amplify。放错文件会导致静默失败——Amplify API 调用会返回 undefined 或空响应，且不报错。

警告： 应用编译前必须存在 amplify_outputs.json，否则构建会因找不到模块而失败。先运行 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 是服务端组件。请使用下面的 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 or getServerSideProps
import { Amplify } from 'aws-amplify';
import outputs from '@/amplify_outputs.json';
Amplify.configure(outputs, { ssr: true });

主要区别： App Router 使用全局客户端组件。Pages Router 则在各个文件中分别配置。

在 layout.tsx 中需要使用 <Authenticator.Provider> 来提供身份验证上下文。

React Native

React Native 与 Web 框架使用相同的 aws-amplify JS 包（它属于 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-native-async-storage/async-storage 是必需的——Amplify SDK 使用它持久化令牌，缺少它会导致运行时失败。

配置入口点

无需注册插件——只需进行配置。

React Native（Expo）——App.tsx：

import 'react-native-get-random-values';  // MUST be first
import { Amplify } from 'aws-amplify';
import outputs from './amplify_outputs.json';
Amplify.configure(outputs);

React Native（Bare CLI）——index.js（位于 AppRegistry.registerComponent 之前）：

import 'react-native-get-random-values';  // MUST be first
import { Amplify } from 'aws-amplify';
import outputs from './amplify_outputs.json';
Amplify.configure(outputs);

React Native 注意事项

• 导入顺序： react-native-get-random-values 必须是入口文件中的第一个导入项，且要放在 aws-amplify 之前。颠倒顺序会导致运行时出现加密错误。
• 缺少 AsyncStorage： 如果没有 @react-native-async-storage/async-storage，身份验证令牌就无法持久化，用户必须在每次应用重启时重新进行身份验证。

SvelteKit

在客户端 hooks 文件中配置 Amplify：

// src/hooks.client.ts
import { Amplify } from 'aws-amplify';
import outputs from '../amplify_outputs.json';

Amplify.configure(outputs);

注意： Svelte 没有 @aws-amplify/ui-* 组件。请直接使用核心 API。

不受支持的框架（Astro、Solid 等）

对于没有官方 Amplify 支持的框架：

1. 使用 npm create amplify@latest -y 搭建后端（适用于任何项目）
2. 在客户端组件（而非构建时）中配置 Amplify

Astro

Amplify 在 Astro 中仅适用于客户端。创建一个 React 组件（不要使用 Astro 语法）：

// src/components/AuthenticatedApp.tsx
import { Amplify } from 'aws-amplify';
import { Authenticator } from '@aws-amplify/ui-react';
import outputs from '../amplify_outputs.json';

Amplify.configure(outputs);

export default function AuthenticatedApp() {
  return (
    <Authenticator>
      {({ signOut, user }) => <main>Hello {user?.username}</main>}
    </Authenticator>
  );
}

在 Astro 页面中使用 client:only：

---
// src/pages/index.astro — no Amplify imports here
---
<html>
  <body>
    <AuthenticatedApp client:only="react" />
  </body>
</html>

必须使用 client:only="react"（不能使用 client:load），以避免 SSR 水合错误。

链接

所有文档链接都默认使用 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

• 面向大模型的 Amplify 文档
• Amplify 文档
• Amplify 的工作原理
• CLI 命令
• React 快速入门
• Next.js 快速入门
• Angular 快速入门
• Vue 快速入门
• React Native 快速入门