Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Menggunakan spesifikasi penerapan Amplify Hosting untuk mengonfigurasi keluaran build

Spesifikasi penerapan Amplify Hosting adalah spesifikasi berbasis sistem file yang mendefinisikan struktur direktori yang memfasilitasi penerapan ke Amplify Hosting. Kerangka kerja dapat menghasilkan struktur direktori yang diharapkan ini sebagai output dari perintah build-nya, memungkinkan kerangka kerja untuk memanfaatkan primitif layanan Amplify Hosting. Amplify Hosting memahami struktur bundel penerapan dan menerapkannya sesuai dengan itu.

Untuk demonstrasi video yang menjelaskan cara menggunakan spesifikasi penerapan, lihat Cara meng-host situs web apa pun yang menggunakan saluran AWS Amplify Amazon Web Services YouTube .

Berikut ini adalah contoh struktur folder yang Amplify harapkan untuk bundel penerapan. Pada tingkat tinggi, ia memiliki folder bernamastatic, folder bernama compute dan file manifes penyebaran bernamadeploy-manifest.json.

.amplify-hosting/
├── compute/
│   └── default/
│       ├── chunks/
│       │   └── app/
│       │       ├── _nuxt/
│       │       │   ├── index-xxx.mjs
│       │       │   └── index-styles.xxx.js
│       │       └── server.mjs
│       ├── node_modules/
│       └── server.js
├── static/
│   ├── css/
│   │   └── nuxt-google-fonts.css
│   ├── fonts/
│   │   ├── font.woff2
│   ├── _nuxt/
│   │   ├── builds/
│   │   │   └── latest.json
│   │   └── entry.xxx.js
│   ├── favicon.ico
│   └── robots.txt
└── deploy-manifest.json

Amplify dukungan primitif SSR

Spesifikasi penerapan Amplify Hosting mendefinisikan kontrak yang memetakan secara dekat ke primitif berikut.

.amplify-hosting/staticDirektori

Anda harus menempatkan semua file statis yang dapat diakses publik yang dimaksudkan untuk disajikan dari URL aplikasi di .amplify-hosting/static direktori. File di dalam direktori ini disajikan melalui aset statis primitif.

File statis dapat diakses di root (/) URL aplikasi tanpa perubahan apa pun pada konten, nama file, atau ekstensinya. Selain itu, subdirektori dipertahankan dalam struktur URL dan muncul sebelum nama file. Sebagai contoh, .amplify-hosting/static/favicon.ico akan dilayani dari https://myAppId.amplify-hostingapp.com/favicon.ico dan .amplify-hosting/static/_nuxt/main.js akan dilayani dari https://myAppId.amplify-hostingapp.com/_nuxt/main.js

Jika kerangka kerja mendukung kemampuan untuk memodifikasi jalur dasar aplikasi, itu harus menambahkan jalur dasar ke aset statis di dalam direktori. .amplify-hosting/static Misalnya, jika jalur dasarnya/folder1/folder2, maka output build untuk aset statis yang dipanggil main.css akan menjadi.amplify-hosting/static/folder1/folder2/main.css.

.amplify-hosting/computeDirektori

Sumber daya komputasi tunggal diwakili oleh satu subdirektori bernama yang default terkandung dalam direktori. .amplify-hosting/compute Jalannya adalah.amplify-hosting/compute/default. Sumber daya komputasi ini dipetakan ke komputasi primitif Amplify Hosting.

Isi default subdirektori harus sesuai dengan aturan berikut.

Amplify Hosting bundel dan gunakan semua file di dalam default subdirektori ke sumber daya komputasi yang disediakan. Setiap sumber daya komputasi dialokasikan 512 MB penyimpanan sementara. Penyimpanan ini tidak dibagi antara instance eksekusi, tetapi dibagi di antara pemanggilan berikutnya dalam instance eksekusi yang sama. Contoh eksekusi dibatasi hingga waktu eksekusi maksimum 15 menit, dan satu-satunya jalur yang dapat ditulis dalam instance eksekusi adalah direktori. /tmp Ukuran tidak terkompresi dari setiap bundel sumber daya komputasi tidak dapat melebihi 220 MB. Misalnya, .amplify/compute/default subdirektori tidak dapat melebihi 220 MB saat tidak dikompresi.

File .amplify-hosting/deploy-manifest.json

Gunakan deploy-manifest.json file untuk menyimpan detail konfigurasi dan metadata untuk penerapan. Minimal, deploy-manifest.json file harus menyertakan version atribut, routes atribut dengan rute catch-all yang ditentukan, dan framework atribut dengan metadata kerangka ditentukan.

Definisi objek berikut menunjukkan konfigurasi untuk manifes penerapan.

type DeployManifest = {
  version: 1;
  routes: Route[];
  computeResources?: ComputeResource[];
  imageSettings?: ImageSettings;
  framework: FrameworkMetadata;
};

Topik berikut menjelaskan detail dan penggunaan untuk setiap atribut dalam manifes penerapan.

Menggunakan atribut versi

versionAtribut mendefinisikan versi spesifikasi penerapan yang Anda terapkan. Saat ini, satu-satunya versi untuk spesifikasi penerapan Amplify Hosting adalah versi 1. Contoh JSON berikut menunjukkan penggunaan untuk atribut. version

"version": 1

Menggunakan atribut routes

routesAtribut ini memungkinkan kerangka kerja untuk memanfaatkan aturan perutean Amplify Hosting primitif. Aturan perutean menyediakan mekanisme untuk merutekan jalur permintaan masuk ke target tertentu dalam bundel penerapan. Aturan perutean hanya menentukan tujuan permintaan yang masuk dan diterapkan setelah permintaan diubah oleh aturan penulisan ulang dan pengalihan. Untuk informasi selengkapnya tentang cara Amplify Hosting menangani penulisan ulang dan pengalihan, lihat. Menyiapkan pengalihan dan penulisan ulang untuk aplikasi Amplify

Aturan perutean tidak menulis ulang atau mengubah permintaan. Jika permintaan masuk cocok dengan pola jalur untuk rute, permintaan akan dirutekan apa adanya ke target rute.

Aturan routing yang ditentukan dalam routes array harus sesuai dengan aturan berikut.

Definisi objek berikut menunjukkan konfigurasi untuk Route objek.

type Route = {
  path: string;
  target: Target;
  fallback?: Target;
}

Tabel berikut menjelaskan properti Route objek.

Definisi objek berikut menunjukkan konfigurasi untuk Target objek.

type Target = {
  kind: TargetKind;
  src?: string;
  cacheControl?: string;
}

Tabel berikut menjelaskan properti Target objek.

Definisi objek berikut menunjukkan penggunaan untuk TargetKind enumerasi.

enum TargetKind {
  Static = "Static",
  Compute = "Compute",
  ImageOptimization = "ImageOptimization"
}

Daftar berikut menentukan nilai yang valid untuk TargetKind enum.

Contoh JSON berikut menunjukkan penggunaan untuk routes atribut dengan beberapa aturan routing ditentukan.

"routes": [
    {
      "path": "/_nuxt/image",
      "target": {
        "kind": "ImageOptimization",
        "cacheControl": "public, max-age=3600, immutable"
      }
    },
    {
      "path": "/_nuxt/builds/meta/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/_nuxt/builds/*",
      "target": {
        "cacheControl": "public, max-age=1, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/_nuxt/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/*.*",
      "target": {
        "kind": "Static"
      },
      "fallback": {
        "kind": "Compute",
        "src": "default"
      }
    },
    {
      "path": "/*",
      "target": {
        "kind": "Compute",
        "src": "default"
      }
    }
  ]

Untuk informasi selengkapnya tentang menentukan aturan perutean dalam manifes penerapan Anda, lihat Praktik terbaik untuk mengonfigurasi aturan perutean

Menggunakan atribut ComputereSources

computeResourcesAtribut ini memungkinkan kerangka kerja untuk menyediakan metadata tentang sumber daya komputasi yang disediakan. Setiap sumber daya komputasi harus memiliki rute yang sesuai yang terkait dengannya.

Definisi objek berikut menunjukkan penggunaan untuk ComputeResource objek.

type ComputeResource = {
  name: string;
  runtime: ComputeRuntime;
  entrypoint: string;
};
 
type ComputeRuntime = 'nodejs20.x' | 'nodejs22.x';

Tabel berikut menjelaskan properti ComputeResource objek.

Jika Anda memiliki struktur direktori yang terlihat seperti berikut ini.

.amplify-hosting
|---compute
|   |---default
|       |---index.js

JSON untuk computeResource atribut akan terlihat seperti berikut ini.

"computeResources": [
    {
      "name": "default",
      "runtime": "nodejs20.x",
      "entrypoint": "index.js",
    }
  ]

Menggunakan atribut ImageSettings

imageSettingsAtribut ini memungkinkan kerangka kerja untuk menyesuaikan perilaku primitif pengoptimalan gambar, yang menyediakan optimasi gambar sesuai permintaan saat runtime.

Definisi objek berikut menunjukkan penggunaan untuk ImageSettings objek.

type ImageSettings = {
  sizes: number[];
  domains: string[];
  remotePatterns: RemotePattern[];
  formats: ImageFormat[];
  minumumCacheTTL: number;
  dangerouslyAllowSVG: boolean;
};
 
type ImageFormat = 'image/avif' | 'image/webp' | 'image/png' | 'image/jpeg';

Tabel berikut menjelaskan properti ImageSettings objek.

Definisi objek berikut menunjukkan penggunaan untuk RemotePattern objek.

type RemotePattern = {
  protocol?: 'https';
  hostname: string;
  port?: string;
  pathname?: string;
}

Tabel berikut menjelaskan properti RemotePattern objek.

Contoh berikut menunjukkan imageSettings atribut.

"imageSettings": { 
    "sizes": [
      100,
      200
    ],
    "domains": [
      "example.com"
    ],
    "remotePatterns": [
      {
        "protocol": "https",
        "hostname": "example.com",
        "port": "",
        "pathname": "/**",
      }
    ],
    "formats": [
      "image/webp"
    ],
    "minumumCacheTTL": 60,
    "dangerouslyAllowSVG": false
  }

Menggunakan atribut framework

Gunakan framework atribut untuk menentukan kerangka metadata.

Definisi objek berikut menunjukkan konfigurasi untuk FrameworkMetadata objek.

type FrameworkMetadata = {
  name: string;
  version: string;
}

Tabel berikut menjelaskan properti FrameworkMetadata objek.

Praktik terbaik untuk mengonfigurasi aturan perutean

Aturan perutean menyediakan mekanisme untuk merutekan jalur permintaan masuk ke target tertentu dalam bundel penerapan. Dalam bundel penerapan, pembuat kerangka kerja dapat memancarkan file ke output build yang diterapkan ke salah satu target berikut:

Penulis kerangka kerja juga menyediakan serangkaian aturan perutean dalam file manifes penyebaran. Setiap aturan dalam array dicocokkan dengan permintaan masuk dalam urutan traversal berurutan, sampai ada kecocokan. Ketika ada aturan yang cocok, permintaan dirutekan ke target yang ditentukan dalam aturan pencocokan. Secara opsional, target fallback dapat ditentukan untuk setiap aturan. Jika target asli mengembalikan kesalahan 404, permintaan dirutekan ke target fallback.

Spesifikasi penerapan mensyaratkan aturan terakhir dalam urutan traversal menjadi aturan catch-all. Aturan catch-all ditentukan dengan jalur. /* Jika permintaan masuk tidak cocok dengan rute sebelumnya dalam larik aturan perutean, permintaan akan dirutekan ke target aturan catch-all.

Untuk kerangka kerja SSR sepertiNuxt.js, target aturan catch-all harus primitif komputasi. Ini karena aplikasi SSR memiliki halaman yang dirender sisi server dengan rute yang tidak dapat diprediksi pada waktu pembuatan. Misalnya, jika Nuxt.js aplikasi memiliki halaman di /blog/[slug] mana [slug] adalah parameter rute dinamis. Target aturan catch-all adalah satu-satunya cara untuk merutekan permintaan ke halaman ini.

Sebaliknya, pola jalur tertentu dapat digunakan untuk menargetkan rute yang diketahui pada waktu pembuatan. Misalnya, Nuxt.js melayani aset statis dari /_nuxt jalur. Ini berarti bahwa /_nuxt/* jalur dapat ditargetkan oleh aturan perutean tertentu yang merutekan permintaan ke aset statis primitif.

Perutean folder publik

Sebagian besar kerangka kerja SSR menyediakan kemampuan untuk melayani aset statis yang dapat berubah dari folder. public File seperti favicon.ico dan robots.txt biasanya disimpan di dalam public folder dan disajikan dari URL root aplikasi. Misalnya, favicon.ico file dilayani darihttps://example.com/favicon.ico. Perhatikan bahwa tidak ada pola jalur yang dapat diprediksi untuk file-file ini. Mereka hampir seluruhnya ditentukan oleh nama file. Satu-satunya cara untuk menargetkan file di dalam public folder adalah dengan menggunakan rute catch-all. Namun, target rute catch-all harus primitif komputasi.

Kami merekomendasikan salah satu pendekatan berikut untuk mengelola public folder Anda.

Tangkap semua perutean fallback

Untuk kerangka kerja SSR sepertiNuxt.js, di mana rute catch-all ditentukan untuk target primitif komputasi, penulis kerangka kerja mungkin mempertimbangkan untuk menentukan fallback statis untuk rute catch-all untuk menyelesaikan masalah perutean folder. public Namun, jenis aturan perutean ini merusak 404 halaman yang dirender sisi server. Misalnya, jika pengguna akhir mengunjungi halaman yang tidak ada, aplikasi akan merender halaman 404 dengan kode status 404. Namun, jika rute catch-all memiliki fallback statis, halaman 404 tidak akan dirender. Sebaliknya, permintaan kembali ke primitif statis dan masih berakhir dengan kode status 404, tetapi halaman 404 tidak dirender.

{
    "path": "/*",
    "target": {
        "kind": "Compute",
        "src": "default"
    },
    "fallback": {
        "kind": "Static"
    }
}

Perutean jalur dasar

Kerangka kerja yang menawarkan kemampuan untuk memodifikasi jalur dasar aplikasi diharapkan untuk menambahkan jalur dasar ke aset statis di dalam direktori. .amplify-hosting/static Misalnya, jika jalur dasarnya/folder1/folder2, maka output build untuk aset statis yang disebut main.css akan menjadi.amplify-hosting/static/folder1/folder2/main.css.

Ini berarti bahwa aturan routing juga perlu diperbarui untuk mencerminkan jalur dasar. Misalnya, jika jalur dasarnya/folder1/folder2, maka aturan perutean untuk aset statis di public folder akan terlihat seperti berikut ini.

{
    "path": "/folder1/folder2/*.*",
    "target": {
        "kind": "Static"
    }
}

Demikian pula, rute sisi server juga perlu memiliki jalur dasar yang ditambahkan ke mereka. Misalnya, jika jalur dasarnya/folder1/folder2, maka aturan perutean untuk /api rute akan terlihat seperti berikut.

{
    "path": "/folder1/folder2/api/*",
    "target": {
        "kind": "Compute",
        "src": "default"
    }
}

Namun, jalur dasar tidak boleh dilanjutkan ke rute catch-all. Misalnya, jika jalur dasarnya/folder1/folder2, maka rute catch-all akan tetap seperti berikut ini.

{
    "path": "/*",
    "target": {
        "kind": "Compute",
        "src": "default"
    }
}

Contoh rute Nuxt.js

Berikut ini adalah deploy-manifest.json file contoh untuk aplikasi Nuxt yang menunjukkan cara menentukan aturan routing.

{
  "version": 1,
  "routes": [
    {
      "path": "/_nuxt/image",
      "target": {
        "kind": "ImageOptimization",
        "cacheControl": "public, max-age=3600, immutable"
      }
    },
    {
      "path": "/_nuxt/builds/meta/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/_nuxt/builds/*",
      "target": {
        "cacheControl": "public, max-age=1, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/_nuxt/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/*.*",
      "target": {
        "kind": "Static"
      },
      "fallback": {
        "kind": "Compute",
        "src": "default"
      }
    },
    {
      "path": "/*",
      "target": {
        "kind": "Compute",
        "src": "default"
      }
    }
  ],
  "computeResources": [
    {
      "name": "default",
      "entrypoint": "server.js",
      "runtime": "nodejs22.x"
    }
  ],
  "framework": {
    "name": "nuxt",
    "version": "3.8.1"
  }
}

Berikut ini adalah deploy-manifest.json file contoh untuk Nuxt yang menunjukkan cara menentukan aturan routing termasuk jalur dasar.

{
  "version": 1,
  "routes": [
    {
      "path": "/base-path/_nuxt/image",
      "target": {
        "kind": "ImageOptimization",
        "cacheControl": "public, max-age=3600, immutable"
      }
    },
    {
      "path": "/base-path/_nuxt/builds/meta/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/base-path/_nuxt/builds/*",
      "target": {
        "cacheControl": "public, max-age=1, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/base-path/_nuxt/*",
      "target": {
        "cacheControl": "public, max-age=31536000, immutable",
        "kind": "Static"
      }
    },
    {
      "path": "/base-path/*.*",
      "target": {
        "kind": "Static"
      },
      "fallback": {
        "kind": "Compute",
        "src": "default"
      }
    },
    {
      "path": "/*",
      "target": {
        "kind": "Compute",
        "src": "default"
      }
    }
  ],
  "computeResources": [
    {
      "name": "default",
      "entrypoint": "server.js",
      "runtime": "nodejs22.x"
    }
  ],
  "framework": {
    "name": "nuxt",
    "version": "3.8.1"
  }
}

Untuk informasi selengkapnya tentang penggunaan routes atribut, lihatMenggunakan atribut routes.