AWS Amplify Gen2 完整指南

iX.

3 May, 2025

概述

AWS Amplify Gen2 是 AWS Amplify 的最新版本，为前端开发者提供了重新设计的全栈应用构建体验。通过 TypeScript 定义后端资源，基于 AWS CDK 构建，提供更灵活的云资源管理。Amplify Gen2相比Gen1 有非常多的改进，主要体现在：

开发体验：从CLI配置转向代码配置
类型安全：完整的TypeScript支持
AI集成：内置AI Kit功能
Sandbox 沙盒环境：个人云开发环境
现代化架构：基于CDK的更灵活架构

Amplify Gen2 和 Gen1 架构和基础设施对比：

特性	Gen1	Gen2
基础架构	基于CloudFormation模板	基于AWS CDK
配置方式	CLI交互式配置	TypeScript代码定义
资源管理	amplify-meta.json	完全代码化
版本控制	配置文件分离	所有配置都在代码中

核心特性

全栈 TypeScript: 使用 TypeScript 编写应用的数据模型、认证、存储和函数
基于 AWS CDK: 使用任何应用需要的云资源，无需担心扩展性
云端沙盒: 每个开发者都有独立的云沙盒环境
热重载: 后端代码变更的实时重载

支持的框架和版本

Next.js 支持

支持版本: Next.js >=13.5.0 <16.0.0
App Router: 完全支持 Next.js App Router
服务器组件: 支持 React Server Components
SSR: 完整的服务器端渲染支持

其他框架

React
Vue.js
Angular
Nuxt.js
SvelteKit

项目初始化

1. 创建新项目

# 使用 create-amplify 快速开始
npm create amplify@latest

# 或者在现有项目中初始化
npm create amplify@latest -- --yes

2. 项目结构

your-app/
├── amplify/
│   ├── auth/
│   │   └── resource.ts          # 认证配置
│   ├── data/
│   │   └── resource.ts          # 数据模型和API
│   ├── storage/
│   │   └── resource.ts          # 存储配置
│   └── backend.ts               # 后端配置入口
├── amplify_outputs.json         # 自动生成的配置文件
└── package.json

核心功能配置

1. 认证 (Auth)

// amplify/auth/resource.ts
import { defineAuth } from '@aws-amplify/backend';

export const auth = defineAuth({
  loginWith: {
    email: true,
  },
  userAttributes: {
    givenName: {
      mutable: true,
      required: true,
    },
    familyName: {
      mutable: true,
      required: true,
    },
  },
});

2. 数据模型 (Data)

// amplify/data/resource.ts
import { type ClientSchema, a, defineData } from '@aws-amplify/backend';

const schema = a.schema({
  Todo: a
    .model({
      content: a.string(),
      done: a.boolean(),
    })
    .authorization((allow) => [allow.owner()]),
});

export type Schema = ClientSchema<typeof schema>;
export const data = defineData({
  schema,
  authorizationModes: {
    defaultAuthorizationMode: 'userPool',
  },
});

3. 存储 (Storage)

// amplify/storage/resource.ts
import { defineStorage } from '@aws-amplify/backend';

export const storage = defineStorage({
  name: 'myProjectFiles',
  access: (allow) => ({
    'profile-pictures/{entity_id}/*': [
      allow.entity('identity').to(['read', 'write', 'delete'])
    ],
    'public/*': [allow.guest.to(['read'])],
  })
});

4. 后端配置

// amplify/backend.ts
import { defineBackend } from '@aws-amplify/backend';
import { auth } from './auth/resource';
import { data } from './data/resource';
import { storage } from './storage/resource';

export const backend = defineBackend({
  auth,
  data,
  storage,
});

AI Kit 功能

1. 对话路由 (Conversation)

// amplify/data/resource.ts
const schema = a.schema({
  // 定义对话路由
  chat: a.conversation({
    aiModel: a.ai.model('Claude 3 Haiku'),
    systemPrompt: 'You are a helpful assistant.',
  })
  .authorization((allow) => [allow.owner()]),
});

2. 生成路由 (Generation)

const schema = a.schema({
  // 定义生成路由
  generateSummary: a.generation({
    aiModel: a.ai.model('Claude 3 Haiku'),
    systemPrompt: 'Summarize the following text:',
  })
  .authorization((allow) => [allow.authenticated()]),
});

3. 支持的AI模型

Claude 3 Haiku
Claude 3.5 Sonnet
Claude 3.5 Sonnet v2
Claude 3 Opus
Amazon Nova 系列模型

| 需要注意，AI Kit 在新模型的支持方面更新速度相对较慢, 并非所有 Bedrock 上的模型都可以使用tt。

Next.js 集成

1. 服务器端配置

// utils/amplifyServerUtils.ts
import { createServerRunner } from '@aws-amplify/adapter-nextjs';
import outputs from '../amplify_outputs.json';

export const { runWithAmplifyServerContext } = createServerRunner({
  config: outputs,
});

2. 客户端配置

// app/layout.tsx
'use client';

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

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

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

3. 服务器组件中的数据获取

// app/todos/page.tsx
import { generateClient } from 'aws-amplify/api/server';
import { cookies } from 'next/headers';
import { runWithAmplifyServerContext } from '@/utils/amplifyServerUtils';

export default async function TodosPage() {
  const todos = await runWithAmplifyServerContext({
    nextServerContext: { cookies },
    operation: async (contextSpec) => {
      const client = generateClient(contextSpec);
      
      const response = await client.graphql({
        query: listTodos,
      });
      
      return response.data.listTodos.items;
    },
  });

  return (
    <div>
      {todos.map((todo) => (
        <div key={todo.id}>{todo.content}</div>
      ))}
    </div>
  );
}

沙盒环境管理

1. 启动沙盒

# 启动监听模式（推荐开发使用）
npx ampx sandbox

# 使用自定义标识符
npx ampx sandbox --identifier my-sandbox

# 单次部署
npx ampx sandbox --once

2. 沙盒管理命令

# 删除沙盒
npx ampx sandbox delete --identifier my-sandbox

# 查看沙盒状态（通过CloudFormation）
aws cloudformation list-stacks \
  --region your-region \
  --stack-status-filter CREATE_COMPLETE UPDATE_COMPLETE \
  --query "StackSummaries[?starts_with(StackName, 'amplify-yourapp-')].{Name:StackName,Status:StackStatus}"

3. 多沙盒环境切换

# 切换到指定沙盒
npx ampx sandbox --identifier target-sandbox --once --outputs-out-dir .

# 这会更新 amplify_outputs.json 文件

部署到生产环境

1. 部署命令

# 部署到生产分支
npx ampx deploy --branch main

# 部署到特定环境
npx ampx deploy --branch staging

2. CI/CD 集成

# .github/workflows/deploy.yml
name: Deploy to Amplify
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npx ampx deploy --branch main
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

最佳实践

1. 开发工作流

个人沙盒: 每个开发者使用独立的沙盒标识符
功能分支: 为不同功能创建不同的沙盒环境
测试环境: 使用共享的测试沙盒进行集成测试
生产部署: 通过CI/CD管道部署到生产环境

2. 安全配置

// 使用环境变量管理敏感配置
const schema = a.schema({
  // 使用授权规则保护数据
  PrivateNote: a
    .model({
      content: a.string(),
    })
    .authorization((allow) => [
      allow.owner(),
      allow.groups(['admin']).to(['read', 'update', 'delete'])
    ]),
});

3. 性能优化

使用服务器组件减少客户端JavaScript
实现适当的缓存策略
优化GraphQL查询
使用CDN加速静态资源

故障排除

1. 常见问题

Library Not Configured 错误:

// 确保在应用早期调用 Amplify.configure
import { Amplify } from 'aws-amplify';
import outputs from './amplify_outputs.json';

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

沙盒部署失败:

# 检查CloudFormation事件
aws cloudformation describe-stack-events \
  --stack-name your-stack-name

权限问题:

# 检查当前AWS身份
aws sts get-caller-identity

# 确保有AmplifyBackendDeployFullAccess权限

2. 调试技巧

启用调试模式: npx ampx sandbox --debug
查看函数日志: npx ampx sandbox --stream-function-logs
检查amplify_outputs.json配置

参考资料：

iX.

take it easy .

概述