A fejlesztési környezet beállítása

Ez az útmutató végigvezeti a Windows API-fejlesztéshez készült Electron fejlesztési környezet beállításán. Telepíti a szükséges eszközöket, inicializálja a project, és konfigurálja a Windows SDK-kat.

Előfeltételek

Mielőtt hozzákezdene, győződjön meg arról, hogy:

Windows 11
Node.js - winget install OpenJS.NodeJS --source winget
.NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
Visual Studio a natív asztali számítási feladattal - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

1. lépés: Új elektronalkalmazás létrehozása

Kezdjük egy új Electron-alkalmazással az Electron Forge használatával, amely kiváló eszköz- és csomagolástámogatást biztosít. Ha egy meglévő alkalmazásból indul ki, kihagyhatja ezt a lépést.

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

Amikor az Electron Forge kéri:

Bundler: Select None (ajánlott – a natív bővítmények további konfiguráció nélkül működnek)
Nyelv: JavaScript kiválasztása (ez az útmutató JS-t használ; TypeScript is működik)
Elektronverzió: Válassza ki a legújabb
Git inicializálása: Az Ön preferencia

Ellenőrizze, hogy fut-e az alkalmazás:

npm start

Meg kell jelennie az alapértelmezett Electron Forge ablaknak. Zárja be, és adjunk hozzá Windows képességeket!

2. lépés: A winapp parancssori felületének telepítése

Az Electron-munkafolyamathoz a wingetből telepített önálló parancssori felület helyett az npm-csomag (@microsoft/winappcli) szükséges. Az npm-csomag Node.js-specifikus segítőket (például add-electron-debug-identity és create-addon) tartalmaz, amelyek nem érhetők el a natív parancssori felületen. Ha már telepítette a winappot a Wingetből, az rendben van – az npm-csomag Node.js-specifikus eszközöket ad hozzá projektfüggőségként, és nem ütközik a rendszer telepítésével.

npm install --save-dev @microsoft/winappcli

3. lépés: A Windows-fejlesztés project inicializálása

A winapp init parancs egyetlen lépésben állítja be a szükséges elemeket: alkalmazásjegyzékeket, objektumokat és SDK-kat.

Futtassa a következő parancsot, és kövesse az utasításokat:

npx winapp init .

Amikor a rendszer kéri:

Csomag neve: Az alapértelmezett (my-windows-app) elfogadásához nyomja le az Enter billentyűt
Publisher név: Az Enter billentyűt lenyomva fogadja el az alapértelmezett értéket, vagy adja meg a nevét
Verzió: Nyomja le az Enter billentyűt az 1.0.0.0 elfogadásához
Belépési pont: Nyomja le az Enter billentyűt az alapértelmezett (my-windows-app.exe) elfogadásához
SDK-k beállítása: Válassza a "Stabil SDK-k" lehetőséget
JS-/TypeScript-kötések hozzáadása: Az Enter billentyűt lenyomva fogadja el az alapértelmezett (Igen) jS-kötéseket Windows App SDK API-khoz

Megjegyzés:

--use-defaults és a nem interaktív init kihagyja a JS-kötéseket, hacsak nem ad át --add-js-bindings. Futtassa a(z) npx winapp init . elemet interaktív módban, hogy a kérdésnél beleegyezzen, vagy automatizáláshoz használja a(z) npx winapp init . --use-defaults --add-js-bindings elemet.

Mit tesz `winapp init` ?

Ez a parancs beállít mindent, amire szüksége van a Windows fejlesztéséhez:

Létrehoz egy .winapp/ mappát , amely a következőt tartalmazza:
- Fejlécek és kódtárak a Windows SDK-ból
- Fejlécek és kódtárak a Windows App SDK
- NuGet-csomagok a szükséges bináris fájlokkal
Generál Package.appxmanifest - Az alkalmazásdentitáshoz és az MSIX-csomagoláshoz szükséges alkalmazásjegyzék
Mappa létrehozása Assets/ – Alkalmazásikonokat és vizuális objektumokat tartalmaz az alkalmazáshoz
Projektet winapp.yaml – Nyomon követi az SDK-verziókat és a projekt konfigurációját
A Windows App SDK futtatókörnyezet telepítése – A modern API-khoz szükséges futtatókörnyezeti összetevők
Fejlesztői mód engedélyezése Windowsban – Szükséges az alkalmazás hibakereséséhez
JS-kötéseket generál – Ha engedélyezi, a következő történik:
- A(z) winapp.jsBindings blokk írása ide: package.json
- Hozzáadja a(z) @microsoft/dynwinrt-codegen elemet a(z) devDependencies elemhez — a kötéseket előállító fordításidejű eszközhöz (az első futtatáskor a regiszter latest verziójához rögzítve, utána változatlanul hagyva)
- Hozzáadja a(z) @microsoft/dynwinrt elemet a(z) dependencies elemhez — ahhoz a futtatókörnyezethez, amelyet a generált kötések futásidőben importálnak (a verziót a telepített kódgenerátor választja ki az ABI-kompatibilitás garantálása érdekében)
- JavaScript-kötéseket generál a Windows App SDK API-jaihoz ide: .winapp/bindings/

Megjegyzés:

A .winapp/ rendszer automatikusan hozzáadja a mappát a .gitignore forráshoz, és nem kell bejelentkeznie a forrásba.

Megnyithatja Package.appxmanifest az olyan tulajdonságok további testreszabásához, mint a megjelenítendő név, a közzétevő és a képességek.

Tip

A Windows SDK-kről:

Windows SDK – A Win32/desktop alkalmazások készítését lehetővé tevő fejlesztői platform. Olyan Windows API-k köré tervezték, amelyek az operációs rendszer bizonyos verzióihoz vannak csatolva. Ezzel elérheti az olyan alapvető Win32 API-kat, mint a fájlrendszer, a hálózatkezelés és a rendszerszolgáltatások.
Windows App SDK – Egy új fejlesztési platform, amellyel modern asztali alkalmazásokat hozhat létre, amelyek Windows verziókra telepíthetők (egészen az 1809-Windows 10-ra). Kényelmes, operációsrendszer-független absztrakciót biztosít Windows operációsrendszer-API-k gazdag katalógusa körül. A Windows App SDK tartalmazza a WinUI 3-at, és hozzáférést biztosít olyan modern funkciókhoz, mint az AI-képességek (Phi Silica), az értesítések, az ablakkezelés és egyebek, amelyek Windows operációsrendszer-kiadásoktól függetlenül rendszeres frissítéseket kapnak.

További információ: Mi a különbség a Windows App SDK és a Windows SDK között?

4. lépés: Visszaállítás hozzáadása a buildelési folyamathoz

Annak érdekében, hogy a Windows SDK-k elérhetők legyenek, amikor más fejlesztők klónozzák a projektet vagy a CI/CD-folyamatokat, adjon hozzá egy postinstall szkriptet a package.json:

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

Ez a szkript automatikusan fut utána npm install , és két dolgot hajt ki:

winapp restore – Letölti és visszaállítja az összes Windows SDK-csomagot a .winapp/ mappába
winapp node add-electron-debug-identity - Regisztrálja az Electron-alkalmazást hibakeresési identitással (erről bővebben a következő lépésekben olvashat)

Important

Electron 42 és újabb: Az Electron 42-től kezdve a bináris fájl már nem töltődik le automatikusan a(z) npm install során (kiadási megjegyzések). A futtatás előtt add-electron-debug-identity kifejezetten le kell töltenie:

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

A --no-install jelző gondoskodik arról, hogy a npx csak a telepített Electron-csomaghoz mellékelt install-electron binárist futtassa, és soha ne töltsön le semmit a regiszterből észrevétlenül. Ha az Electron < 42 előtti verziójához van rögzítve, hagyja ki ezt a lépést — a bináris fájl már a helyén van a(z) npm install után.

Most futtassa a npm install parancsot a postinstall szkript aktiválásához és a Windows környezet konfigurálásához:

npm install

Megjegyzés:

A postinstall szkript minden egyes npm installután automatikusan fut. Ez azt jelenti, hogy a Windows környezet automatikusan konfigurálva lesz, amikor valaki klónozza a projektet, és npm install futtat.

💡 Platformfüggetlen fejlesztés (kattintson a kibontásához)

Ha platformfüggetlen Electron-alkalmazást készít, és a fejlesztők macOS-en vagy Linuxon dolgoznak, feltételesen futtatnia kell a Windows-specifikus beállítást. Az ajánlott megközelítés a következő:

Hozzon létre 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.');
}

Ezután frissítse a következőt package.json:

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

Ez biztosítja, hogy Windows-specifikus beállítás csak Windows gépeken fusson, így más platformok fejlesztői hiba nélkül dolgozhatnak a projekten.

5. lépés: A hibakeresési identitás ismertetése

A npm install 4. lépésben futtatott parancsprogram aktiválta a postinstall szkriptet, amely futott winapp node add-electron-debug-identity. Ez ideiglenes hibakeresési identitást biztosít az alkalmazásnak, így tesztelheti Windows olyan API-kat, amelyekhez alkalmazásdentitásra van szükség a fejlesztés során.

Mit csinál az identitás hibakeresése?

Ez a parancs:

Olvassa a(z) Package.appxmanifest alkalmazást annak részletei és képességei megismeréséhez
electron.exe Regisztrál az node_modules ideiglenes identitással
Lehetővé teszi az identitáshoz szükséges API-k tesztelését teljes MSIX-csomag létrehozása nélkül

A hibakeresési identitás automatikusan lett alkalmazva, amikor a(z) npm install futott a 4. lépésben. A továbbiakban a rendszer újra alkalmazza, amikor valaki fut npm install.

Mikor kell manuálisan frissíteni a hibakeresési identitást?

Ezt a parancsot manuálisan kell futtatnia, valahányszor módosítja a Package.appxmanifest (a képességeket, az identitást vagy a tulajdonságokat) vagy bármely kapcsolt eszközt (például ikonok, mcp.json stb.)

npx winapp node add-electron-debug-identity

A telepítés tesztelése

Most már tesztelheti az Electron-alkalmazást a hibakeresési identitás alkalmazásával:

npm start

Meg kell nyitnia egy asztali alkalmazásablakot (nem böngészőlapot) – így futnak az Electron-alkalmazások.

⚠️ Ismert probléma: Az alkalmazás összeomlik vagy üres ablak (kattintson a kibontásához)

Van egy ismert Windows hiba a ritkán csomagolt Electron-alkalmazásokkal, amely miatt az alkalmazás összeomlik az indításkor, vagy nem rendereli a webes tartalmat. A problémát kijavítottuk Windows, de még nem propagáltuk az összes eszközre.

Tünetek:

Az alkalmazás közvetlenül az indítás után összeomlik
Megnyílik az ablak, de üres/fehér képernyő jelenik meg
A webes tartalom nem jelenik meg

Átmeneti megoldás:

Adja hozzá a --no-sandbox zászlót a kezdő szkriptben package.json. Ez megkerüli a problémát a Chromium tesztkörnyezetének letiltásával, amely fejlesztési célokra biztonságos.

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

Fontos: Ez a probléma nem érinti a teljes MSIX-csomagolást – csak az identitás hibakeresését a fejlesztés során.

Hibakeresési identitás visszavonása (ha a hibaelhárításhoz szükséges):

npx winapp node clear-electron-debug-identity

Ezzel visszaállítja az eredeti Electron végrehajtható fájlt a hibakeresési azonosító nélkül.

Következő lépések

A fejlesztői környezet beállítása után készen áll arra, hogy meghívja Windows API-kat JavaScriptből, vagy natív bővítményeket hozzon létre, ha natív kódra van szüksége:

Windows API-k meghívása JavaScriptből – JS-kötések használatával hívja meg Windows App SDK API-kat, és bővítse őket Windows SDK API-kkal awinapp.jsBindings
Értesítés megjelenítése JavaScriptből – JS-kötések használatával natív bővítmény nélkül jeleníthet meg Windows App SDK értesítést
Phi Silica meghívása JavaScriptből – JS-kötések használatával összegezheti a szöveget a helyi nyelvi modellel
WinML futtatása JavaScriptből – JS-kötések használata ONNX-következtetéshez onnxruntime-node
Phi Silica-bővítmény létrehozása – Ismerje meg, hogyan hozhat létre olyan C#-bővítményt, amely meghívja a Phi Silica AI API-t
WinML-bővítmény létrehozása – Megtudhatja, hogyan hozhat létre egy C# bővítményt, ami Windows Machine Learning-et használ
Csomagolás disztribúcióhoz – MSIX-csomag létrehozása disztribúcióhoz

Vagy térjen vissza az első lépések áttekintéséhez.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-09-26

A fejlesztési környezet beállítása

Előfeltételek

1. lépés: Új elektronalkalmazás létrehozása

2. lépés: A winapp parancssori felületének telepítése

3. lépés: A Windows-fejlesztés project inicializálása

Mit tesz winapp init ?

4. lépés: Visszaállítás hozzáadása a buildelési folyamathoz

5. lépés: A hibakeresési identitás ismertetése

Mit csinál az identitás hibakeresése?

Mikor kell manuálisan frissíteni a hibakeresési identitást?

A telepítés tesztelése

Következő lépések

Visszajelzés

További források

Mit tesz `winapp init` ?