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 = thisconst 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 informationNeutralino.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 applicationNeutralino.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>`;// 计算jsshowContainerEle.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文档读一遍就基本没问题了

拜！