Nastavení vývojového prostředí

Tato příručka vás provede nastavením vývojového prostředí Elektron pro vývoj rozhraní API pro Windows. Nainstalujete potřebné nástroje, inicializujete project a nakonfigurujete sady Windows SDK.

Předpoklady

Než začnete, ujistěte se, že máte:

Windows 11
Node.js - winget install OpenJS.NodeJS --source winget
.NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
Visual Studio s nativní desktopovou pracovní zátěží - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

Krok 1: Vytvoření nové aplikace Elektron

Začneme s novou aplikací Electron pomocí Electron Forge, který poskytuje vynikající podporu pro nástroje a balení. Pokud začínáte z existující aplikace, můžete tento krok přeskočit.

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

Na výzvu od Electron Forge:

Bundler: Select None (doporučeno – nativní doplňky fungují bez další konfigurace)
Jazyk: Vyberte JavaScript (v tomto průvodci se používá JS; TypeScript funguje také)
Verze Electron: Vyberte nejnovější
Inicializace git: Vaše preference

Ověřte, že aplikace běží:

npm start

Mělo by se zobrazit výchozí okno Elektron Forge. Zavřete ho a pojďme přidat možnosti Windows!

Krok 2: Instalace rozhraní příkazového řádku winapp

Pracovní postup Electron vyžaduje balíček npm (@microsoft/winappcli) místo samostatného příkazového řádku nainstalovaného z wingetu. Balíček npm obsahuje pomocné rutiny specifické pro Node.js(například add-electron-debug-identity a create-addon), které nejsou k dispozici v nativním rozhraní příkazového řádku. Pokud už máte winapp nainstalovaný z wingetu, je to v pořádku – balíček npm přidá Node.jsnástroje specifické pro konkrétní projekt jako závislost projektu a nebude v konfliktu s instalací systému.

npm install --save-dev @microsoft/winappcli

Krok 3: Inicializace project pro vývoj pro Windows

Příkaz winapp init nastaví vše, co potřebujete na jednom místě: manifest aplikace, prostředky a sady SDK.

Spusťte následující příkaz a postupujte podle pokynů:

npx winapp init .

Po zobrazení výzvy:

Název balíčku: Stisknutím klávesy Enter přijměte výchozí hodnotu (my-windows-app).
Publisher název: Stisknutím klávesy Enter přijměte výchozí hodnotu nebo zadejte své jméno.
Verze: Stisknutím klávesy Enter přijměte verzi 1.0.0.0.
Vstupní bod: Stisknutím klávesy Enter přijměte výchozí (my-windows-app.exe)
Instalační sady SDK: Vyberte stabilní sady SDK.

Co dělá `winapp init` ?

Tento příkaz nastaví vše, co potřebujete pro vývoj pro Windows:

Vytvoří .winapp/ složku obsahující:
- Hlavičky a knihovny ze sady Windows SDK
- Záhlaví a knihovny z Windows App SDK
- Balíčky NuGet s požadovanými binárními soubory
Generuje Package.appxmanifest – Manifest aplikace vyžadovaný pro identitu aplikace a balení MSIX
Vytvoří Assets/ složku – Obsahuje ikony aplikací a vizuální prostředky pro vaši aplikaci.
Creates winapp.yaml – Sleduje verze sady SDK a konfiguraci project
Instalace Windows App SDK runtime – Požadované komponenty modulu runtime pro moderní rozhraní API
Enables Developer Mode in Windows – vyžadováno pro ladění naší aplikace

Poznámka:

Složka .winapp/ se automaticky přidá do .gitignore, ale neměla by být zapsána do úložiště.

Můžete otevřít Package.appxmanifest a upravit vlastnosti, jako je zobrazovaný název, vydavatel a možnosti.

Tip

O knihovnách SDK Windows:

Windows SDK – vývojová platforma, která umožňuje vytvářet aplikace Win32/desktop. Je navržená pro rozhraní API systému Windows, která jsou svázaná s konkrétními verzemi operačního systému. Tato možnost slouží k přístupu k základním rozhraním API Win32, jako jsou systém souborů, sítě a systémové služby.
Windows App SDK – nová vývojová platforma, která umožňuje vytvářet moderní desktopové aplikace, které je možné nainstalovat napříč verzemi Windows (až do Windows 10 1809). Poskytuje pohodlnou, na operačním systému nezávislou abstrakci kolem rozsáhlého katalogu rozhraní API operačního systému Windows. Windows App SDK zahrnuje WinUI 3 a poskytuje přístup k moderním funkcím, jako jsou funkce AI (Phi Silica), oznámení, správa oken a další, které dostávají pravidelné aktualizace nezávislé na verzích operačního systému Windows.

Další informace: Co je rozdíl mezi Windows App SDK a sadou WINDOWS SDK?

Krok 4: Přidání obnovení do kanálu buildu

Pokud chcete zajistit, že Windows sady SDK budou dostupné, když ostatní vývojáři klonují váš projekt nebo v CI/CD kanálech, přidejte do postinstall skript package.json.

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

Tento skript se automaticky spustí po události npm install a provede dvě věci:

winapp restore – stáhne a obnoví všechny balíčky sady WINDOWS SDK do složky .winapp/
winapp node add-electron-debug-identity - Zaregistruje aplikaci Electron s identitou pro ladění (více o tomto se dozvíte v následujících krocích).

Teď spusťte příkaz npm install, který aktivuje poinstalační skript a nakonfiguruje prostředí Windows:

npm install

Poznámka:

Skript postinstall se spustí automaticky po každém npm install. To znamená, že prostředí Windows se nakonfiguruje automaticky, kdykoli někdo naklonuje váš projekt a spustí npm install.

💡 Vývoj pro různé platformy (kliknutím rozbalte)

Pokud vytváříte multiplatformní aplikaci Electron a máte vývojáře pracující na macOS nebo Linuxu, budete chtít podmíněně spustit nastavení specifické pro Windows. Tady je doporučený postup:

Vytvořit scripts/postinstall.js:

if (process.platform === 'win32') {
  const { execSync } = require('child_process');
  try {
    execSync('npx winapp restore && npx winapp cert generate --if-exists skip && npx winapp node add-electron-debug-identity', {
      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.');
}

Pak aktualizujte package.json:

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

Tím se zajistí, že se nastavení specifické pro Windows spustí jenom na Windows počítačích, což vývojářům na jiných platformách umožní pracovat na projektu bez chyb.

Krok 5: Pochopení identity ladění

Spuštěním npm install v kroku 4 se spustil postinstall skript, který běžel winapp node add-electron-debug-identity. Poskytuje to vaší aplikaci dočasnou identitu ladění, abyste mohli otestovat rozhraní Windows API, která během vývoje vyžadují identitu aplikace.

K čemu slouží ladicí identita?

Tento příkaz:

Přečte vaše Package.appxmanifest a zjistí podrobnosti a schopnosti aplikace.
Zaregistruje electron.exe ve vaší node_modules s dočasnou identitou.
Umožňuje otestovat rozhraní API, která vyžadují identitu, bez vytvoření kompletního balíčku MSIX.

Identita ladění se použila automaticky při spuštění npm install v kroku 4. V budoucnu se znovu použije pokaždé, když někdo spustí npm install.

Kdy ručně aktualizovat ladicí identitu

Tento příkaz musíte spustit ručně, kdykoli změníte Package.appxmanifest (změníte možnosti, identitu nebo vlastnosti) nebo některý z propojených prostředků (ikony, mcp.jsonatd.)

npx winapp node add-electron-debug-identity

Testování nastavení

Teď můžete otestovat aplikaci Elektron s použitou identitou ladění:

npm start

Mělo by se zobrazit otevřené okno desktopové aplikace (ne karta prohlížeče) – to je způsob, jakým aplikace Electron běží.

⚠️ Známý problém: Chybové ukončení aplikace nebo prázdné okno (kliknutím rozbalte)

Existuje známá chyba Windows s řídkým balením aplikací Electron, která způsobuje, že aplikace se při startu zhroutí nebo nevykreslí webový obsah. Tento problém je opravený v Windows, ale zatím se nerozšířel na všechna zařízení.

Příznaky:

Aplikace se okamžitě po spuštění chybově ukončí.
Otevře se okno, ale zobrazuje prázdnou/bílou obrazovku.
Webový obsah se nevykreslí

Alternativní řešení:

Přidejte příznak --no-sandbox do spouštěcího skriptu v package.json. Tento problém se dá obejít zakázáním sandboxu Chromium, což je bezpečné pro účely vývoje.

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

Důležité: Tento problém nemá vliv na úplné balení MSIX – pouze ladění identity během vývoje.

Vrátit zpět identitu pro ladění (v případě potřeby pro řešení potíží):

npx winapp node clear-electron-debug-identity

Tím se obnoví původní spustitelný soubor Electron bez ladicí identity.

Další kroky

Teď, když je vaše vývojové prostředí nastavené, jste připraveni vytvářet nativní doplňky a volat Windows rozhraní API:

Vytvoření doplňku Phi Silica – Zjistěte, jak vytvořit doplněk jazyka C#, který volá rozhraní API Phi Silica AI.
Creating a WinML Addon – Zjistěte, jak vytvořit doplněk jazyka C#, který používá Windows Machine Learning
Balení pro distribuci – Vytvoření balíčku MSIX pro distribuci

Nebo se vraťte do přehledu Začínáme.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-05-12