Runtime Node.js

Runtime Node.js adalah stack software yang bertanggung jawab untuk menginstal kode aplikasi dan dependensi Anda, kemudian menjalankan aplikasi tersebut di lingkungan fleksibel.

  • Versi 18 dan yang lebih baru di-build menggunakan buildpacks, yang mengharuskan Anda memilih sistem operasi di file app.yaml. Misalnya, untuk menggunakan Node.js 20, Anda harus menentukan Ubuntu 22 sebagai sistem operasinya.

  • Versi 16 dan yang lebih lama dibangun menggunakan Docker.

  • Mesin Node.js default menggunakan rilis LTS terbaru.

Untuk daftar lengkap versi Node.js yang didukung, dan versi Ubuntu yang sesuai, lihat Jadwal dukungan runtime.

Pengelola paket

Selama deployment, runtime menggunakan pengelola paket npm, yarn, atau Pnpm untuk menginstal dependensi dan memulai aplikasi. Pengelola paket ditetapkan dengan logika berikut:

  • Pengelola paket default adalah npm.
  • Jika file yarn.lock ada di direktori utama aplikasi Anda, runtime akan menggunakan pengelola paket yarn.
  • Khusus untuk runtime Node.js versi 18 dan versi 20, jika file pnpm-lock.yaml ada dalam direktori root aplikasi Anda, runtime akan menggunakan pengelola paket Pnpm.
  • Jika package-lock.json, dan yarn.lock atau pnpm-lock.yaml ada, deployment Anda akan gagal dengan error. Jika memerlukan file package-lock.json, Anda harus menentukan file pengelola paket lainnya di bagian skip_files dari file app.yaml untuk menentukan pengelola paket mana yang akan digunakan.

Memilih versi Node.js

Versi runtime baru

Untuk runtime Node.js versi 18 dan yang lebih baru, Anda harus menyertakan setelan runtime_config dan operating_system di file app.yaml untuk menentukan sistem operasi.

Untuk menggunakan runtime baru, Anda harus menginstal gcloud CLI versi 420.0.0 atau yang lebih baru. Anda dapat memperbarui alat CLI dengan menjalankan perintah gcloud components update. Untuk melihat versi yang diinstal, Anda dapat menjalankan perintah gcloud version.

Atau, tentukan versi berdasarkan:

  • Menambahkan setelan runtime_version di file app.yaml Anda. Secara default, versi Node.js terbaru digunakan jika setelan runtime_version tidak ditentukan. Misalnya,

    • Untuk menentukan Node.js 20 di Ubuntu 22:
      runtime: nodejs
  env: flex

  runtime_config:
      operating_system: "ubuntu22"
      runtime_version: "20"
    • Untuk menentukan versi Node.js terbaru yang didukung di Ubuntu 22:
      runtime: nodejs
  env: flex

  runtime_config:
      operating_system: "ubuntu22"

  • Menyertakan versi Node.js apa pun dalam file package.json aplikasi Anda menggunakan kolom engines. Perhatikan bahwa saat Anda menggunakan kolom engines untuk menentukan versi, setelan runtime_version akan lebih diutamakan. Untuk mencegah kerusakan yang tidak terduga, sebaiknya tentukan versi Node.js di kolom engines. Misalnya,

      {
    "engines": {
      "node": "20.x"
    }
  }

    Properti engines.node dapat berupa rentang semver. Jika Anda menentukannya, runtime akan mendownload dan menginstal Node.js versi terbaru yang cocok dengan rentang semver. Jika tidak ditemukan kecocokan, aplikasi akan gagal di-deploy dan runtime akan menampilkan pesan error.

Versi runtime sebelumnya

Untuk runtime Node.js versi 16 dan yang lebih lama, tentukan versi dalam file package.json aplikasi Anda menggunakan engines.

Contoh berikut mengonfigurasi runtime untuk menggunakan rilis Node 9 terbaru.

{
  "engines": {
    "node": "9.x"
  }
}

Properti engines.node dapat berupa rentang semver. Jika Anda menentukannya, runtime akan mendownload dan menginstal Node.js versi terbaru yang cocok dengan rentang semver. Jika tidak ditemukan kecocokan, aplikasi akan gagal di-deploy dan runtime akan menampilkan pesan error.

Versi pengelola paket

Image runtime bertujuan untuk menggunakan rilis yarn terbaru dan rilis npm yang tersedia dalam rilis Node.js LTS terbaru.

Anda dapat menentukan versi pengelola paket yang berbeda untuk digunakan dalam file package.json aplikasi menggunakan kolom engines. Dalam hal ini, runtime akan memastikan bahwa pengelola paket yang digunakan untuk deployment memiliki versi yang sesuai dengan spesifikasi yang tercantum di kolom engines.

Jika spesifikasi versi yarn dan npm diberikan, hanya pengelola paket yang digunakan untuk deployment yang akan diupdate, jika diperlukan. Hal ini menghemat waktu deployment dengan tidak menginstal pengelola paket versi kustom jika sedang tidak digunakan untuk men-deploy aplikasi Anda.

Contoh berikut mengonfigurasi runtime untuk menggunakan versi kustom npm:

{
  "engines": {
    "npm": "5.x"
  }
}

Contoh berikutnya mengonfigurasi runtime untuk menggunakan versi kustom yarn:

{
  "engines": {
    "yarn": ">=1.0.0 <2.0.0"
  }
}

Properti engines.npm dan engines.yarn dapat berupa rentang semver.

Dependensi

Selama deployment, runtime akan menggunakan pengelola paket npm atau yarn untuk menginstal dependensi dengan menjalankan npm install atau yarn install. Lihat bagian Pengelola Paket untuk informasi selengkapnya tentang cara runtime memilih pengelola paket yang akan digunakan.

Selain itu, untuk informasi lebih lanjut tentang cara mengelola paket Node.js di Google App Engine, lihat Menggunakan Library Node.js.

Untuk mengaktifkan penggunaan paket Node.js yang memerlukan ekstensi native, paket Ubuntu berikut sudah diinstal sebelumnya dalam image Docker.

  • build-essential
  • ca-certificates
  • curl
  • git
  • imagemagick
  • libkrb5-dev
  • netbase
  • python

Jika aplikasi memerlukan dependensi tingkat sistem operasi tambahan, Anda harus menggunakan runtime kustom berdasarkan runtime ini untuk menginstal paket yang sesuai.

Skrip build NPM

Untuk runtime Node.js versi 18 dan yang lebih baru, lingkungan runtime akan mengeksekusi npm run build jika skrip build terdeteksi di package.json secara default. Jika memerlukan kontrol tambahan atas langkah-langkah build sebelum memulai aplikasi, Anda dapat memberikan langkah build kustom dengan menambahkan skrip gcp-build ke file package.json.

Untuk mencegah build menjalankan skrip npm run build, Anda harus:

  • Menambahkan skrip gcp-build dengan nilai kosong di file package.json Anda: "gcp-build":"".

  • Menambahkan variabel lingkungan build GOOGLE_NODE_RUN_SCRIPTS dengan nilai kosong di file app.yaml.

    build_env_variables:
  GOOGLE_NODE_RUN_SCRIPTS: ''
Untuk mengetahui detail tentang cara menentukan variabel lingkungan build, lihat bagian build_env_variables dalam file app.yaml.

Proses mulai aplikasi

Runtime memulai aplikasi Anda menggunakan npm start, yang menggunakan perintah yang ditentukan dalam package.json. Contoh:

"scripts": {
  "start": "node app.js"
}

Skrip awal Anda harus memulai server web yang merespons permintaan HTTP di port yang ditentukan oleh variabel lingkungan PORT, biasanya 8080.

Memperpanjang runtime

Anda dapat menggunakan runtime kustom untuk menambahkan fungsi lain pada aplikasi Node.js yang berjalan di lingkungan fleksibel App Engine. Untuk mengonfigurasi runtime kustom, ganti baris berikut di file app.yaml Anda:

runtime: nodejs

dengan baris ini:

runtime: custom

Anda juga harus menambahkan file Dockerfile dan .dockerignore dalam direktori yang sama yang berisi file app.yaml.

Buka dokumentasi Runtime kustom untuk mempelajari cara menentukan Dockerfile dalam runtime kustom.

HTTPS dan proxy penerusan

App Engine menghentikan koneksi HTTPS di load balancer dan meneruskan permintaan ke aplikasi Anda. Beberapa aplikasi perlu menentukan IP dan protokol permintaan asli. Alamat IP pengguna tersedia di header X-Forwarded-For standar. Aplikasi yang memerlukan informasi ini harus mengonfigurasi framework webnya untuk memercayai proxy.

Dengan Express.js, gunakan setelan trust proxy:

app.set('trust proxy', true);

Untuk informasi tentang cara menerapkan koneksi HTTPS, lihat Cara Menangani Permintaan.

Variabel lingkungan

Variabel lingkungan berikut ditetapkan oleh lingkungan runtime:

Variabel lingkungan Deskripsi
GAE_INSTANCE Nama instance saat ini.
GAE_MEMORY_MB Jumlah memori yang tersedia untuk proses aplikasi.
GAE_SERVICE Nama layanan ditentukan dalam file app.yaml aplikasi Anda, atau jika tidak ada nama layanan yang ditentukan, namanya akan ditetapkan ke default.
GAE_VERSION Label versi aplikasi saat ini.
GOOGLE_CLOUD_PROJECT Project ID yang terkait dengan aplikasi Anda, yang terlihat di Konsol Google Cloud
NODE_ENV Saat aplikasi Anda di-deploy, nilainya adalah production.
PORT Port yang akan menerima permintaan HTTP. Tetapkan ke 8080.

Anda dapat menetapkan variabel lingkungan tambahan dengan app.yaml.

Server metadata

Setiap instance aplikasi Anda dapat menggunakan server metadata Compute Engine untuk melakukan kueri informasi tentang instance, termasuk nama host, alamat IP eksternal, ID instance, metadata kustom, dan informasi akun layanan. Dengan App Engine, Anda tidak dapat menetapkan metadata kustom untuk setiap instance, tetapi Anda dapat menetapkan metadata kustom tingkat project serta membacanya dari instance App Engine dan Compute Engine singkat ini.

Fungsi contoh ini menggunakan server metadata untuk mendapatkan alamat IP eksternal instance untuk runtime Node.js versi 16 dan yang lebih lama, serta versi 18 dan yang lebih baru. Perlu diperhatikan bahwa Anda harus mengupdate app.yaml untuk menggunakan versi baru. Baca runtime Node.js untuk mengetahui informasi selengkapnya tentang penggunaan versi yang lebih baru.

const express = require('express');
const fetch = require('node-fetch');

const app = express();
app.enable('trust proxy');

const METADATA_NETWORK_INTERFACE_URL =
  'http://metadata/computeMetadata/v1/' +
  '/instance/network-interfaces/0/access-configs/0/external-ip';

const getExternalIp = async () => {
  const options = {
    headers: {
      'Metadata-Flavor': 'Google',
    },
    json: true,
  };

  try {
    const response = await fetch(METADATA_NETWORK_INTERFACE_URL, options);
    const ip = await response.json();
    return ip;
  } catch (err) {
    console.log('Error while talking to metadata server, assuming localhost');
    return 'localhost';
  }
};

app.get('/', async (req, res, next) => {
  try {
    const externalIp = await getExternalIp();
    res.status(200).send(`External IP: ${externalIp}`).end();
  } catch (err) {
    next(err);
  }
});

const PORT = parseInt(process.env.PORT) || 8080;
app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
  console.log('Press Ctrl+C to quit.');
});