Electron 如何调用 Windows 原生 API
做 Electron 桌面应用的时候，难免要和操作系统打打交道。在 Windows 上，这些需求说起来也不少：
- 调用 Windows Store API 搞应用内购买
- 处理 Windows Store 应用特有的文件系统虚拟化
- 获取系统级别的权限和资源
- 和 Windows Runtime (WinRT) 组件交互
Electron 说到底还是 Node.js 环境，而 Node.js 本来就不直接提供访问 Windows 原生 API 的能力。两者之间，需要一座桥。
这就像你想和不懂中文的朋友交流，中间总得有个翻译官。Electron 是用 JavaScript 写的，Windows API 是 C/C++ 写的，语言不通，得想办法搭个桥。代码世界的残酷就在这里，没什么人情的。
关于 HagiCode
本文分享的方案来自我们在 HagiCode 项目中的实践经验。HagiCode Desktop 需要调用 Microsoft Store API 来处理订阅购买和许可证管理，这便是我们摸索出一套技术方案的原因。毕竟有需求才有动力，这话一点不假。
技术方案对比
在 Electron 中调用 Windows 原生 API，有几种主流方案可以选择。每种方案都有其适用场景，就像工具箱里的不同工具，用对了地方才能发挥最大作用，用错了也只是徒增麻烦。
| 方案 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| dynwinrt | WinRT API (如 Store API) | 类型安全、自动生成绑定、现代 JavaScript 支持 | 只支持 WinRT API、需要 Windows SDK |
| 原生 Node.js 扩展 | 高性能、任何 Windows API | 完全控制、性能最优 | 需要 C++ 开发能力、跨平台复杂 |
| child_process + PowerShell | 临时性、一次性调用 | 简单快捷、无需编译 | 性能差、错误处理复杂 |
| edge.js/ffi-napi | 调用现有 DLL | 可复用现有库 | 兼容性问题、维护成本高 |
HagiCode Desktop 采用了混合方案：使用 dynwinrt 来访问 Windows Store API，使用原生 Node.js 扩展来处理高性能的 Store 购买操作，同时用 Node.js 原生 fs 和 path 模块处理 Windows Store 应用特有的文件系统虚拟化。能简单就简单，这也是我们的原则。
方案一：使用 dynwinrt 调用 WinRT API
dynwinrt 是 Microsoft 提供的一个工具链，可以基于 Windows SDK 的 metadata 文件自动生成 JavaScript 绑定。它专门用于调用 WinRT API，比如 Windows Store API。
安装依赖：
{ |
"optionalDependencies": { |
"@microsoft/dynwinrt": "0.1.0-preview.6", |
"@microsoft/dynwinrt-codegen": "0.1.0-preview.6" |
} |
} |
生成 WinRT 绑定：
// scripts/generate-store-bindings.js |
const { execFileSync } = 'node:child_process'; |
function generateStoreNamespace(windowsWinmdPath) { |
execFileSync('npx', [ |
'dynwinrt-codegen', |
'generate', |
'--winmd', windowsWinmdPath, |
'--namespace', 'Windows.Services.Store', |
'--output', 'src/main/subscription/generated-js', |
'--lang', 'js', |
]); |
} |
使用生成的绑定：
// 使用 dynwinrt 生成的 Store API 绑定 |
import { Windows } from '../subscription/generated-js/index.js'; |
async function queryStoreProduct(storeId: string) { |
const storeContext = Windows.Services.Store.StoreContext.getDefault(); |
const result = await storeContext.getAssociatedStoreProductsAsync(['Subscription', 'Durable']); |
if (result.extendedError !== 0) { |
throw new Error(`Store API error: ${result.extendedError}`); |
} |
return result.products.get(storeId); |
} |
dynwinrt 的好处是类型安全，生成的代码和现代 JavaScript 习惯一致。但它只能处理 WinRT API，如果你需要调用传统的 Win32 API，就得用别的方案了。工具就是这样，各有所长。
方案二：原生 Node.js 扩展
当需要高性能或者 dynwinrt 不支持的功能时，原生 Node.js 扩展是最佳选择。这个方案需要用 C++ 写代码，然后用 node-gyp 编译成 .node 文件。
创建 binding.gyp：
{ |
"targets": [{ |
"target_name": "windows-store-addon", |
"sources": ["src/windows-store-addon.cpp"], |
"include_dirs": [ |
"<!(node -e \"require('nan')\")" |
], |
"defines": [ |
"WIN32_LEAN_AND_MEAN" |
] |
}] |
} |
C++ 原生模块示例：
// src/windows-store-addon.cpp |
#include <nan.h> |
#include <windows.h> |
#include <wrl.h> |
#include <windows.services.store.h> |
using namespace v8; |
using namespace Windows::Services::Store; |
NAN_METHOD(QueryStoreStatus) { |
auto async = new Nan::AsyncWorker( |
[]() { |
// 调用 Windows Store API |
auto context = StoreContext::GetDefault(); |
auto products = context->GetAssociatedStoreProductsAsync(...)->GetResults(); |
// 处理结果 |
} |
); |
Nan::AsyncQueueWorker(async); |
} |
NAN_MODULE_INIT(InitModule) { |
Nan::Set(target, Nan::New("queryStoreStatus").ToLocalChecked(), |
Nan::GetFunction(Nan::New<FunctionTemplate>(QueryStoreStatus)).ToLocalChecked()); |
} |
NODE_MODULE(windows_store_addon, InitModule) |
编译和使用：
node-gyp rebuild |
import addon from './build/Release/windows-store-addon.node'; |
const result = addon.queryStoreStatus({ |
storeId: 'your-store-id', |
productKinds: ['Subscription', 'Durable'] |
}); |
原生扩展的性能是最好的，但开发成本也高。需要懂 C++，还要处理跨平台兼容问题。如果你的团队有 C++ 经验，或者性能要求特别高，这个方案值得投入。只是这条路走起来，终究是辛苦一些。
方案三：处理 Windows Store 应用虚拟化
Windows Store 应用运行在虚拟化环境中，路径映射需要特殊处理。HagiCode Desktop 用下面的函数来处理这个问题：
// src/main/windows-store-path-display.ts |
export function resolveWindowsStorePackageFamilyName(executablePath: string): string | null { |
const WINDOWS_APPS_SEGMENT = '\\windowsapps\\'; |
const windowsPath = executablePath.replace(/\//g, '\\'); |
const markerIndex = windowsPath.toLowerCase().indexOf(WINDOWS_APPS_SEGMENT); |
if (markerIndex < 0) return null; |
const relativePath = windowsPath.slice(markerIndex + WINDOWS_APPS_SEGMENT.length); |
const packageFullName = relativePath.split('\\', 1)[0]?.trim(); |
return packageFullName || null; |
} |
export function resolveWindowsStoreVirtualizedPhysicalPath( |
logicalPath: string, |
options: ResolveWindowsStorePathDisplayOptions = {} |
): string | null { |
const packageFamilyName = options.packageFamilyName |
?? resolveWindowsStorePackageFamilyName(options.execPath ?? process.execPath); |
if (!packageFamilyName) return null; |
const packageStorageRoot = path.win32.join( |
options.env.LOCALAPPDATA, |
'Packages', |
packageFamilyName |
); |
// 将虚拟化路径映射到物理路径 |
if (isPathWithinWindowsRoot(logicalPath, options.env.APPDATA)) { |
return path.win32.join( |
packageStorageRoot, |
'LocalCache', |