Neutralinojs 项目实战初体验（踩坑指南），干翻 electron

Neutralinojs 官方文档

卧槽卧槽，！这个年轻人居然用浏览器把电脑关机了_哔哩哔哩_bilibili正是在下

本教程搭建的是纯原生项目，没有和其它前端框架绑定。

如果反响还不错的话，就出集成框架（vue3）的内容。（集成react官方已提供）

本文将会搭建一个桌面端程序如图所示

本项目实现了一个所见即所得的网页实时操作页面，旨在演示一些如何搭建项目，并介绍Neutralinojs中的一些常见api，包括IPC消息通讯，托盘，消息通知等

什么是 Neutralinojs？

Neutralinojs 是一个轻量级可移植的桌面应用程序开发框架适用于 Linux、macOS 和 Windows 的预构建 x64 二进制文件。它可以让你使用 JavaScript, HTML 和 CSS 开发轻量的跨平台桌面应用。 您可以使用任何编程语言（通过扩展 IPC）扩展 Neutranojs，并将 NeutranoJS 用作任何代码的一部分（通过子进程 IPC）。

在 Electron 和 NWjs 中，你必须安装 Node.js 和成百上千的依赖库。内嵌的 Chromium 和 Node 使简单的应用也变的很臃肿。 Neutralizojs 提供了一个轻量级和可移植的 SDK，它是 Electron 和 NW.js 的替代品。 Neutralizojs不捆绑 Chromium，而是在操作系统中使用现有的 web 浏览器库（例如在 Linux 中使用 gtk-webkit2）。 Neutralizojs 为本机操作实现了 WebSocket 连接，并嵌入了一个静态 web 服务器来提供 web 内容。 此外，它还为开发人员提供了一个内置的 JavaScript 客户端库。

在使用neu cli运行neu run时候会提供一个websocket服务,我扒代码的时候发现的，如图（neu cli源码片段）

neutralinojs 是官方提供的一个 JavaScript 客户端库（也称为 Neutralino.js）供开发人员进行交互，他是如何与neu cli进行交互的呢？？？

没错是websocket,neutralinojs会发起websocket连接，进行发送和接收数据，如图（neutralinojs源码片段）

！！！！于是，这个框架的工作原理就很清楚了

当我们使用脚手架的时候执行neu run或运行neu build打包后的可执行exe文件的时候，后台会默认启动一个websocket服务，前端页面使用neutralinojs 会发起websocket连接，前端需要调用底层代码的时候，就发送websocket给后台，后台调用系统级别的api，执行相应的操作，然后返回对应的操作结果（可能是对象，或者其它类型的数据）

提供多种模式

• window

  Neutralinojs 应用程序将在本机窗口上运行。该窗口将使用用户的操作系统主题。 此模式是跨平台应用程序开发的不错选择。

• browser

  Neutralinojs 应用程序将使用用户的默认浏览器来加载应用程序。 因此，您可以使用本机操作构建 Web 应用程序。您通常无法访问操作 通过 Web 浏览器提供系统级功能。但是，Neutralinojs 浏览器模式可帮助您制作可以 使用所需的安全控制访问操作系统层。

• cloud

  此模式将 Neutralinojs 进程作为后台服务器运行。 您将能够将应用程序公开到公共网络或 Internet。可以实现手机远程操作电脑客户端功能，类似ssh

  卧槽卧槽，！这个年轻人居然用浏览器把电脑关机了_哔哩哔哩_bilibili正是在下

• chrome

  Neutralinojs 应用程序将作为 Chrome 应用程序运行。该框架使用以下 Chrome 命令行 使 Web 应用程序看起来更像本机应用程序的参数。

提供各种原生 api

• 系统信息
• 剪切板
• 文件系统
• os

可选开放的权限

用户可以在neutralino.config.json中，配置设置开发的系统原生 api 权限

全局变量

用户可以在neutralino.config.json中，配置各种全局变量，统一配置管理

自动更新

• 提供简单易操作的更新功能

• 打包大小 neu build

  • 空项目打包只有 2.45M（electron40-50M）!!!

• 打包速度

  • 毫秒级 （空项目）
  • 快！！！！按下键盘就打包完了！！！！

• 项目运行速度 neu run

  • 基本秒起（空项目）

因为某些不可抗的原因,按照官方示例步骤，一步一步去搭建项目有时候会报错/(ㄒ o ㄒ)/~~

所以下面是遇到错误的一些解决方案

初始化项目（开始踩坑）

我们将搭建一个和框架的无关的程序

1. 安装 neu CLI

neu CLI 是用来创建 Neutralionjs 程序的脚手架程序

npm install -g @neutralinojs/neu

如果您不想进行全局安装，请将 neu CLI 与 npx 一起使用。

npx @neutralinojs/neu <command>

2. 创建新应用

输入以下命令以搭建新应用的基架

neu create newdemo

很多人在执行到 neu create newdemo 的时候卡住不动了如图

这是由于某些不可抗力，导致某些镜像下载不下来
如何解决呢？？

如果下载没有问题的话（恭喜）会有这样的提示

你的项目结构是这样的！！！ 执行neu run就可以启动项目了！！

我们先来认识一下，项目目录下面的文件是干什么的

• .github

  • FUNDING.yml 作者用来拉赞助的

• .tmp（前面介绍过）

  • **.**各种临时文件

• bin（前面介绍过）

  • **.**
  • 存放的是一些用于启动 Neutralinojs 应用程序的主可执行程序，或者是一些辅助工具。用于配置或启动 Neutralinojs 应用，或者用于构建和打包应用程序。
  • 由于 Neutralinojs 旨在支持多个操作系统，因此 bin 文件夹可能包含针对不同操作系统（如 Windows、macOS、Linux）的特定二进制文件。
  • 用于存放与运行和构建应用程序相关的二进制文件和脚本。

• resources

  • icons 图片 图标
  • js
    • **.js各种需要用到的js文件按
    • **.d.ts各种类型声明文件
  • index.html 项目主入口
  • index.css 样式

• .gitignore git忽略文件

• LICENSE 许可证书

• neutralino.config.json 配置文件！！！！！！！非常重要，需要细说

• neutralinojs.log 日志

3.如果下载一直卡顿，并且项目结构不是上面图片这样目录结构，或者缺失东西，项目跑步起来，那么请按照下面的步骤操作！！！(踩坑吧！！！！)

停止下载（很多时候是网络问题，多试一下，实在不行才进行下面的操作）

此时本地目录会存在一个 newdemo 文件夹，里面可能包含以下这些内容

和完整项目对比，明显会发现多了和少了很多文件

这时候我们就需要删除多余的文件，补充缺少的文件！！！！

删除.tmp目录

• 这个文件是一个缓存临时文件夹的地方，会存在大量缓存内容，只会在搭建项目中途出现，网友们的这个文件夹中的内容应该是各不相同，因为不知道网络会卡在构建项目的某个步骤，所以这个临时缓存文件夹内容是不一样的。

• 你咋知道.temp目录干啥的？？？答：我是在分析neu-cli脚手架源码的时候发现的，它会进行以下三步操作，每一步操作都会在临时文件夹里面产生一些东西，所以你会卡在什么奇怪的地方是不确定的

新建bin文件夹

• 你咋知道bin文件的？？？答：我在分析neu-cli脚手架源码的时候发现的，

• • 介绍一下：bin这个文件目录里面存放的是一些用于启动 Neutralinojs 应用程序的主可执行程序，或者是一些辅助工具。用于配置或启动 Neutralinojs 应用，或者用于构建和打包应用程序。
  • 由于 Neutralinojs 旨在支持多个操作系统，因此 bin 文件夹可能包含针对不同操作系统（如 Windows、macOS、Linux）的特定二进制文件。
  • 用于存放与运行和构建应用程序相关的二进制文件和脚本。

• 长这样

• 你要问了？这些文件从哪里来的？？？？

  • 首先到neutralinojs官方项目地址里面GitHub - neutralinojs/neutralinojs: Portable and lightweight cross-platform desktop application development framework

  • 长这样

  • 然后点这里，找到官方发布的二进制文件

  • 我这里最新是5.2.0(2024/07/29已经是5.3.0版本了，支持背景透明)版本点击下载解压就可以了

  • 压缩包里面就是这样

  • 把里面的文件全部放在bin文件目录就可以了！！！！！

添加neutralino.js

• neutralinojs 是官方提供的一个 JavaScript 客户端库（也称为 Neutralino.js）供开发人员进行交互

• 正常情况下会有这个文件目录

• 这个目录下面存放我们的自己写的项目代码

• 如果下载存在问题会缺失js文件目录下面的neutralino.js和neutralino.d.ts

• 他们俩分别是我们开发中要使用到的包和它的类型声明文件

• 你又要问了！！！如何获取呢？？？？

• 访问地址GitHub - neutralinojs/neutralino.js: JavaScript API for Neutralinojs
  

• 执行命令
  npm install @neutralinojs/lib
  # --- or ---
  yarn add @neutralinojs/lib
  

• 然后再node_modules文件目录下面就能找到他们俩了，把他俩放在js目录下面，就ok了

启动项目！！！！

经过上面的步骤，我们的代码目录结构就成这样了

然后在控制台执行命令

neu run

出现一下画面

！！！！！恭喜你，项目启动成功

开始实战项目

认识项目目录

经过前面的步骤，我们已经可以把项目完美的启动起来了。

现在我们先来认识一下，项目目录下面的文件是干什么的

• .github

  • FUNDING.yml 作者用来拉赞助的

• .tmp（前面介绍过）

  • **.**各种临时文件

• bin（前面介绍过）

  • **.**
  • 存放的是一些用于启动 Neutralinojs 应用程序的主可执行程序，或者是一些辅助工具。用于配置或启动 Neutralinojs 应用，或者用于构建和打包应用程序。
  • 由于 Neutralinojs 旨在支持多个操作系统，因此 bin 文件夹可能包含针对不同操作系统（如 Windows、macOS、Linux）的特定二进制文件。
  • 用于存放与运行和构建应用程序相关的二进制文件和脚本。

• resources

  • icons 图片 图标
  • js
    • **.js各种需要用到的js文件
    • **.d.ts各种类型声明文件
  • index.html 项目主入口
  • index.css 样式

• .gitignore git忽略文件

• LICENSE 许可证书

• neutralino.config.json 配置文件！！！！！！！非常重要，需要细说

• neutralinojs.log 日志

neutralino.config.json详解

{
  "$schema": "https://raw.githubusercontent.com/neutralinojs/neutralinojs/main/schemas/neutralino.config.schema.json",// 配置schema。。没研究过
  "applicationId": "js.neutralino.sample",// 应用id
  "version": "1.0.0",// 版本号
  "defaultMode": "window",// 默认模式 有四种模式 对应下面的 modes属性
  "port": 0,// 开发端口
  "documentRoot": "/resources/",// 对应项目文件中的文件目录
  "url": "/",// url相对路径
  "enableServer": true,// 能够启动服务
  "enableNativeAPI": true,// 支持原生api
  "tokenSecurity": "one-time",//【cloud模式】 one-time服务器只发送一次token，客户端将保留，其它客户端访问的时候将报错，推荐；如果不传，所有客户端都能访问；您可以使用该身份验证详细信息从外部进程连接到 Neutralinojs WebSocket 作为 IPC 机制
  "exportAuthInfo":true,// 将身份验证详细信息导出到文件中。${NL_PATH}/.tmp/auth_info.json //您可以使用该身份验证详细信息从外部进程连接到 Neutralinojs WebSocket 作为 IPC 机制
  "logging": {// 日志
    "enabled": true,
    "writeToLogFile": true
  },
	// 原生api允许列表 ！！！！！！！这个很重要，需要自己设置开放那些权限，官方文档有对这些权限的介绍  
  "nativeAllowList": [
    "app.*",
    "os.*",
    "debug.log"
  ],
// 项目中可以使用到的全局变量  
  "globalVariables": {
    "TEST1": "Hello",
    "TEST2": [
      2,
      4,
      5
    ],
    "TEST3": {
      "value1": 10,
      "value2": {}
    }
  },
  // 可选的模式，使用不同的模式，项目使用的效果也不一样
  "modes": {
// 窗口设置  
    "window": {
      "title": "test1",
      "width": 800,
      "height": 500,
      "minWidth": 400,
      "minHeight": 200,
      "center": true,
      "fullScreen": false,
      "alwaysOnTop": false,
      "icon": "/resources/icons/appIcon.png",
      "enableInspector": true,
      "borderless": false,
      "maximize": false,
      "hidden": false,
      "resizable": true,
      "exitProcessOnClose": false,
      "trasparent":true,// 窗口透明，5.3v版本开始支持（我现在是5.2v，快了）
      "nativeAllowList": [
        "app.*"
      ]// 允许的权限
    },
    "browser": {
    // 全局变量
      "globalVariables": {
        "TEST": "Test value browser"
      },
      // 锁定权限列表
      "nativeBlockList": [
        "filesystem.*"
      ]
    },
    "cloud": {
    // 请求路径
      "url": "/resources/#cloud",
      "nativeAllowList": [
        "app.*"
      ]
    },
    "chrome": {
      "width": 800,
      "height": 500,
      "args": "--user-agent=\"Neutralinojs chrome mode\"",
      // 锁定的权限
      "nativeBlockList": [
        "filesystem.*",
        "os.*"
      ]
    }
  },
  // 脚手架相关的
  "cli": {
    "binaryName": "test1",
    "resourcesPath": "/resources/",
    "extensionsPath": "/extensions/",
    "clientLibrary": "/resources/js/neutralino.js",
    "binaryVersion": "5.2.0",//！！！！！！！！！！！！！！！！！！！！！！！！！！！这里版本对应的二进制文件的版本，一定要是同一个版本
    "clientVersion": "5.2.0"//！！！！！！！！！！！！！！！！！！！！！！！！！！！！这里版本对应的二进制文件的版本，一定要是同一个版本
  }
}

具体更详细内容，请参考官方文档Introduction | Neutralinojs

resources目录详解

• icons图标图片
• js
  • main.js业务逻辑代码
  • neutralino.js项目核心库（neutralino支持的各种api都在它身上）
  • neutralino.d.ts项目核心库类型声明文件
• index.html应用界面
• styles.css样式

初始化代码

• main.js

  • 先清空，后面我们交互逻辑都会放在这个文件里面

• index.html

  • <!DOCTYPE html>
    <html>
      <head>
        <meta charset="UTF-8" />
        <title>所见即所得</title>
        <link rel="shortcut icon" href="./icon.ico" />
        <link rel="stylesheet" href="./styles.css" />
      </head>
      <body>
        <!-- <div id="neutralinoapp">
          <h1>嘻嘻嘻嘻嘻嘻嘻嘻neutralino.js嘻嘻嘻嘻嘻嘻嘻嘻嘻</h1>
          <div id="info"></div>
          <img src="/icons/logo.gif" alt="Neutralinojs" />
        </div>
        <div style="display: flex">
          
        </div> -->
        <div class="contain">
          <div class="left">
            <div class="box">
              <div class="title">HTML</div>
              <textarea id="html-val"></textarea>
            </div>
            <div class="box">
              <div class="title">CSS</div>
              <textarea id="css-val"></textarea>
            </div>
            <div class="box">
              <div class="title">JS</div>
              <textarea id="js-val"></textarea>
            </div>
          </div>
          <div class="right">
            <div class="box">
              <div class="title">实际效果</div>
              <iframe id="show-container"></iframe>
            </div>
            <div class="box">
              <div class="title">控制台</div>
              <div id="log-val"></div>
            </div>
          </div>
        </div>
        <script src="./js/neutralino.js"></script>
        <script src="./js/index.js"></script>
    
        <!-- Your app's source files -->
        <!-- <script src="/js/main.js"></script> -->
      </body>
    </html>
    
    

• styles.css

  • * {
      margin: 0;
      padding: 0;
      box-sizing: border-box;
    }
    html,
    body {
      width: 100%;
      height: 100%;
    }
    .contain {
      width: 100%;
      height: 100%;
      display: flex;
    
      .left {
        color: white;
        min-width: 350px;
        width: 30%;
        height: 100%;
        background-color: white;
        padding: 0 20px;
        .box {
          width: 100%;
          height: 33%;
          display: flex;
          flex-direction: column;
          .title {
            background-color: silver;
            height: 10%;
            text-align: center;
          }
          textarea {
            background-color: black;
            color: white;
            padding: 20px;
            width: 100%;
            height: 90%;
            font-size: 20px;
          }
        }
      }
    
      .right {
        width: 70%;
        height: 100%;
        display: flex;
        flex-direction: column;
        .box {
          width: 100%;
          height: 50%;
          background-color: white;
          padding: 0 20px;
          .title {
            background-color: silver;
            height: 10%;
            text-align: center;
          }
          iframe {
            background-color: white;
            width: 100%;
            height: 89%;
          }
          #log-val::before {
            color: white;
            white-space: pre-wrap;
            content: '控制台输出 : ';
          }
          #log-val {
            height: 89%;
            overflow-y: scroll;
            color: rgb(240, 240, 132);
            background-color: black;
            width: 100%;
            padding: 10px;
            content: 'gege';
          }
        }
      }
    }
    

经过上面的初始化步骤，你的界面会变成这样！！！！！

main.js实现核心业务代码（建议提前去官网看看api文档）

main.js

// 防抖函数
let debounce = (func, delay) => {
    let timeout = null;
    return function () {
        const _this = this
        const args = [...arguments]
        if (timeout) {
            clearTimeout(timeout)
        }
        timeout = setTimeout(() => {
            func.apply(_this, args)
        }, delay)
    };
};
// 节流函数
let throttle = (func, wait) => {
    let previous = Date.now();
    return function () {
        let now = Date.now();
        let context = this;
        let args = arguments;
        if (now - previous > wait) {
            func.apply(context, args);
            previous = now;
        }
    }
};


// console.log(Neutralino, 'Neutralino')
// 设置系统右下角托盘
const setTray = () => {
    // 托盘只在window模式下支持
    if (NL_MODE != "window") {
        console.log("INFO: 托盘只在window模式下支持.");
        return;
    }
    // 托盘项
    let tray = {
        icon: "/resources/icons/trayIcon.png",
        menuItems: [
            { id: "openBaidu", text: "打开百度" },
            // 分割线条
            { id: "SEP", text: "-" },
            { id: "VERSION", text: "Get version" },
            // 分割线条
            { id: "SEP", text: "-" },
            { id: "提示文字", text: "提示文字" },
            // 分割线条
            { id: "SEP", text: "-" },
            { id: "QUIT", text: "Quit" }
        ]
    };

    // 设置系统托盘
    Neutralino.os.setTray(tray);
}
// 托盘右击事件
const onTrayMenuItemClicked = (event) => {
    switch (event.detail.id) {
        case "VERSION":
            // Display version information
            Neutralino.os.showMessageBox("Version information",
                `Neutralinojs server: v${NL_VERSION} | Neutralinojs client: v${NL_CVERSION}`);
            break;
        case "openBaidu":
            // 打开指定网页
            Neutralino.os.open("https://www.baidu.com");
            break;
        case "提示文字":
            Neutralino.os.showMessageBox("我是提示标题", `我是提示文字内容`);
            break;
        case "QUIT":
            // Exit the application
            Neutralino.app.exit();
            break;
    }
}
// 窗口关闭事件
const onWindowClose = () => {
    Neutralino.app.exit();
}
/**
 * 万物起源，先调用init方法，然后才能使用任何 原生 API 函数!!!!
 * 执行init方法的时候，内部会发起websocket连接，打通交互逻辑
 */
Neutralino.init()
// 监听 客户端库与 Neutralino 服务器连接成功触发事件。
Neutralino.events.on('ready', async () => {
    // 弹出一个提示窗口
    Neutralino.os.showMessageBox('red润提醒您', 'Hello Neutralinojs');
    // 从剪切板获取数据
    // let format = await Neutralino.clipboard.getFormat();
    // console.log(`Format: ${format}`);
    // 给剪切板设置文字
    // await Neutralino.clipboard.writeText('Test value');
    // 给剪切板设置图片
    // let image = prepareClipboardImage();
    // await Neutralino.clipboard.writeImage(image);
    // 从剪切板获取文字
    // let clipboardText = await Neutralino.clipboard.readText();
    // console.log(`Text: ${clipboardText}`);
    // // 从剪切板获取图片
    // let clipboardImage = await Neutralino.clipboard.readImage();
    // console.log(`Image: ${clipboardImage}`);
    // 选择提示框
    // let button = await Neutralino.os
    //     .showMessageBox('Confirm',
    //         'Are you sure you want to quit?',
    //         'YES_NO', 'QUESTION');
    // if (button == 'YES') {
    //     Neutralino.app.exit();
    // }
    // 右下角提示，目前win11支持异常，已经有人提了pr，待官方更新中
    // await Neutralino.os.showNotification('Hello world', 'It works! Have a nice day');
    // // 错误类型的提示
    // await Neutralino.os.showNotification('Oops :/', 'Something went wrong', 'ERROR');

});
// 苹果系统没有托盘
if (NL_OS != "Darwin") {
    setTray();
}
// 监听用户单击托盘时候触发
Neutralino.events.on("trayMenuItemClicked", onTrayMenuItemClicked);
// 监听用户关闭窗口时触发事件。
Neutralino.events.on("windowClose", onWindowClose);

// 获取配置文件信息
// Neutralino.app.getConfig().then(res => {
//     console.log(res, 'getConfig')
// })
// 获取windows系统环境变量
// Neutralino.os.getEnvs().then(res => {
//     console.log(res, 'getEnvs')
// })
// 输出系统信息
console.log(`
    APPID:${NL_APPID}
    PORT:${NL_PORT}
    OS:${NL_OS}
    SERVER:v${NL_VERSION}
    CLIENT:v${NL_CVERSION}
    MODE:${NL_MODE}
`);


const htmlValEle = document.querySelector("#html-val");
const cssValEle = document.querySelector("#css-val");
const jsValEle = document.querySelector("#js-val");
const logValEle = document.querySelector('#log-val')
/**
 * @type {HTMLIFrameElement}
 */
const showContainerEle = document.querySelector('#show-container')
// 初始化值
let htmlVal = htmlValEle.value = "<button onclick='test()'>hello world</button>";
let cssVal = cssValEle.value = "h1{color:red;}";
let jsVal = jsValEle.value = "function test(){alert('12334');}";
// 控制台记录行数
let countLine = 1;

const run = (htmlVal, cssVal, jsVal) => {
    // 界面和样式
    showContainerEle.contentDocument.body.innerHTML = htmlVal + `<style>${cssVal}</style>`;
    // 计算js
    showContainerEle.contentWindow.eval(jsVal);
    // 拦截console,自定义自己的逻辑
    showContainerEle.contentWindow.console.log = (val) => {
        logValEle.innerText = logValEle.innerText + "\n第" + countLine + "行:" + val;
        countLine++;
    }
}

run(htmlVal, cssVal, jsVal)
// 节流稳定输出
const htmlFunc = throttle((e, d) => {
    // oldconsole(e.target.value, 'e,d')
    htmlVal = e.target.value;
    run(htmlVal, cssVal, jsVal)
}, 100)
const cssFunc = throttle((e, d) => {
    // oldconsole(e.target.value, 'e,d')
    cssVal = e.target.value;
    run(htmlVal, cssVal, jsVal)
}, 100)
// 防抖防止拼写错误的时候，频繁提示错误
const jsFunc = debounce((e, d) => {
    // oldconsole(e.target.value, 'e,d')
    jsVal = e.target.value;
    run(htmlVal, cssVal, jsVal)
}, 1000)



// 监听事件
htmlValEle.addEventListener('input', htmlFunc)
cssValEle.addEventListener('input', cssFunc)
jsValEle.addEventListener('input', jsFunc)

最终效果!!!

完结。

还有很多东西没讲完，比如比如和前端框架整合vue,react,自动更新，实现远程控制等。如果需要学习这块的人比较多的话，就更新。

这个库相对于electron还是简单许多，把官方api文档读一遍就基本没问题了

拜！