Настройка среды разработки

В этом руководстве описывается настройка среды разработки Electron для разработки API Windows. Установите нужные средства, инициализируйте проект и настройте пакеты средств разработки (SDK) для Windows.

Необходимые условия

Прежде чем начать, убедитесь, что у вас есть следующее:

Windows 11
Node.js - winget install OpenJS.NodeJS --source winget
пакет SDK .NET версии 10 - winget install Microsoft.DotNet.SDK.10 --source winget
Visual Studio с нативной рабочей нагрузкой для настольных ПК - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

Шаг 1. Создание нового приложения Electron

Мы начнем с нового приложения Electron с помощью Electron Forge, которое обеспечивает отличную поддержку инструментов и упаковки. Если вы начинаете с существующего приложения, этот шаг можно пропустить.

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

После запроса от Electron Forge:

Bundler: Select None (рекомендуется — собственные надстройки работают без дополнительной настройки)
Язык: выбор JavaScript (в этом руководстве используется JS; TypeScript тоже работает)
Электронная версия: выберите последнюю версию
Инициализация git: ваши предпочтения

Проверьте, что приложение выполняется:

npm start

Должно появиться окно "Electron Forge" по умолчанию. Закройте его и добавьте возможности Windows!

Шаг 2. Установка winapp CLI

Для рабочего процесса Electron требуется пакет npm (@microsoft/winappcli), а не автономный интерфейс командной строки, установленный из winget. Пакет npm включает в себя Node.js вспомогательные службы (например add-electron-debug-identity и create-addon), которые недоступны в собственном интерфейсе командной строки. Если у вас уже установлено winapp из winget, то это нормально — пакет npm добавляет инструменты, специфичные для Node.js, в качестве зависимости для проекта и не конфликтует с установленной системой.

npm install --save-dev @microsoft/winappcli

Шаг 3. Инициализировать проект для разработки под Windows

Команда winapp init настраивает все, что вам нужно одним махом: манифест приложения, ресурсы и SDK.

Выполните следующую команду и следуйте подсказкам.

npx winapp init .

Когда появится запрос:

Имя пакета: нажмите клавишу ВВОД, чтобы принять значение по умолчанию (my-windows-app)
Имя издателя: нажмите клавишу Enter, чтобы принять значение по умолчанию или введите своё имя.
Версия: нажмите клавишу ВВОД, чтобы принять 1.0.0.0
Точка входа: нажмите клавишу ВВОД, чтобы принять значение по умолчанию (my-windows-app.exe)
Установка пакетов SDK: выберите "Стабильные пакеты SDK"

Что делает `winapp init` ?

Эта команда настраивает все необходимые компоненты для разработки Windows:

Создает .winapp/ папку , содержащую:
- Заголовки и библиотеки из пакета SDK Windows
- Заголовки и библиотеки из Windows App SDK
- Пакеты NuGet с необходимыми двоичными файлами
Генерирует Package.appxmanifest — манифест приложения, необходимый для идентификации приложения и упаковки MSIX
Создает Assets/ папку — содержит значки приложения и визуальные ресурсы для приложения
Creates winapp.yaml — отслеживает версии пакета SDK и конфигурацию project
Installs Windows App SDK runtime — необходимые компоненты среды выполнения для современных API
Включает режим разработчика в Windows — требуется для отладки нашего приложения

Замечание

Папка .winapp/ автоматически добавляется в .gitignore и не должна быть загружена в репозиторий.

Вы можете открыть Package.appxmanifest, чтобы дополнительно настроить такие свойства, как отображаемое имя, издатель и возможности.

Tip

О пакетах SDK Windows:

Windows SDK — платформа разработки, которая позволяет создавать классические Win32/настольные приложения. Этот пакет использует API Windows, которые привязаны к определенным версиям ОС. Используйте это для доступа к основным API Win32, таким как файловая система, сети и системные службы.
Windows App SDK — новая платформа разработки, которая позволяет создавать современные классические приложения, которые можно установить в Windows версиях (вплоть до Windows 10 1809). Обеспечивает удобную, независимую от ОС абстракцию вокруг богатого каталога API ОС Windows. Windows App SDK включает WinUI 3 и предоставляет доступ к современным функциям, таким как возможности искусственного интеллекта (Phi Silica), уведомления, управление окнами и многое другое, которое получает регулярные обновления независимо от выпусков ос Windows.

Дополнительные сведения: Чем разница между Windows App SDK и пакетом SDK Windows?

Шаг 4. Добавление восстановления в конвейер сборки

Чтобы гарантировать доступность Windows SDK в CI/CD средах или когда другие разработчики клонируют ваш проект, следует добавить скрипт postinstall в package.json.

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

Этот скрипт автоматически запускается после npm install и выполняет две задачи:

winapp restore — загружает и восстанавливает все пакеты SDK Windows в папку .winapp/
winapp node add-electron-debug-identity — регистрирует ваше приложение Electron с идентификатором для отладки (подробнее об этом на следующих этапах)

Теперь запустите npm install, чтобы активировать скрипт postinstall и настроить среду Windows:

npm install

Замечание

Скрипт postinstall выполняется автоматически после каждого npm install. Это означает, что среда Windows будет настроена автоматически, когда кто-то клонирует проект и запускает npm install.

💡 Кроссплатформенная разработка (щелкните, чтобы развернуть)

Если вы создаете кроссплатформенное приложение на базе Electron и у вас есть разработчики, использующие macOS или Linux, необходимо условно выполнить настройку, специфичную для Windows. Ниже приведен рекомендуемый подход.

Создайте 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.');
}

Затем обновите package.json:

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

Это гарантирует, что настройка, специфичная для Windows, выполняется только на Windows устройствах, что позволяет разработчикам на других платформах работать над проектом без ошибок.

Шаг 5: Понимание сущности отладки

Сценарий, который вы запустили на шаге npm install, активировал postinstall, который запустил winapp node add-electron-debug-identity. Это дает приложению временное удостоверение отладки, чтобы можно было протестировать Windows API, для которых требуется удостоверение приложения во время разработки.

Что делает отладочное удостоверение?

Эта команда:

Считывает Package.appxmanifest сведения о приложении и его возможности
Региструет electron.exe в node_modules с временной идентификацией
Позволяет тестировать API для управления идентификацией без создания полного пакета MSIX.

Удостоверение отладки было применено автоматически при запуске npm install на шаге 4. В дальнейшем он будет повторно применяться всякий раз, когда кто-либо запускает npm install.

Когда необходимо вручную обновить удостоверение отладки

Эту команду необходимо выполнять вручную каждый раз, когда вы изменяете Package.appxmanifest (например, возможности, удостоверения или свойства) или любые связанные ресурсы (значки, mcp.json и т. д.)

npx winapp node add-electron-debug-identity

Тестирование установки

Теперь вы можете протестировать приложение Electron с помощью примененной идентификации отладки:

npm start

Откроется окно классического приложения (а не вкладка браузера) — это способ запуска приложений Electron.

⚠️ Известная проблема: сбои приложения или пустое окно (щелкните, чтобы развернуть)

Известна ошибка Windows, связанная с разряженной упаковкой приложений Electron, которая приводит к сбою приложения при запуске или не отображает веб-содержимое. Проблема устранена в Windows, но еще не распространилась на все устройства.

Симптомы:

Сбой приложения сразу после запуска
Откроется окно, но отображается пустой или белый экран
Веб-содержимое не удается отобразить

Решение:

Добавьте флаг --no-sandbox в скрипт старта в package.json. Это обходит проблему, отключив песочницу Chromium, что безопасно для целей разработки.

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

Важно: Эта проблема не влияет на полную упаковку MSIX — только на отладочную идентификацию во время разработки.

Чтобы отменить идентификатор отладки (при необходимости для устранения неполадок):

npx winapp node clear-electron-debug-identity

Восстанавливается исходный исполняемый файл Electron без идентификатора отладки.

Дальнейшие шаги

Теперь, когда среда разработки настроена, вы можете создавать собственные надстройки и вызывать WINDOWS API:

Создание надстройки Phi Silica — узнайте, как создать надстройку C#, которая вызывает API Phi Silica AI
Создание надстройки WinML . Узнайте, как создать надстройку C#, которая использует Windows Машинное обучение
Упаковка для распространения — создание пакета MSIX для распространения

Или вернитесь к обзору начала работы.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-05-12