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 Node.js

Node.js 24 (pratinjau) menggunakan buildpack. Mesin Node.js default menggunakan rilis LTS terbaru. Untuk mengetahui daftar lengkap versi Node.js yang didukung, dan versi Ubuntu yang sesuai, lihat Jadwal dukungan runtime.

Untuk menggunakan versi Node.js yang didukung, Anda harus:

  • Instal 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, jalankan perintah gcloud version.

  • Sertakan setelan runtime_config dan operating_system dalam file app.yaml untuk menentukan sistem operasi.

  • 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. Contoh:

      • Untuk menentukan Node.js 24 (pratinjau) di Ubuntu 24:

          runtime: nodejs
  env: flex

  runtime_config:
      operating_system: "ubuntu24"
      runtime_version: "24"

      • Untuk menentukan versi Node.js terbaru yang didukung di Ubuntu 24:

          runtime: nodejs
  env: flex

  runtime_config:
      operating_system: "ubuntu24"

        Setelan runtime_version mendukung semver.

    • Menyertakan versi Node.js terbaru yang didukung dalam file package.json aplikasi Anda menggunakan kolom engines. 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, beserta runtime_version. Contoh:

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

      Properti engines.node dapat berupa rentang semver. Jika Anda menentukan properti ini, 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 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:

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

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

Dukungan untuk runtime Node.js lainnya

Jika perlu menggunakan versi Node.js yang tidak didukung, Anda dapat membuat runtime kustom dan memilih image dasar yang valid dengan versi Node.js yang Anda butuhkan.

Untuk image dasar yang disediakan Google atau image dasar Node.js Docker, lihat Membangun runtime kustom.

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 Node.js versi 18 dan yang lebih baru, jika file pnpm-lock.yaml ada di 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.

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 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 pada 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 mengkueri 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.

import express from 'express';
import fetch from '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.');
});