Neutralinojs 项目实战初体验（踩坑指南），干翻 electron
卧槽卧槽，！这个年轻人居然用浏览器把电脑关机了_哔哩哔哩_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
- 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文档读一遍就基本没问题了
拜！
5907
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
