Deploy Next.js lên AWS Amplify — Hướng dẫn thực chiến

00

Chuẩn bị trước khi bắt đầu

Trước khi deploy, đảm bảo bạn đã có đủ những thứ sau:

Tài khoản AWS (free tier là đủ để thử)
Repo Next.js trên GitHub (public hoặc private đều được)
Node.js 18+ trong dự án

💡

AWS Amplify Hosting hỗ trợ cả App Router lẫn Pages Router. Bài này dùng App Router (Next.js 13+). Nếu bạn dùng Pages Router, các bước hoàn toàn tương tự.

Kiểm tra package.json có đủ scripts cần thiết:

package.json

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "engines": {
    "node": ">=18.0.0"
  }
}

01

Kết nối GitHub với Amplify

Truy cập AWS Console → AWS Amplify → Create new app. Giao diện sẽ yêu cầu chọn nguồn code:

console.aws.amazon.com/amplify/create

awsServicesAmplify

Deploy your app

Connect a Git repository or deploy manually.

📦 Choose source

🐙

GitHub

Connect via OAuth

🦊

GitLab

Connect via OAuth

🪣

Bitbucket

Connect via OAuth

Sau khi xác thực OAuth với GitHub, Amplify liệt kê toàn bộ repo bạn có quyền truy cập. Chọn repo và branch muốn deploy:

console.aws.amazon.com/amplify/create/repo

awsAmplify

Select repository

Choose the repository and branch you want to deploy.

Repository

Branch

My app is a monorepo

⚠️

Repo private: Nếu repo là private, bạn cần cấp quyền cho Amplify app trên trang cài đặt GitHub OAuth. Amplify sẽ redirect bạn tới đó tự động.

02

Cấu hình Build Settings

Amplify tự động phát hiện Next.js và sinh ra amplify.yml. Bạn có thể dùng mặc định hoặc tuỳ chỉnh trực tiếp trên console:

console.aws.amazon.com/amplify/create/build

awsAmplify

App build specification

preBuild

build

postBuild

artifacts

# amplify.yml — auto-generated for Next.js
version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: .next
    files:
      - "**/*"
  cache:
    paths:
      - node_modules/**/*
      - .next/cache/**/*

Commit file amplify.yml vào root repo để override config trên console:

amplify.yml

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: .next
    files:
      - "**/*"
  cache:
    paths:
      - node_modules/**/*
      - .next/cache/**/*  # cache build để deploy nhanh hơn ~50%

✅

Cache .next/cache giúp các lần build tiếp theo nhanh hơn ~40–60% nhờ Next.js incremental compilation.

03

Cấu hình biến môi trường

Vào App settings → Environment variables. Amplify hỗ trợ gán giá trị khác nhau cho từng branch.

console.aws.amazon.com/amplify/app/xxx/environment-variables

awsAmplify › App settings

Environment variables

Variables are available during build and at runtime via process.env

🌿 Branch: main (production)

KeyValue

NEXT_PUBLIC_API_URL

DATABASE_URL •••••••••••••••• secret

NEXTAUTH_SECRET •••••••••••••••• secret

NEXTAUTH_URL

Quy tắc đặt tên biến môi trường trong Next.js

.env.example

# ✅ Expose ra client (browser) — PHẢI có prefix NEXT_PUBLIC_
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

# ✅ Server-only — chỉ dùng trong Server Components / API Routes
DATABASE_URL=postgresql://user:pass@host/db
NEXTAUTH_SECRET=your-secret-here
REDIS_URL=redis://your-endpoint:6379

⚠️

Không commit .env.local lên Git. Chỉ commit .env.example để document. Tất cả giá trị thật khai báo trực tiếp trên Amplify Console.

Env khác nhau theo branch

per-branch env

# Branch: main (production)
NEXT_PUBLIC_API_URL = https://api.yourdomain.com

# Branch: develop (staging)
NEXT_PUBLIC_API_URL = https://api-staging.yourdomain.com

04

CI/CD tự động

Mỗi lần git push lên branch đã cấu hình, Amplify tự động trigger build mới. Pipeline gồm 4 giai đoạn:

console.aws.amazon.com/amplify/app/xxx/deployments

awsAmplify › Deployments

Build #14 — main

Triggered by push · a3f9c12 "feat: add auth pages"

⏳ In progress

✓

Provision

0:08

›

✓

Build

1:42

›

⚙

Deploy

running

›

○

Verify

—

14:22:31 ✔ npm ci completed (cached)
14:22:33 ▶ Running npm run build
14:23:51 ✔ Build complete — 78 pages
14:23:52 ▶ Deploying to CDN...

1

Auto-build branch `main` (production)

Mặc định đã bật. Mỗi push lên main = 1 deploy mới.

2

Thêm branch `develop` cho staging

Vào Hosting → Branches → Connect branch, chọn develop. Amplify tạo URL riêng: develop.xxxxxx.amplifyapp.com

3

Preview URL cho Pull Request (tuỳ chọn)

Bật Previews trong App settings — Amplify tự tạo URL riêng cho mỗi PR.

preview url

https://pr-42.xxxxxx.amplifyapp.com

Trigger build thủ công qua webhook

bash

# Lấy URL từ: App settings → Build notifications → Incoming webhooks
curl -X POST \
  "https://webhooks.amplify.us-east-1.amazonaws.com/prod/webhooks?id=xxxx&token=yyyy"

05

Gắn Custom Domain

Amplify tích hợp AWS Certificate Manager (ACM) để cấp SSL miễn phí. Vào Hosting → Custom domains → Add domain:

console.aws.amazon.com/amplify/app/xxx/domain-management

awsAmplify › Custom domains

Add domain

Domain name

Subdomains

yourdomain.com → main branch

www.yourdomain.com → main branch

SSL — Auto-provisioned (free)

AWS Certificate Manager

DNS records cần thêm

Record 1 — SSL Validation

TypeCNAME

Name_abc123def.yourdomain.com

Value_xyz789.acm-validations.aws

Record 2 — Traffic routing

TypeCNAME

Namewww

Valuemain.xxxxxx.amplifyapp.com

1

Nhập domain vào Amplify

Amplify hiển thị 2 CNAME record cần thêm vào DNS provider.

2

Cập nhật DNS tại nhà cung cấp domain

Vào Namecheap / Cloudflare / GoDaddy → thêm đúng 2 CNAME record. Record 1 để verify SSL, record 2 để trỏ traffic.

3

Chờ SSL propagate (15 phút – 48 giờ)

Thường 15–30 phút nếu dùng Cloudflare. Amplify tự cấp SSL và chuyển trạng thái:

Pending

→

Available

💡

Nếu domain đang dùng Cloudflare, tắt tính năng Proxy (cam) cho CNAME record trong lúc verify SSL — chuyển về DNS only (xám). Sau khi verify xong, bật lại nếu muốn.

06

Xử lý lỗi thường gặp

Lỗi 1: Build fail — "Module not found"

Thường do package chưa install đúng. Dùng npm ci thay vì npm install và kiểm tra Node version:

amplify.yml — fix

preBuild:
  commands:
    - node --version   # kiểm tra version trước
    - npm ci          # luôn dùng ci thay vì install

Lỗi 2: Environment variable undefined ở runtime

Biến không có prefix NEXT_PUBLIC_ chỉ available ở server-side. Gọi ở Client Component sẽ là undefined.

typescript

// ❌ Sai — DATABASE_URL không có ở client
'use client'
const db = process.env.DATABASE_URL

// ✅ Đúng — chỉ dùng trong Server Component / Route Handler
// app/api/route.ts
export async function GET() {
  const db = process.env.DATABASE_URL // ✅ ok
}

Lỗi 3: Node version không khớp

Amplify mặc định dùng Node 16. Nếu dự án cần Node 18+, thêm vào amplify.yml hoặc set trong Build image settings:

amplify.yml

preBuild:
  commands:
    - nvm use 18
    - npm ci

Lỗi 4: 404 khi refresh trang

Với App Router thì Amplify tự xử lý. Nếu cần, thêm vào next.config.js:

next.config.js

const nextConfig = {
  output: 'standalone'  // tối ưu bundle size, Amplify hỗ trợ
}
module.exports = nextConfig

Chuẩn bị trước khi bắt đầu

Kết nối GitHub với Amplify

Cấu hình Build Settings

Cấu hình biến môi trường

Quy tắc đặt tên biến môi trường trong Next.js

Env khác nhau theo branch

CI/CD tự động

Auto-build branch main (production)

Thêm branch develop cho staging

Preview URL cho Pull Request (tuỳ chọn)

Trigger build thủ công qua webhook

Gắn Custom Domain

Nhập domain vào Amplify

Cập nhật DNS tại nhà cung cấp domain

Chờ SSL propagate (15 phút – 48 giờ)

Xử lý lỗi thường gặp

Lỗi 1: Build fail — "Module not found"

Lỗi 2: Environment variable undefined ở runtime

Lỗi 3: Node version không khớp

Lỗi 4: 404 khi refresh trang

Auto-build branch `main` (production)

Thêm branch `develop` cho staging