【跨桌面应用开发】Neutralinojs快速入门指南

参考文档：
Neutralinojs官网
 Neutralinojs中文文档

介绍

Neutralinojs 是一个轻量级、跨平台 的桌面应用开发框架，让你使用熟悉的 Web 技术（HTML、CSS、JavaScript）构建桌面应用。相比 Electron，它最大的优势是极小的体积 （空项目仅 ~2MB）和毫秒级构建速度。

核心优势

特性	Neutralinojs	Electron
空项目体积	~2MB	~50MB
构建速度	毫秒级	分钟级
内存占用	低	高
依赖	系统自带 WebView	捆绑 Chromium

环境准备

确保已安装 Node.js（建议 v16+），然后安装 CLI 工具：

bash 复制代码

# 全局安装 neu CLI
npm install -g @neutralinojs/neu

# 或使用 npx（无需全局安装）
npx @neutralinojs/neu <command>

Windows 用户注意：如果遇到 PowerShell 执行策略错误，以管理员身份运行：
powershell 复制代码
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

创建第一个应用

1. 初始化项目

bash 复制代码

neu create myapp
cd myapp

如果出现以下报错，可以使用命令set NODE_TLS_REJECT_UNAUTHORIZED=0，临时解决。

启动效果：

项目结构说明：

复制代码

myapp/
├── neutralino.config.json    # 核心配置文件
├── bin/                      # 二进制可执行文件
├── resources/                # 前端资源目录
│   ├── index.html           # 应用入口页面
│   ├── styles.css           # 样式文件
│   └── js/
│       ├── main.js          # 业务逻辑
│       └── neutralino.js    # 客户端库
└── dist/                    # 构建输出目录（自动生成）

2. 编写代码

resources/index.html：

html 复制代码

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>我的第一个 Neutralinojs 应用</title>
    <link rel="stylesheet" href="styles.css">
</head>
<body>
    <div id="app">
        <h1>Hello <span id="username"></span>!</h1>
        <p>欢迎使用 Neutralinojs</p>
        <button id="btn-exit">退出应用</button>
    </div>

    <script src="js/neutralino.js"></script>
    <script src="js/main.js"></script>
</body>
</html>

resources/js/main.js：

javascript 复制代码

// 初始化 Neutralino
Neutralino.init();

// 应用就绪后执行
Neutralino.events.on('ready', async () => {
    // 获取系统用户名
    const username = await Neutralino.os.getEnv('USER') || 
                     await Neutralino.os.getEnv('USERNAME');
    
    document.getElementById('username').textContent = username;
    
    // 绑定退出按钮
    document.getElementById('btn-exit').addEventListener('click', () => {
        Neutralino.app.exit();
    });
});

实现效果

优点：启动速度快(2-3s)，页面自动热更新

3. 配置权限

编辑 neutralino.config.json，确保允许使用的原生 API：

json 复制代码

{
  "applicationId": "com.example.myapp",
  "version": "1.0.0",
  "defaultMode": "window",
  "nativeAllowList": [
    "app.*",
    "os.*",
    "debug.log"
  ],
  "modes": {
    "window": {
      "title": "我的应用",
      "width": 800,
      "height": 600,
      "center": true,
      "resizable": true
    }
  }
}

4. 运行应用

bash 复制代码

neu run

支持热重载：修改代码后自动刷新

5. 构建发布

bash 复制代码

# 构建所有平台版本
neu build

# 构建并打包为 zip
neu build --release

构建完成后，dist/ 目录包含各平台的可执行文件和 resources.neu 资源包。

构建完成后文件大小仅2.5MB。

常用原生 API 示例

系统对话框

javascript 复制代码

// 消息框
await Neutralino.os.showMessageBox('提示', '操作成功！');

// 确认对话框
const button = await Neutralino.os.showMessageBox(
    '确认', 
    '确定要退出吗？', 
    'YES_NO', 
    'QUESTION'
);

if (button === 'YES') {
    Neutralino.app.exit();
}

文件操作

javascript 复制代码

// 读取文件
const data = await Neutralino.filesystem.readFile('./config.json');
const config = JSON.parse(data);

// 写入文件
await Neutralino.filesystem.writeFile('./output.txt', 'Hello World');

记得分配权限（编辑 neutralino.config.json），并且重启程序

"nativeAllowList": [

"app.*",

"filesystem.*"

]

系统托盘（Windows/Linux）

javascript 复制代码

if (NL_OS !== 'Darwin') {
    await Neutralino.os.setTray({
        icon: '/resources/icons/trayIcon.png',
        menuItems: [
            { id: 'show', text: '显示窗口' },
            { id: 'SEP', text: '-' },
            { id: 'quit', text: '退出' }
        ]
    });
}

Neutralino.events.on('trayMenuItemClicked', (event) => {
    if (event.detail.id === 'quit') {
        Neutralino.app.exit();
    }
});

通知

javascript 复制代码

await Neutralino.os.showNotification('新消息', '您有一条未读通知', 'INFO');

集成前端框架

Neutralinojs 支持 React、Vue、Svelte 等现代框架：

bash 复制代码

# 创建 React 项目
neu create hello-react -t codezri/neutralinojs-react

# 创建 Vue 项目  
neu create hello-vue -t codezri/neutralinojs-vue

常见问题

Q: Windows 上显示白屏？

A: 以管理员身份运行以下命令解除 UWP 限制：

cmd 复制代码

CheckNetIsolation.exe LoopbackExempt -a -n="Microsoft.Win32WebViewHost_cw5n1h2txyewy"

Q: 如何调试？

A: 右键点击应用窗口选择"检查"，或使用 Ctrl+Shift+I 打开 DevTools。

Q: 应用启动慢？

A: 确保 Windows 已安装 WebView2 运行时。

下一步

查阅官方文档了解完整 API
探索应用模式（窗口、无边框、服务器等）
学习扩展机制使用其他编程语言扩展功能