Electron/Node 本地集成 C#/.NET，node-api-dotnet

Electron/Node 本地集成 C#/.NET，node-api-dotnet 是否应该优先推荐？

在 Electron 桌面应用里，经常会遇到一个问题：前端页面是 React、Vue 或 Angular，业务主流程在 Node/Electron 里，但很多本地能力又更适合用 C#/.NET 实现。

比如：

txt 复制代码

获取机器码
读取 Windows 注册表
调用本地 SDK
调用加速器 DLL
操作本地文件
调用系统服务
处理复杂本地业务逻辑
复用已有 C# 代码

这时就会出现几种方案：

txt 复制代码

Electron 直接调用 C# EXE
Electron 通过 gRPC 调 C# 本地服务
Electron 通过 koffi 调 C/C++ DLL
Electron 通过 C++ 桥接 CLR
Electron/Node 通过 node-api-dotnet 调 C#/.NET

那么，在 Electron/Node 本地集成 C#/.NET 的方案里，node-api-dotnet 是否应该优先推荐？

我的结论是：

对于绝大多数 Electron/Node 调用 C#/.NET 本地能力的场景，node-api-dotnet 可以作为第一优先级方案。

但它不是所有场景的唯一答案。如果你的第三方 SDK 非常不稳定，容易崩溃，或者你需要强隔离，那么 C# 本地服务 / 子进程 / gRPC 会更稳。

一、先给结论

可以把几种方案简单对比如下：

方案	推荐度	性能	复杂度	适合场景
node-api-dotnet	⭐⭐⭐⭐⭐	高	中低	Electron/Node 调用 C#/.NET 类库
C# 本地服务 / gRPC	⭐⭐⭐⭐	中高	中	强隔离、长任务、易崩溃 SDK
C# EXE 子进程	⭐⭐⭐⭐	中	低中	简单命令调用、进程隔离
koffi	⭐⭐⭐	高	中	调用 C/C++ 原生 DLL
C++ 桥接 CLR	⭐⭐	高	高	老项目、特殊 CLR 托管场景

如果你是新项目，并且目标是：

txt 复制代码

Electron + React
Node 主进程
C#/.NET 本地能力
Windows 桌面端

那么推荐架构是：

txt 复制代码

React 页面
  ↓
preload.js 暴露安全 API
  ↓
ipcRenderer.invoke(...)
  ↓
Electron main process
  ↓
node-api-dotnet
  ↓
C# NativeBridge.dll
  ↓
Windows API / 本地 SDK / 业务逻辑

这个架构的核心思想是：

页面只负责 UI，Electron 主进程负责调度，C# 负责本地能力。

二、为什么 node-api-dotnet 值得优先考虑？

node-api-dotnet 的最大价值是：它可以让 Node.js/Electron 直接加载 .NET 程序集，并调用 C# 里导出的类和方法。

也就是说，你不需要自己写 C++ 桥接层，也不需要把 C# 做成 HTTP 服务，更不需要让前端页面直接碰系统能力。

例如，你可以在 C# 里写：

csharp 复制代码

public static string GetMachineCode()
{
    return Environment.MachineName;
}

然后在 Electron 主进程里像调用普通模块一样调用它：

js 复制代码

const code = bridge.NativeBridge.GetMachineCode();

这对于 Electron 本地集成非常有吸引力。

它的优势主要有几个：

txt 复制代码

1. 微软官方项目，方向更正
2. 进程内调用，性能比 HTTP/gRPC 更直接
3. 不需要自己托管 CLR
4. 可以复用 C#/.NET 代码
5. 比 C++ 桥接方案简单
6. 适合封装 Windows 本地能力
7. 可以和 Electron IPC 安全模型配合

对于你的这类场景，比如：

txt 复制代码

Electron 启动加速
Electron 停止加速
Electron 获取机器码
Electron 调用本地 SDK
Electron 调用 Windows 服务
Electron 做 AI Coding 编辑器本地文件能力

node-api-dotnet 都是比较合适的。

三、它适合什么场景？

1. Electron 调用 C# 本地工具类

例如：

txt 复制代码

获取机器码
获取系统版本
读取本地配置
读写本地文件
检测进程
检测端口
调用 Windows API

这些功能用 C# 写通常更方便，再通过 node-api-dotnet 暴露给 Electron。

2. Electron 调用已有 .NET 业务代码

如果你的公司已有 C# 代码，比如：

txt 复制代码

授权逻辑
设备识别
加密解密
SDK 封装
本地资源扫描
系统环境检测

没有必要全部重写成 Node.js。可以直接把这部分封装成 .NET Class Library，再给 Node/Electron 调用。

3. Electron + React 做桌面应用

推荐结构是：

txt 复制代码

React Renderer：只负责页面
preload.js：只暴露白名单 API
main.js：处理 IPC 和本地能力调度
C# DLL：封装真正的系统能力

不要让 React 页面直接调用 Node.js、C#、文件系统、命令行。这样做安全性更好，也更容易维护。

4. AI Coding 编辑器、本地工作台、桌面工具

如果你要做一个类似本地 AI Coding 编辑器的应用，结构可以是：

txt 复制代码

React：代码编辑器 UI
Electron main：AI 请求、本地文件调度
C# NativeBridge：文件系统、进程、命令、Windows SDK
node-api-dotnet：Node 和 C# 的桥

例如：

txt 复制代码

打开项目
读取目录
读取文件
保存文件
执行命令
获取 Git 状态
调用本地模型
调用 Windows SDK

这些都可以通过 C# 桥接层封装。

四、它不适合什么场景？

虽然我推荐优先考虑 node-api-dotnet，但它并不是万能方案。

1. 第三方 SDK 很容易崩溃

如果你调用的是某个不稳定的本地 SDK，一旦崩溃可能影响 Electron 主进程，那么不建议直接进程内调用。

这种场景建议：

txt 复制代码

Electron
  ↓
C# 子进程 / Windows Service
  ↓
第三方 SDK

进程隔离的好处是：SDK 崩了，主程序不一定跟着崩。

2. 任务非常重、耗时非常长

例如：

txt 复制代码

大型文件扫描
视频处理
模型推理
批量压缩
长时间网络任务

这种任务不建议直接阻塞 Electron 主进程。可以用：

txt 复制代码

C# Worker 进程
gRPC
HTTP 本地服务
消息队列

3. 你调用的是纯 C/C++ DLL

如果第三方 SDK 本身就是标准 C/C++ DLL，并且导出了明确的 C 函数，例如：

c 复制代码

int StartAccelerator(const char* config);
int StopAccelerator();

那可以优先考虑 koffi 或 ffi-napi 这类 Node 原生 FFI 方案。

但是如果你要调用的是 C# 类库，koffi 就不是最佳选择。因为 koffi 更适合 C ABI，不适合直接调用普通 C# DLL。

4. 你需要跨进程权限隔离

如果你的本地能力涉及：

txt 复制代码

管理员权限
系统服务
驱动通信
高危命令执行
网络代理
游戏加速
虚拟网卡

建议把高权限能力放到独立 C# 服务里，Electron 只负责调用服务接口。

五、推荐的工程结构

一个比较合理的项目结构如下：

txt 复制代码

my-electron-app
├─ package.json
├─ electron
│  ├─ main.js
│  └─ preload.js
├─ renderer
│  └─ React 页面
├─ native
│  └─ NativeBridge
│     ├─ NativeBridge.csproj
│     └─ NativeBridge.cs
└─ dist

职责划分如下：

txt 复制代码

renderer：页面 UI
preload：安全 API 白名单
main：Electron 主进程、IPC、调用 C#
native：C# 本地能力封装

不要把所有东西都堆在前端页面里。

六、最小 Hello World 示例

下面做一个最小例子：

目标：

txt 复制代码

React 页面点击按钮
  ↓
调用 window.nativeAPI.hello('xunweiyun')
  ↓
preload 转发到 Electron main
  ↓
main 通过 node-api-dotnet 调用 C#
  ↓
C# 返回 Hello 消息

1. 创建 C# 类库

bash 复制代码

mkdir NativeBridge
cd NativeBridge

dotnet new classlib --framework net8.0
dotnet add package --prerelease Microsoft.JavaScript.NodeApi
dotnet add package --prerelease Microsoft.JavaScript.NodeApi.Generator

2. 编写 C# 导出方法

新建 NativeBridge.cs：

csharp 复制代码

using Microsoft.JavaScript.NodeApi;

namespace NativeBridge;

public static class LocalApi
{
    [JSExport]
    public static string Hello(string name)
    {
        return $"Hello {name}, from C# .NET";
    }

    [JSExport]
    public static string GetMachineCode()
    {
        return $"{Environment.MachineName}-{Environment.UserName}";
    }

    [JSExport]
    public static string StartAccelerator(string gameId)
    {
        // 这里后续可以替换成真实加速 SDK 调用
        return $"accelerator started, gameId={gameId}";
    }

    [JSExport]
    public static string StopAccelerator(string gameId)
    {
        // 这里后续可以替换成真实停止加速 SDK 调用
        return $"accelerator stopped, gameId={gameId}";
    }
}

编译：

bash 复制代码

dotnet build

编译成功后会得到类似文件：

txt 复制代码

NativeBridge/bin/Debug/net8.0/NativeBridge.dll

3. Electron 安装 node-api-dotnet

在 Electron 项目根目录安装：

bash 复制代码

npm install node-api-dotnet

4. Electron main.js 调用 C#

js 复制代码

const path = require('path');
const { app, BrowserWindow, ipcMain } = require('electron');
const dotnet = require('node-api-dotnet/net8.0');

let bridge;

function loadNativeBridge() {
  const dllPath = path.join(
    __dirname,
    '../native/NativeBridge/bin/Debug/net8.0/NativeBridge.dll'
  );

  bridge = dotnet.require(dllPath);
}

function createWindow() {
  const win = new BrowserWindow({
    width: 1200,
    height: 800,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      nodeIntegration: false,
      contextIsolation: true,
      sandbox: false
    }
  });

  win.loadURL('http://localhost:5173');
}

app.whenReady().then(() => {
  loadNativeBridge();

  ipcMain.handle('native:hello', async (_, name) => {
    return bridge.LocalApi.Hello(name);
  });

  ipcMain.handle('native:getMachineCode', async () => {
    return bridge.LocalApi.GetMachineCode();
  });

  ipcMain.handle('accelerator:start', async (_, gameId) => {
    return bridge.LocalApi.StartAccelerator(gameId);
  });

  ipcMain.handle('accelerator:stop', async (_, gameId) => {
    return bridge.LocalApi.StopAccelerator(gameId);
  });

  createWindow();
});

5. preload.js 暴露安全 API

js 复制代码

const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('nativeAPI', {
  hello: (name) => ipcRenderer.invoke('native:hello', name),
  getMachineCode: () => ipcRenderer.invoke('native:getMachineCode'),
  startAccelerator: (gameId) => ipcRenderer.invoke('accelerator:start', gameId),
  stopAccelerator: (gameId) => ipcRenderer.invoke('accelerator:stop', gameId)
});

注意，不要这样做：

js 复制代码

contextBridge.exposeInMainWorld('electron', {
  ipcRenderer
});

因为这等于把完整 IPC 能力暴露给页面，风险比较大。

正确方式是只暴露你需要的白名单方法。

6. React 页面调用

jsx 复制代码

import { useState } from 'react';

export default function App() {
  const [message, setMessage] = useState('');

  async function handleHello() {
    const result = await window.nativeAPI.hello('xunweiyun');
    setMessage(result);
  }

  async function handleMachineCode() {
    const result = await window.nativeAPI.getMachineCode();
    setMessage(result);
  }

  async function handleStart() {
    const result = await window.nativeAPI.startAccelerator('cs2');
    setMessage(result);
  }

  async function handleStop() {
    const result = await window.nativeAPI.stopAccelerator('cs2');
    setMessage(result);
  }

  return (
    <div style={{ padding: 24 }}>
      <h1>Electron + React + C# node-api-dotnet Demo</h1>

      <button onClick={handleHello}>调用 C# Hello</button>
      <button onClick={handleMachineCode}>获取机器码</button>
      <button onClick={handleStart}>启动加速</button>
      <button onClick={handleStop}>停止加速</button>

      <pre>{message}</pre>
    </div>
  );
}

七、生产环境要注意什么？

1. 不要把 C# 调用放到 Renderer

错误方式：

txt 复制代码

React 页面直接 require('node-api-dotnet')

不推荐这样做。

正确方式：

txt 复制代码

React
  ↓
preload
  ↓
Electron main
  ↓
node-api-dotnet
  ↓
C#

2. 注意 .NET Runtime 依赖

如果你使用 runtime-dependent 模式，目标机器需要安装对应版本的 .NET Runtime。

比如你使用 .NET 8，那客户电脑上需要有 .NET 8 Runtime。

生产部署时可以选择：

txt 复制代码

方案 A：安装包检测并安装 .NET Runtime
方案 B：把 .NET Runtime 一起打包
方案 C：研究 Native AOT，减少运行时依赖

3. 第三方 SDK 不稳定时要做隔离

如果你调用的是游戏加速 SDK、驱动 SDK、网络 SDK，这类 SDK 一旦崩溃可能影响主进程。

这时建议改成：

txt 复制代码

Electron main
  ↓
C# Worker / Windows Service
  ↓
第三方 SDK

Electron 和 C# Worker 之间可以用：

txt 复制代码

gRPC
HTTP localhost
Named Pipe
WebSocket

4. 所有 IPC 都要做参数校验

不要相信前端传来的参数。

例如：

js 复制代码

ipcMain.handle('accelerator:start', async (_, gameId) => {
  if (typeof gameId !== 'string' || gameId.length > 64) {
    throw new Error('invalid gameId');
  }

  return bridge.LocalApi.StartAccelerator(gameId);
});

5. 异常要统一捕获

C# 方法可能抛异常，Node 侧要捕获：

js 复制代码

ipcMain.handle('native:hello', async (_, name) => {
  try {
    return {
      ok: true,
      data: bridge.LocalApi.Hello(name)
    };
  } catch (error) {
    return {
      ok: false,
      message: error.message
    };
  }
});

前端再统一处理：

js 复制代码

const res = await window.nativeAPI.hello('xunweiyun');

if (!res.ok) {
  alert(res.message);
}

八、最终推荐

如果你的项目是：

txt 复制代码

Electron 桌面端
React/Vue/Angular 前端
Node.js 主进程
需要调用 C#/.NET 本地能力

那么推荐优先考虑：

txt 复制代码

node-api-dotnet

它适合：

txt 复制代码

普通本地能力调用
复用 C# 代码
封装 Windows API
调用 .NET 类库
构建本地桌面工具
构建 AI Coding 编辑器
构建游戏启动器/加速器客户端

但是如果你的场景是：

txt 复制代码

第三方 SDK 容易崩溃
需要管理员权限
需要长期后台运行
需要系统服务
需要强隔离

则更建议：

txt 复制代码

C# 子进程 / Windows Service / gRPC

一句话总结：

Electron/Node 调 C#/.NET，普通本地集成优先 node-api-dotnet；高风险、高权限、易崩溃场景优先 C# 独立进程或本地服务。