Menyiapkan Lingkungan Pengembangan

Panduan ini memandu Anda menyiapkan lingkungan pengembangan Electron untuk pengembangan Windows API. Anda akan menginstal alat yang diperlukan, menginisialisasi project, dan mengonfigurasi Windows SDK.

Prasyarat

Sebelum memulai, pastikan Anda memiliki:

  • Windows 11
  • Node.js - winget install OpenJS.NodeJS --source winget
  • .NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
  • Visual Studio dengan Paket Kerja Desktop Native - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

Langkah 1: Buat Aplikasi Electron Baru

Kita akan mulai dengan aplikasi Electron baru menggunakan Electron Forge, yang menyediakan alat dan dukungan pengemasan yang sangat baik. Jika Anda memulai dari aplikasi yang sudah ada, Anda dapat melewati langkah ini.

npm create electron-app@latest my-windows-app
cd my-windows-app

Ketika diminta oleh Electron Forge:

  • Bunder: Pilih Tidak Ada (disarankan — addon asli berfungsi tanpa konfigurasi tambahan)
  • Bahasa: Pilih JavaScript (panduan ini menggunakan JS; TypeScript juga berfungsi)
  • Versi elektron: Pilih terbaru
  • Menginisialisasi git: Preferensi Anda

Verifikasi bahwa aplikasi berjalan:

npm start

Anda seharusnya melihat jendela default Electron Forge. Tutup dan mari kita tambahkan kemampuan Windows!

Langkah 2: Instal winapp CLI

Alur kerja Electron memerlukan paket npm (@microsoft/winappcli) daripada CLI mandiri yang diinstal dari winget. Paket npm mencakup helper khusus Node.js (seperti add-electron-debug-identity dan create-addon) yang tidak tersedia di CLI asli. Jika Anda sudah menginstal winapp dari winget, tidak apa-apa - paket npm menambahkan alat khusus Node.jssebagai dependensi proyek dan tidak akan bertentangan dengan penginstalan sistem Anda.

npm install --save-dev @microsoft/winappcli

Langkah 3: Menginisialisasi project untuk pengembangan Windows

Perintah winapp init menyiapkan semua yang Anda butuhkan dalam satu langkah: manifes aplikasi, aset, dan SDK.

Jalankan perintah berikut dan ikuti perintah:

npx winapp init .

Ketika diminta:

  • Nama paket: Tekan Enter untuk menerima default (my-windows-app)
  • Nama penerbit: Tekan Enter untuk menerima pengaturan standar atau masukkan nama Anda
  • Versi: Tekan Enter untuk menerima 1.0.0.0
  • Titik masuk: Tekan Enter untuk menerima default (my-windows-app.exe)
  • SDK Penyiapan: Pilih "SDK Stabil"
  • Menambahkan pengikatan JS/TypeScript: Tekan Enter untuk menerima default (Ya) untuk menghasilkan pengikatan JS untuk API SDK Aplikasi Windows

Nota

--use-defaults dan init non-interaktif melewati binding JS kecuali Anda menyertakan --add-js-bindings. Jalankan interaktif npx winapp init . untuk ikut serta pada perintah, atau gunakan npx winapp init . --use-defaults --add-js-bindings untuk otomatisasi.

Apa yang Dilakukan winapp init?

Perintah ini menyiapkan semua yang Anda butuhkan untuk pengembangan Windows:

  1. .winapp/ Membuat folder yang berisi:

    • Header dan pustaka dari SDK Windows
    • Header dan pustaka dari SDK Aplikasi Windows
    • Paket NuGet dengan biner yang diperlukan

  2. Menghasilkan Package.appxmanifest - Manifes aplikasi yang diperlukan untuk identitas aplikasi dan kemasan MSIX

  3. Assets/ Membuat folder - Berisi ikon aplikasi dan aset visual untuk aplikasi Anda

  4. Buat winapp.yaml - Melacak versi SDK dan konfigurasi project

  5. Installs SDK Aplikasi Windows runtime - Komponen runtime yang dibutuhkan untuk API modern

  6. Mengaktifkan Mode Pengembang di Windows - Dibutuhkan untuk penelusuran kesalahan aplikasi kami

  7. Menghasilkan pengikatan JS - Saat Anda ikut serta, pengikatan tersebut:

    • Menulis blok winapp.jsBindings ke package.json
    • Menambahkan @microsoft/dynwinrt-codegen ke devDependencies — alat saat build yang menghasilkan binding (dipasangkan ke versi latest milik registri saat pertama kali dijalankan, lalu setelah itu dibiarkan apa adanya)
    • Menambahkan @microsoft/dynwinrt ke dependencies — runtime yang diimpor oleh binding yang dihasilkan saat eksekusi (versinya dipilih oleh codegen yang terinstal untuk menjamin kompatibilitas ABI)
    • Menghasilkan pengikatan JS untuk API SDK Aplikasi Windows ke dalam.winapp/bindings/

Nota

Folder .winapp/ secara otomatis ditambahkan ke .gitignore dan tidak boleh dicek masuk ke sumber.

Anda dapat membuka Package.appxmanifest untuk menyesuaikan properti lebih lanjut seperti nama tampilan, penerbit, dan kemampuan.

Tip

Tentang SDK Windows:

  • Windows SDK - Platform pengembangan yang memungkinkan Anda membangun aplikasi Win32/desktop. Ini dirancang di sekitar API Windows yang digabungkan dengan versi OS tertentu. Gunakan ini untuk mengakses API Win32 inti seperti sistem file, jaringan, dan layanan sistem.

  • SDK Aplikasi Windows - Platform pengembangan baru yang memungkinkan Anda membangun aplikasi desktop modern yang dapat diinstal di seluruh versi Windows (hingga Windows 10 1809). Ini menyediakan abstraksi yang nyaman, terpisah dari OS di sekitar katalog API Windows OS yang kaya. SDK Aplikasi Windows mencakup WinUI 3 dan menyediakan akses ke fitur modern seperti kemampuan AI (Phi Silica), pemberitahuan, manajemen jendela, dan banyak lagi yang menerima pembaruan rutin yang independen dari rilis OS Windows.

Pelajari lebih lanjut: Apa perbedaan antara SDK Aplikasi Windows dan SDK Windows?

Langkah 4: Tambahkan Pulihkan ke Alur Build Anda

Untuk memastikan SDK Windows tersedia saat pengembang lain mengkloning proyek Anda atau di alur CI/CD, tambahkan skrip postinstall ke package.json Anda:

{
  "scripts": {
    "postinstall": "winapp restore && winapp node add-electron-debug-identity"
  }
}

Skrip ini secara otomatis berjalan setelah npm install dan melakukan dua hal:

  1. winapp restore - Mengunduh dan memulihkan semua paket SDK Windows ke folder .winapp/
  2. winapp node add-electron-debug-identity - Mendaftarkan aplikasi Electron Anda dengan identitas debug (selengkapnya tentang ini di langkah berikutnya)

Important

Electron 42 dan yang lebih baru: Pada Electron 42, biner tidak lagi diunduh secara otomatis selama npm install (catatan rilis). Anda harus mengunduhnya secara eksplisit sebelum add-electron-debug-identity menjalankan:

{
  "scripts": {
    "postinstall": "npx --no-install install-electron && winapp restore && winapp node add-electron-debug-identity"
  }
}

Flag --no-install memastikan npx hanya menjalankan biner install-electron yang disertakan dalam paket Electron yang Anda instal dan tidak pernah mengunduh apa pun secara diam-diam dari registry. Jika Anda menyematkan ke Electron < 42, hilangkan langkah ini — biner sudah ada setelah npm install.

Sekarang jalankan npm install untuk memicu skrip pascainstall dan mengonfigurasi lingkungan Windows:

npm install

Nota

postinstall Skrip berjalan secara otomatis setelah setiap npm install. Ini berarti lingkungan Windows akan dikonfigurasi secara otomatis setiap kali seseorang mengkloning proyek Anda dan menjalankan npm install.

💡 Pengembangan Lintas Platform (klik untuk memperluas)

Jika Anda membangun aplikasi Electron lintas platform dan memiliki pengembang yang bekerja di macOS atau Linux, Anda harus melakukan pengaturan khusus Windows secara kondisional. Berikut adalah pendekatan yang direkomendasikan:

Buat scripts/postinstall.js:

if (process.platform === 'win32') {
  const { execSync } = require('child_process');
  const fs = require('fs');
  const path = require('path');

  // Electron 42+ ships an `install-electron` bin and skips the postinstall download.
  // Run it only when present, and use `--no-install` so npx never silently fetches
  // anything from the registry.
  const installElectronBin = path.join(
    'node_modules', '.bin',
    process.platform === 'win32' ? 'install-electron.cmd' : 'install-electron'
  );
  const steps = [];
  if (fs.existsSync(installElectronBin)) {
    steps.push('npx --no-install install-electron');
  }
  steps.push(
    'npx winapp restore',
    'npx winapp cert generate --if-exists skip',
    'npx winapp node add-electron-debug-identity'
  );

  try {
    execSync(steps.join(' && '), { stdio: 'inherit' });
  } catch (error) {
    console.warn('Warning: Windows-specific setup failed. If you are not developing Windows features, you can ignore this.');
  }
} else {
  console.log('Skipping Windows-specific setup on non-Windows platform.');
}

Kemudian perbarui package.json:

{
  "scripts": {
    "postinstall": "node scripts/postinstall.js"
  }
}

Ini memastikan penyiapan khusus Windows hanya berjalan pada komputer Windows, memungkinkan pengembang di platform lain untuk mengerjakan proyek tanpa kesalahan.

Langkah 5: Memahami Identitas Debug

Pada Langkah 4, npm install yang Anda jalankan memicu skrip postinstall, yang kemudian menjalankan winapp node add-electron-debug-identity. Ini memberi aplikasi Anda identitas debug sementara sehingga Anda dapat menguji API Windows yang memerlukan identitas aplikasi selama pengembangan.

Apa Fungsi Identitas Debug?

Perintah ini:

  1. Memeriksa Package.appxmanifest Anda untuk mendapatkan detail dan kemampuan aplikasi
  2. Mendaftarkan electron.exe di node_modules Anda dengan identitas sementara
  3. Memungkinkan Anda menguji API yang diperlukan identitas tanpa membuat paket MSIX lengkap

Identitas debug diterapkan secara otomatis saat Anda menjalankan npm install di Langkah 4. Ke depannya, itu akan diterapkan kembali setiap kali ada yang menjalankan npm install.

Kapan Harus Memperbarui Identitas Debug Secara Manual

Anda perlu menjalankan perintah ini secara manual setiap kali Anda memodifikasi Package.appxmanifest (mengubah kemampuan, identitas, atau properti) atau salah satu aset tertaut (ikon, mcp.json, dll)

npx winapp node add-electron-debug-identity

Menguji Penyiapan Anda

Sekarang Anda dapat menguji aplikasi Electron dengan identitas debug yang diterapkan:

npm start

Anda akan melihat jendela aplikasi desktop terbuka (bukan tab browser) — ini adalah cara aplikasi Electron berjalan.

⚠️ Masalah umum: Aplikasi Crash atau Jendela Kosong (klik untuk memperluas)

Diketahui ada bug pada Windows dengan aplikasi Electron yang dikemas secara sparse, yang menyebabkan aplikasi mengalami crash saat startup atau gagal merender konten web. Masalah ini telah diperbaiki di Windows tetapi belum disebarluaskan ke semua perangkat.

Gejala:

  • Aplikasi crash segera setelah diluncurkan
  • Jendela terbuka tetapi menampilkan layar kosong/putih
  • Konten web gagal ditampilkan

Solusi:

Tambahkan --no-sandbox flag ke skrip mulai Anda di package.json. Ini mengatasi masalah ini dengan menonaktifkan sandbox Chromium, yang aman digunakan untuk pengembangan.

{
  "scripts": {
    "start": "electron-forge start -- --no-sandbox"
  }
}

Penting: Masalah ini tidak memengaruhi kemasan MSIX penuh - hanya identitas debug selama pengembangan.

Untuk membatalkan identitas debug (jika diperlukan untuk pemecahan masalah):

npx winapp node clear-electron-debug-identity

Ini memulihkan file eksekusi Electron yang asli tanpa identitas debug.

Langkah Selanjutnya

Sekarang setelah lingkungan pengembangan Anda disiapkan, Anda siap untuk memanggil API Windows dari JavaScript atau membuat addon asli saat Anda memerlukan kode asli:

Atau kembali ke Gambaran Umum Memulai.

  • Last updated on