企业官网建设流程全解析

• 桌面应用
• 跨平台

本文以 docs/Core/Migration-Guide.md 为骨架，系统讲解从旧版 Electron.NET（ElectronNET.API+electron.manifest.json+ CLI 工具）迁移到新一代ElectronNET.Core的完整路径：涉及 NuGet 包结构替换、electron-builder.json自动配置、UseElectron()回调式启动改造、调试/打包流程升级以及常见问题排查。读完本文，你将能够独立完成一次生产级迁移，并掌握迁移后“.NET 优先”进程架构下的开发、调试与跨平台发布技能。

迁移前准备：环境与项目盘点

迁移本身并不复杂，但新旧两代框架在构建系统、运行时架构和工具链上存在根本差异，因此务必先做好三件事：

1. 备份你的项目——迁移过程中会删除旧的electron.manifest.json、替换 NuGet 包并改写Program.cs，一个可回退的工作备份是底线保障。
2. 更新开发工具——安装 Node.js 22.x 与 .NET 8.0+。
3. 记录当前环境——确认你当前的 Electron 与 ASP.NET 版本，便于迁移后对照验证行为是否一致。

按照 System Requirements 的说明，新框架要求的环境基线是：

Node.js 的安装与升级可参考以下方式：

• Windows：从官方安装包安装后，运行node --version确认输出为v22.x.x。
• Linux：推荐使用 Node Version Manager（NVM）：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22

如果你计划在 Windows 上为 Linux 目标做开发调试，还需要安装 WSL2，并在 WSL 内也安装 Node.js 22.x（LTS）。Visual Studio 在 WSL 上调试时会自动安装 .NET，其他场景则需要你在 WSL 中手动安装匹配的 .NET SDK。

Step 1：更新 NuGet 包

旧版项目引用的是ElectronNET.API单一包。迁移的第一步是先卸载旧包：

dotnet remove package ElectronNET.API

然后安装新架构下的包：

dotnet add package ElectronNET.Core dotnet add package ElectronNET.Core.AspNet # 仅 ASP.NET 项目需要

注意：ElectronNET.Core会自动把 API 包作为依赖引入，无需单独引用。完整的包结构说明见 Package Description。

理解新包结构：一个包拆成三个

新架构把“构建集成”与“API 定义”彻底分离，拆分为三个职责单一的包：

• ElectronNET.Core（主包）：包含 MSBuild 目标与任务、Visual Studio 项目系统集成（设计器）、运行时进程生命周期编排、自动生成electron-builder.json与package.json的能力。用于启动项目、需要完整 Electron.NET 功能的项目。
• ElectronNET.Core.Api（API 包）：纯粹的 Electron API 封装与类型定义，不含任何构建依赖，跨 Windows/macOS/Linux 平台。适用于类库项目、仅需 API 访问而不需要构建集成的场景，以及多项目解决方案中除启动项目以外的其他项目。
• ElectronNET.Core.AspNet（ASP.NET 集成包）：提供UseElectron()扩展方法、WebHost 集成、Hot Reload 支持等 ASP.NET 专用运行时组件。适用于基于 MVC、Razor Pages 或 Blazor 的 ASP.NET Core 项目。

依赖链清晰且无环：ElectronNET.Core→ElectronNET.Core.Api，ElectronNET.Core.AspNet→ElectronNET.Core.Api，ElectronNET.Core.Api本身没有任何依赖。

按项目形态选择引用方式：

单项目（ASP.NET）：

<ItemGroup> <PackageReference Include="ElectronNET.Core" Version="1.0.0" /> <PackageReference Include="ElectronNET.Core.AspNet" Version="1.0.0" /> </ItemGroup>

单项目（控制台）：

<ItemGroup> <PackageReference Include="ElectronNET.Core" Version="1.0.0" /> </ItemGroup>

多项目解决方案（ASP.NET）：启动项目引用ElectronNET.Core+ElectronNET.Core.AspNet，其余类库项目只引用ElectronNET.Core.Api，从而避免非启动项目被带入整套构建逻辑。

从源码看，控制台应用是 ElectronNET.Core 新引入的一等公民——ElectronNET.API/Runtime/StartupManager.cs会根据AssemblyMetadata中的IsAspNet标记判断DotnetAppType是 ASP.NET 应用还是普通 .NET 应用，非 ASP.NET 应用直接创建对应的运行时控制器。这意味着迁移后你甚至可以脱离 ASP.NET，仅用最简单的dotnet new console项目承载 Electron 桌面应用。

Step 2：配置项目设置：从 manifest 到 electron-builder.json

自动生成的配置

ElectronNET.Core会在首次构建或 NuGet restore 时，自动在你的项目Properties文件夹中生成electron-builder.json。对基础场景而言，无需任何手工配置。这与旧版“手工维护 JSON + CLI 参数”的模式有本质区别：配置错误被整体消灭，同时移除了对独立 CLI 工具（electronize.exe）的依赖。

迁移旧的 electron.manifest.json

如果你有旧版遗留的electron.manifest.json，按如下步骤迁移：

1. 打开项目生成的Properties/electron-builder.json；
2. 在旧electron.manifest.json中找到build节点；
3. 把build 节点的内容（注意：不是"build"这个键本身）复制到新的electron-builder.json中；
4. 使用 Visual Studio 项目设计器通过 UI 配置 Electron 设置；
5. 删除旧的electron.manifest.json文件。

手工配置 electron-builder.json

如果你偏好手工编辑，也可以在Properties/electron-builder.json中直接写配置，示例：

{ "linux": { "target": ["tar.xz"] }, "win": { "target": [ { "target": "nsis", "arch": "x64" } ] }, "nsis": { "oneClick": true, "perMachine": false } }

含义说明：

• linux.target：Linux 平台产物格式（如tar.xz，也可配AppImage、deb、rpm等）；
• win.target：Windows 平台产物格式，这里是 NSIS 安装器且指定x64架构；
• nsis.oneClick/nsis.perMachine：NSIS 安装器的“一键安装”模式与“是否按每台机器安装”。更完整的 electron-builder 选项可查阅对应工具的官方文档。

修改启动（Launch）设置

ElectronNET.Core不再依赖独立的 CLI 工具来启动应用，而是通过 Visual Studio 的启动配置文件（Properties/launchSettings.json）选择ASP.NET-first（.NET 优先）或Electron-first（Electron 优先）两种调试/启动方式。具体配置方法见 Debugging 与 Startup Methods。

值得注意的是，新框架支持8 种启动场景，覆盖“打包/未打包 × 控制台/ASP.NET × dotnet-first/electron-first”的全部组合。框架在运行时通过 StartupManager 自动检测并选择：

• 是否由 .NET 启动（LaunchOrderDetector.CheckIsLaunchedByDotNet()）；
• 是否处于未打包状态（UnpackagedDetector.CheckIsUnpackaged()）；

两个布尔量组合出UnpackedDotnetFirst、PackagedDotnetFirst、UnpackedElectronFirst、PackagedElectronFirst四种启动方式（枚举定义见 StartupMethod.cs）。与旧版“Electron 永远先启动”不同，新架构默认推荐.NET 优先，由 .NET 作为父进程管理 Electron 子进程的生命周期，带来更可靠的退出清理与错误恢复。

Step 3：更新启动代码：UseElectron() 回调改造

旧版UseElectron(args)不带回调，窗口创建时机不好控制。新版要求在UseElectron(args, onAppReadyCallback)中传入回调——该回调会在 Electron 就绪的正确时机执行，用于初始化你的 Electron UI。

现代 ASP.NET Core（WebApplication / 最小宿主模型）

using ElectronNET.API; using ElectronNET.API.Entities; public static void Main(string[] args) { var builder = WebApplication.CreateBuilder(args); builder.UseElectron(args, ElectronAppReady); var app = builder.Build(); app.Run(); } public static async Task ElectronAppReady() { var browserWindow = await Electron.WindowManager.CreateWindowAsync( new BrowserWindowOptions { Show = false }); browserWindow.OnReadyToShow += () => browserWindow.Show(); }

传统 ASP.NET Core（IWebHostBuilder + Startup 类）

using ElectronNET.API; using ElectronNET.API.Entities; public static void Main(string[] args) { WebHost.CreateDefaultBuilder(args) .UseElectron(args, ElectronAppReady) .UseStartup<Startup>() .Build() .Run(); } public static async Task ElectronAppReady() { var browserWindow = await Electron.WindowManager.CreateWindowAsync( new BrowserWindowOptions { Show = false }); browserWindow.OnReadyToShow += () => browserWindow.Show(); }

回调的四种重载与源码佐证

从 WebApplicationBuilderExtensions.cs 与 WebHostBuilderExtensions.cs 的源码可以看到，UseElectron的第二个参数提供了四种异步回调签名，你可以按需选用：

在 WebHost 模型下，回调会被包装为AppReadyCallbackResolver注册为单例（见WebHostBuilderExtensions的ConfigureServices分支），并在 ASP.NET 生命周期适配器（AspNetLifetimeAdapter）的驱动下于正确的时机触发。

在回调中加载指定 URL：读取真实端口

如果你希望在回调中跳转到具体页面，可以从静态类ElectronNetRuntime读取 ASP.NET 实际监听的端口（源码见 ElectronNetRuntime.cs）：

await browserWindow.WebContents .LoadURLAsync($"http://localhost:{ElectronNetRuntime.AspNetWebPort}/mypage.html");

ElectronNetRuntime同时暴露了AspNetWebPort（默认 Web 端口为 8001）、ElectronSocketPort（默认 Socket 桥接端口为 8000）以及ElectronAuthToken、StartupMethod等运行时信息，供你在回调与业务代码中做条件化处理。

依赖注入

ElectronNET 的 API 模块也可以注册进 ASP.NET 的 DI 容器，所有 Electron 模块均以单例形式注册：

using ElectronNET.API; public void ConfigureServices(IServiceCollection services) { services.AddElectron(); }

Step 4：更新开发工具与运行环境

迁移后请对照 System Requirements 核验开发环境：

• .NET 8.0 或更高；
• Node.js 22.x 且确保其位于 PATH 中；
• Visual Studio 2022（推荐）；
• 如需在 Windows 上构建/调试 Linux 应用，安装并配置 WSL2，同时在 WSL 内安装 Node.js 22.x 与匹配的 .NET SDK。

Step 5：更新调试设置：从 watch 到原生调试

旧 watch 功能已被移除

旧版依赖的watch特性在新框架中不再支持，取而代之的是ASP.NET-first 调试 + Hot Reload：

• 旧方式：手动附加进程、刷新缓慢；
• 新方式：原生 Visual Studio 调试 + Hot Reload，启动速度显著提升；
• 收益：更快的开发循环、更好的调试体验。

三种调试模式与 launchSettings.json

ElectronNET.Core通过Properties/launchSettings.json配置三种调试模式（详见 Debugging）：

1. ASP.NET-first 调试（推荐）——直接调试 .NET 代码，支持完整断点、Hot Reload 与编辑并继续（Edit-and-Continue）：

{ "profiles": { "ASP.Net (unpackaged)": { "commandName": "Project", "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development" }, "applicationUrl": "http://localhost:8001/" } } }

2. Electron-first 调试——用于需要检查原生 Electron API / Node.js 代码的场景：

{ "profiles": { "Electron (unpackaged)": { "commandName": "Executable", "executablePath": "node", "commandLineArgs": "node_modules/electron/cli.js main.js -unpackedelectron", "workingDirectory": "$(TargetDir).electron", "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development" } } } }

3. WSL 跨平台调试——在 Windows 上直接调试 Linux 构建产物：

{ "profiles": { "WSL": { "commandName": "WSL2", "launchUrl": "http://localhost:8001/", "environmentVariables": { "ASPNETCORE_ENVIRONMENT": "Development", "ASPNETCORE_URLS": "http://localhost:8001/" }, "distributionName": "" } } }

三者可以合并进同一个launchSettings.json，按需选择启动配置。

命令行启动标志与启动方法速查

结合 Startup Methods，迁移后你会遇到四个关键命令行标志：

切换 Runtime Identifier

在 Windows 与 WSL/Linux 调试之间切换时，需要调整 Runtime Identifier：

• 在 Visual Studio 中：右键项目 →Properties→ 调整 Runtime Identifier；
• 直接编辑.csproj：

<!-- For Windows debugging --> <RuntimeIdentifier>win-x64</RuntimeIdentifier> <!-- For WSL/Linux debugging --> <RuntimeIdentifier>linux-x64</RuntimeIdentifier>

新框架的输出目录也遵循标准 .NET 约定（如bin\net8.0\win-x64），取代了旧版含义模糊的bin\Desktop布局，多目标构建清晰可预测。

验证迁移：构建、调试与打包测试

完成上述五个步骤后，按以下顺序验证迁移成果：

1. 构建项目——确认无编译错误；
2. 用新的 ASP.NET-first 方式测试调试——断点、Hot Reload、编辑并继续；
3. 验证打包——确认新配置下可产出可分发的 Electron 包；
4. 检查跨平台构建——若面向多平台，确认各目标（Windows/Linux/macOS）均可产出。

打包方面的要点（详见 Package Building）：

• ASP.NET 应用使用文件夹发布 +SelfContained=true；控制台应用使用文件夹发布 +SelfContained=false；
• 发布过程会自动安装 npm 依赖并运行 electron-builder；
• 在 Windows 上发布 Linux 配置时，ElectronNET 会自动借助 WSL 完成平台相关步骤；
• macOS 构建不能在 Windows 上进行（需要符号链接，Windows 不支持），需在 Linux 或 macOS 上完成。

常见迁移问题排查

构建错误

• Node.js 版本问题：确认 Node.js 22.x 已安装且在 PATH 中；
• 包冲突：必要时清理 NuGet 缓存（如dotnet nuget locals all --clear）。

运行时错误

• 缺少 electron-builder.json：触发一次重建或手动 NuGet restore，让 MSBuild 自动生成该文件；
• 进程无法终止：改用 .NET-first 启动模式（-unpackeddotnet/-dotnetpacked），由 .NET 管理 Electron 子进程生命周期，清理更彻底。

从 StartupManager.cs 的源码看，运行时通过命令行参数（electronPort、electronHost、electronPID、electronAuthToken）与 Electron 进程交换握手信息，因此排查启动类问题时，也可以关注这些参数是否被正确传递。

高级迁移主题速览

对于复杂项目，Advanced Migration Topics 提供了三类进阶指导：

1. 自定义 ASP.NET 端口：旧版在electron.manifest.json中指定 WebPort 的方式已废弃（ASP.NET-first 启动模式下该时机不成立），改为通过 MSBuild 元数据注入：

<ItemGroup> <AssemblyMetadata Include="AspNetHttpPort" Value="4000" /> </ItemGroup>

对应的解析逻辑可在StartupManager.GatherBuildInfo()中看到：它读取入口程序集上的AssemblyMetadataAttribute，将AspNetHttpPort解析为ElectronNetRuntime.AspNetWebPort。

2. 自定义 ElectronHostHook：仅当你在项目中使用自定义 ElectronHostHook 实现时才需要处理。如果你未改动过该代码、也未使用其演示功能（Excel 与 ZIP），可以直接从项目中移除ElectronHostHook文件夹。否则需要升级package.json中的@types/node（^22.18）、typescript（^5.9.3）、socket.io（^4.8.1），并在项目文件中引入Microsoft.TypeScript.MSBuild及相应的TypeScriptModuleKind/TypeScriptUseNodeJS/TypeScriptTSConfig属性。

3. 多项目解决方案：类库项目只装ElectronNET.Core.Api，启动项目装ElectronNET.Core（ASP.NET 项目再加ElectronNET.Core.AspNet），配置通过项目引用或共享文件传递。

迁移收益总结

迁移到ElectronNET.Core带来的核心收益（对照 What's New）：

• ✅配置简化——告别 CLI 工具与手工 JSON，一切走 Visual Studio 项目系统；
• ✅调试体验升级——原生 Visual Studio 调试 + Hot Reload，无需手动附加进程；
• ✅现代架构——.NET-first 进程生命周期，Electron 作为子进程由 .NET 管理，退出清理更可靠；
• ✅跨平台就绪——可在 Windows 上直接构建并调试 Linux 应用（WSL 集成）；
• ✅面向未来——不再与固定 Electron 版本强耦合，可灵活选择 Electron 版本，构建期做兼容性校验；
• ✅更广的适用面——移除 ASP.NET 硬性依赖，控制台应用也能承载 Electron 桌面应用，支持文件系统 HTML/JS、远程服务器等多种内容源。

下一步

• What's New——ElectronNET.Core 全部新特性总览；
• Advanced Migration Topics——复杂场景与边界情况处理；
• Getting Started / ASP.NET——迁移后的新开发工作流；
• Debugging——三种调试模式的详细配置；
• Startup Methods——8 种启动场景的进程流程详解；
• Package Building——面向多平台的分发包构建。

• 桌面应用
• 跨平台