1. 先说清楚 Neutralinojs 到底是个什么东西刚看到 Neutralinojs 这个词时我第一反应是“又一个 Electron 套壳框架”。但真正试用完之后我得说这个判断不对。Neutralinojs 的核心思路和 Electron 完全相反Electron 是把整个 Chromium 浏览器塞进你的应用包所以一个 Hello World 的体积轻松突破 150MB而 Neutralinojs 完全不捆绑浏览器它直接调用操作系统自带的 WebView 渲染引擎Windows 上是 WebView2macOS 上是 WKWebViewLinux 上是 WebKitGTK后端只需要一个很小的原生二进制程序来托管静态资源和提供系统 API。打个比方Electron 像是一辆自带厨房的豪华餐车走哪都能做饭但车本身又重又大Neutralinojs 是只带食材去共享厨房系统内置的 WebView 就是那个共享厨房所以最终产物只有几兆。另一个常被拿来对比的是 Tauri但 Tauri 在 Windows 上也需要依赖 WebView2而且它的 Rust 工具链对入门者来说门槛更高。如果你的技术栈是纯 JavaScript/HTML/CSS想快速做出一个轻量桌面工具Neutralinojs 的上手成本是最低的。这篇文章要解决的问题很具体在国内网络环境下怎么把它从零搭起来、正常跑起来、最后打包成可发布的产物。我会把每个环节可能遇到的坑都写清楚尤其是二进制文件下载失败、镜像配置、跨平台打包这几个点网上资料很少但几乎所有人都会踩。2. 先用两分钟弄清它的运行原理再决定要不要入坑2.1 双进程模型原生后端 WebView 前端Neutralinojs 的应用本质上由两部分组成。第一部分是那个原生二进制程序你可以理解为一个迷你的 Web 服务器加原生能力调度器它负责读取配置、托管静态文件、执行前端请求的系统级操作比如弹出窗口、读取文件列表、获取系统信息。第二部分是 WebView 中加载的网页也就是你的前端界面它通过官方提供的一个 JavaScript 库neutralino.js向原生后端发起调用。这两部分之间通过 WebSocket 通信。前端代码很像写普通网页但在 window 对象上会多出一个Neutralino全局对象你调用的Neutralino.window.setTitle()、Neutralino.os.showOpenDialog()这些 API最终都会被打包成一条消息发给后端进程由后端去真正调用操作系统能力。理解了这一点你就能明白为什么 Neutralinojs 的体积这么小——系统能力不是由框架预先塞进去的而是按需通过这个轻量通信管道临时调用的。2.2 和 Electron、Tauri 放到一起对比很多人选型时会在这三个框架之间纠结我整理了一张表直接看差异维度NeutralinojsElectronTauri打包体积Hello World2~5MB150MB 左右3~10MB是否内置浏览器否用系统 WebView是捆绑 Chromium否用系统 WebView后端语言JavaScriptNode.jsNode.jsRust低版本 Windows 兼容性良好良好需额外处理 WebView2生态成熟度较小还在发展最成熟快速发展中入门门槛低中中高Rust 编译链在对比里你会发现Electron 的优势是生态和稳定性Tauri 的优势是安全性和性能而 Neutralinojs 的最大优势是“简单”。它没有复杂的构建体系配置就是一个 JSON 文件没有编译步骤连打包都只是一条命令。如果你只是给团队做个内部工具、个人效率小软件、教学演示程序或者想在 Web 技术上快速验证桌面端想法Neutralinojs 是非常合适的选择。但如果你要做大型商业级应用需要复杂的系统集成或庞大的第三方库生态那还是老老实实选 Electron。2.3 哪些项目适合用它哪些不适合根据我的实际使用体验适合的场景大概有三类。第一类是内部工具比如运维面板、脱水版数据库客户端、日志查看器第二类是“网页套壳但比纯浏览器好用”的工具比如给某个线上系统做一个独立的桌面图标入口第三类是教学和演示让学生用熟悉的前端技术快速体验桌面应用开发。不太适合的场景是涉及大量文件系统读写、复杂原生交互、视频处理等重逻辑的应用。不是说做不到而是要写很多自定义扩展代码性价比就低了。另外如果目标用户中有大量老旧的 Windows 7/8 系统也要注意 WebView 兼容性问题。3. 国内环境搭建实操从镜像配置到跑通第一个窗口3.1 环境准备Node.js 和 npm 镜像Neutralinojs 的 CLI 和脚手架都依赖 Node.js建议安装 16 或更高的 LTS 版本这个没什么争议。真正要提醒的是国内网络环境下npm 官方源经常让大家卡在依赖安装那一步所以第一步先检查并切换镜像源。# 查看当前 npm 镜像地址 npm config get registry # 如果输出的是 https://registry.npmjs.org/建议切换到国内镜像 npm config set registry https://registry.npmmirror.com这一步非常关键因为后续脚手架创建项目、安装 CLI 依赖都走 npm。切换镜像后下载速度会有肉眼可见的提升。如果你在公司内网环境也可以用公司自建的 npm 私服原理一样。3.2 用官方脚手架创建项目Neutralinojs 官方推荐用脚手架直接生成项目模板命令为npm create neutralinojslatest myapp执行后CLI 会让你选一套模板。新手选默认的 JavaScript 模板就行TypeScript 模板也可以只是多做一步编译配置。创建完成后进入项目目录cd myapp项目里会有一个 package.json如果有neu相关的依赖先执行npm install把命令行工具装好。之后检查一下neu命令是否可用npx neu --version如果能输出版本号说明 CLI 环境正常可以进入下一步。3.3 最容易卡住的点二进制文件下载失败这是国内环境搭建时最大的坑。脚手架创建完项目后会默认调用neu update去 GitHub Releases 下载对应平台的 Neutralinojs 运行时二进制文件并存放到项目的.bin目录。但很多人在这一步会遇到超时、报错或者干脆卡住不动。遇到这种情况首先检查.bin目录里有没有生成对应的二进制文件。比如在 Windows 上应该有neutralino-win_x64.exeLinux 上应该有neutralino-linux_x64。如果没有那就需要手动处理。最稳妥的办法是直接本机浏览器打开 GitHub Releases 页面手动下载与你当前平台匹配的二进制文件。文件命名规则大概是下面这样平台文件名Windows x64neutralino-win_x64.exemacOS Intelneutralino-mac_x64macOS Apple Siliconneutralino-mac_arm64Linux x64neutralino-linux_x64Linux ARM64neutralino-linux_arm64下载好之后把它放到项目的.bin目录下并保持文件名与列表中的一致。然后再次运行npx neu update如果 CLI 检测到本地已经有匹配的二进制且版本正确就会跳过下载直接完成更新。这一步国内环境几乎必踩提前知道处理方式能省很多时间。3.4 跑通第一个窗口neu run二进制备好后运行开发模式非常简单npx neu run默认配置下它会以一个原生窗口的形式打开你的应用窗口里加载的就是resources目录下的页面。如果你希望先在浏览器里调试可以把neutralino.config.json里的mode改为browser这样neu run会在默认浏览器里打开应用地址调试工具也更方便。开发模式下改动前端文件页面会自动刷新这一点和网页开发体验很接近。看到那个空白窗口里出现默认页面时整个搭建流程就算真正跑通了。4. 开发调试的核心机制配置、端口和权限白名单4.1 neu run 背后做了什么neu run看起来只是启动了一个窗口实际上它后台做了三件事启动一个本地 WebSocket 服务用于前后端通信在指定端口启动静态资源服务把resources目录暴露出来监听resources目录下的文件变化并向前端发送刷新消息。理解这个机制后很多运行期问题都能定位。比如你改了neutralino.config.json里的端口号却发现没生效原因就是配置文件不会热加载必须终止进程后重新neu run。再比如你在resources目录外新建了文件页面不会自动刷新因为监听范围就在这个目录内。4.2 neutralino.config.json 的关键字段这个文件是整个项目的中枢值得花时间逐字段理解。我把最常用的字段列出来配置字段作用applicationId应用唯一标识跨平台安装和配置读写依赖它modewindow / browser / cloud决定运行形式port开发服务器的端口默认 8080冲突时手动改url入口页面路径一般指向 /resources/nativeAllowList允许前端调用的原生 API 模块白名单globalVariables需要注入到前端的全局变量cli.binaryName运行时二进制的名称也会成为打包后的可执行文件名cli.binaryVersion锁定运行时二进制版本升级时改这里cli.resourcesPath打包时要压缩进 resources.neu 的目录cli.extensionsPath扩展进程的存放目录port字段可能是开发时第一个要动的配置。如果你本机 8080 端口被其他服务占用neu run会报端口冲突这时候直接修改port: 8080为其他值即可。前端页面里如果有写死的接口地址记得同步修改。4.3 nativeAllowList 白名单不是摆设很多新手初学时图省事直接把nativeAllowList配成通配符什么模块都放行。这个习惯很危险。nativeAllowList的语义是前端页面可以调用哪些原生能力模块。如果你引入了不受信任的前端依赖比如某个第三方 JS 库它理论上也能通过这些 API 读取文件、执行命令。正确做法是最小权限原则只用哪些就放开哪些。默认模板一般会给出nativeAllowList: [app, os, window, computer, debug]之类的集合。如果你用不到os模块就把它从白名单里删掉。后面引入自定义扩展时同样要控制扩展之间的数据流。4.4 开发期离不开的调试技巧开发工具方面Neutralinojs 没有 Electron 那种可以直接 CtrlShiftI 打开的官方调试器但有个替代方案在窗口创建时调用Neutralino.debug.log()日志会输出到终端或者干脆把mode切到browser用浏览器 F12 调试页面前端逻辑。一个比较顺手的流程是平时用mode: browser调前端样式和交互功能稳定后再切回mode: window验证原生窗口表现。切换时注意本地存储、窗口尺寸这些状态不同运行模式下行为会有差异。5. 打包发布全流程与跨平台产物的正确姿势5.1 neu build 到底做了什么打包命令只有一条npx neu build但这背后也有讲究。CLI 会做两件关键的事第一把cli.resourcesPath指向的目录整体压缩成一个resources.neu文件这个文件本质上是一个特殊命名的 zip 包里面装着你所有的前端页面和静态资源第二把当前平台的运行时二进制复制到dist目录下并按照cli.binaryName重命名。最终产物结构大致如下dist/ └── myapp/ ├── myapp.exe # Windows 可执行文件 └── resources.neu # 前端资源包应用启动时二进制程序会读取同目录下的resources.neu解压到临时目录并加载入口页面。所以分发部署时这两个文件必须放在一起缺一不可。把资源整体打包成单文件还有一个好处你的前端代码不是以明文散落的虽然仍可被解包分析但至少避免了随手翻目录就能看到源码的情况。5.2 打包时再遇二进制下载问题的处理思路neu build在执行过程中如果检测到.bin目录里的二进制版本与cli.binaryVersion不一致会尝试从 GitHub 重新下载。这一步在国内网络环境同样可能失败。我的处理习惯是在开发环境跑通后先确认.bin里已经放好了对应平台的二进制并且版本和cli.binaryVersion一致然后再执行neu build。如果打包时仍然尝试下载检查两个地方neutralino.config.json中cli.binaryVersion填写的版本号是否正确.bin目录下的二进制文件名是否与平台匹配。还有一个实用技巧把下载好的二进制文件留在项目里并提交到内部版本管理仓库如果你用的是私有仓库团队其他成员 clone 项目后就不需要再去 GitHub 重新下载了。这在多人协作时能节省大量时间。5.3 跨平台打包不要幻想一条命令通吃Neutralinojs 有一个限制它不会像 Electron 那样支持你在 Windows 上直接打出 macOS 的安装包。因为运行时二进制依赖特定操作系统和架构而且resources.neu虽然与平台无关但没有对应平台的二进制就没法运行。实现跨平台分发主流做法有两种。第一种最直接在哪个平台发布就在哪个平台执行neu build。Windows 发布走 Windows 机器macOS 发布在 macOS 机器上打包。第二种是手动组合产物在一个平台构建出resources.neu然后在对应的目标平台上手动下载对应二进制放在同一目录下改名即可。前者适合有 CI 条件或本机刚好有多个系统的场景后者适合临时应急。5.4 一个容易吓到新手的提示未签名警告打包好的 Windows exe 在分发时经常遇到 SmartScreen 拦截提示“Windows protected your PC”。这完全正常因为应用没有代码签名证书。“更多信息 - 仍要运行”就能绕过去但正式面向外部用户发布时建议购买证书对二进制做签名。这一步不是框架层面的问题是所有桌面应用都要面对的分发现实。至此从开发到出包的完整链路已经走通。如果只是做简单工具你已经可以停在这里了。但如果你想进一步压榨 Neutralinojs 的能力接入自己的后端逻辑就绕不开自定义扩展。6. 用自定义扩展突破官方 API 的天花板6.1 为什么需要自定义扩展官方提供的 API 覆盖了窗口管理、系统信息、文件对话框这些常用操作但你迟早会遇到它没有覆盖的能力。比如我需要读取应用目录下某个 JSON 配置文件并解析成菜单数据官方 API 里没有直接暴露读取任意文件的方法出于安全考虑也不会暴露。这时候就需要自定义扩展。Neutralinojs 的自定义扩展机制本质上是通过一个独立子进程来跑你的 Node.js 逻辑这个子进程与主进程通过 stdin/stdout 交换 JSON 格式的消息。前端通过Neutralino.extensions.dispatch()把事件发给扩展扩展处理完后再把结果送回前端。理解成“用 Node.js 写一个与页面异步通信的本地服务”就很形象。6.2 一个读取配置文件的扩展实战下面我以“读取应用同目录下的 settings.json”为例走一遍完整流程。先创建扩展目录和脚本mkdir -p extensions touch extensions/read-config.jsread-config.js的内容如下const readline require(readline); const fs require(fs); const rl readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false }); rl.on(line, (line) { const msg JSON.parse(line); // 主进程启动扩展时会传入初始参数先不做业务处理 if (msg.event processArgs) { return; } if (msg.event readConfig) { try { const content fs.readFileSync(msg.data.path, utf8); console.log(JSON.stringify({ id: msg.id, event: readConfig, data: content })); } catch (e) { console.log(JSON.stringify({ id: msg.id, event: readConfig, error: String(e) })); } } });然后在neutralino.config.json中注册扩展extensions: [ { id: js.read-config, command: node extensions/read-config.js, stdio: [ stdin, stdout ] } ]前端页面里这样调用Neutralino.extensions.dispatch(js.read-config, readConfig, { path: ./settings.json });注意这里的path默认是相对于扩展进程当前工作目录的实际项目中要处理好相对路径和绝对路径的换算。收到事件后前端通过Neutralino.events.on(extensions, ...)监听扩展发来的消息。这个例子虽然短但它涵盖了自定义扩展的全部核心知识点子进程启动、JSON 消息协议、事件名映射、异步回传。你完全可以在这个基础上扩展出数据库访问、调用本机命令行工具等功能。6.3 扩展开发的安全底线扩展进程的能力比页面大得多因为它本质上是 Node.js 环境能读文件、能执行命令。所以扩展的输入参数必须严格校验。比如上面那个读取配置的例子至少要做两件事校验传入路径确实在允许的目录范围内确认文件类型是 JSON 而不是其他格式。不要因为前端是自己写的就放松校验在桌面应用里XSS 漏洞同样可能成为攻击入口。另一个容易忽略的点扩展进程失效时neu run和打包后的应用行为不完全相同。开发模式如果扩展挂了你通常能在终端看到报错但打包后扩展异常可能只是静默失败。所以上线前一定要在打包产物里完整测一遍所有扩展功能。7. 一份经过实战检验的踩坑清单和提效玩法7.1 高频问题速查表现象原因解决办法neu run报端口冲突8080 被其他进程占用修改 config 中的 port窗口打开后白屏url 配置指向错误或资源未加载检查 url 是否为 /resources/修改 config 不生效配置文件不参与热更新重启neu runWindows 双击程序后无响应杀毒软件/防火墙拦截未签名程序添加信任目录或申请签名Windows 精简系统白屏缺少 WebView2 Runtime安装 Microsoft Edge WebView2 RuntimeLinux 下窗口白屏系统缺少 WebKitGTK 运行库安装对应包的运行库前端调 API 被拒绝nativeAllowList 未开放对应模块按需添加模块白名单打包时卡在下载阶段需要从 GitHub 获取二进制手动下载并放入 .binarch 不匹配在 64 位设备打包给 32 位机器用x64/arm64 分别构建其中 Linux 白屏那个问题外网文档提得比较多国内搜到的资料反而少。如果你的 Linux 测试环境白屏第一反应别去查代码先确认系统装没装 WebKitGTK。Ubuntu 系的包名通常是 libwebkit2gtk-4.0 或 4.1 系列装上运行库再试绝大多数情况能解决。7.2 常用命令速查npm create neutralinojslatest myapp创建新项目npm install安装项目依赖neu update更新运行时二进制文件neu run启动开发模式neu build打包发布产物neu --version查看 CLI 版本7.3 前端工程化Vite/Vue/React 怎么接入团队里用 Vue 或 React 的人往往会问能不能继续用组件化开发。答案是可以但要处理两个点。第一利用前端构建工具把页面打包成纯静态资源然后把这些静态资源全部放进resources目录。第二确保资源路径是相对路径而不是绝对路径。以 Vite 为例你需要在vite.config.js里设置base: ./这样构建产物的 js、css 引用都是相对路径Neutralinojs 通过file://协议加载时不会因为路径问题而白屏。开发阶段体验很直接先用 Vite 的热更新调 UI最后构建一次把产物同步到 resources 目录再切回 Neutralinojs 验证原生窗口行为。我个人的习惯是写一个 npm script 把 Vite 的 build 输出自动同步到 resources 目录比如sync: vite build rm -rf resources/* cp -r dist/* resources/这样每次发布都是一条命令完成。7.4 版本锁定的个人经验最后补充一个很多人吃过亏的点cli.binaryVersion这个版本号最好手动固定不要随便升级。Neutralinojs 处于快速迭代期不同版本之间配置字段可能有微调。项目一旦跑通把cli.binaryVersion锁住升级时单独验证后再改。否则你某天执行neu update后可能只是升级了个二进制版本页面就出现莫名的兼容问题。同样的版本谨慎态度也适用于neutralino.js客户端库。它需要和二进制版本匹配才能正常通信模板脚手架一般会处理好两者的一致性你自己单独更新的时候要留意版本对应关系。我自己的经验是先跑通最小 demo再上 Vite 工程化最后才考虑加扩展。三步走下来踩坑最少。如果你也是从 Electron 转过来的刚开始看到那个几兆的打包体积确实会有点不习惯——但这就是轻量框架该有的样子。
Neutralinojs 国内环境搭建与跨平台打包实战指南
1. 先说清楚 Neutralinojs 到底是个什么东西刚看到 Neutralinojs 这个词时我第一反应是“又一个 Electron 套壳框架”。但真正试用完之后我得说这个判断不对。Neutralinojs 的核心思路和 Electron 完全相反Electron 是把整个 Chromium 浏览器塞进你的应用包所以一个 Hello World 的体积轻松突破 150MB而 Neutralinojs 完全不捆绑浏览器它直接调用操作系统自带的 WebView 渲染引擎Windows 上是 WebView2macOS 上是 WKWebViewLinux 上是 WebKitGTK后端只需要一个很小的原生二进制程序来托管静态资源和提供系统 API。打个比方Electron 像是一辆自带厨房的豪华餐车走哪都能做饭但车本身又重又大Neutralinojs 是只带食材去共享厨房系统内置的 WebView 就是那个共享厨房所以最终产物只有几兆。另一个常被拿来对比的是 Tauri但 Tauri 在 Windows 上也需要依赖 WebView2而且它的 Rust 工具链对入门者来说门槛更高。如果你的技术栈是纯 JavaScript/HTML/CSS想快速做出一个轻量桌面工具Neutralinojs 的上手成本是最低的。这篇文章要解决的问题很具体在国内网络环境下怎么把它从零搭起来、正常跑起来、最后打包成可发布的产物。我会把每个环节可能遇到的坑都写清楚尤其是二进制文件下载失败、镜像配置、跨平台打包这几个点网上资料很少但几乎所有人都会踩。2. 先用两分钟弄清它的运行原理再决定要不要入坑2.1 双进程模型原生后端 WebView 前端Neutralinojs 的应用本质上由两部分组成。第一部分是那个原生二进制程序你可以理解为一个迷你的 Web 服务器加原生能力调度器它负责读取配置、托管静态文件、执行前端请求的系统级操作比如弹出窗口、读取文件列表、获取系统信息。第二部分是 WebView 中加载的网页也就是你的前端界面它通过官方提供的一个 JavaScript 库neutralino.js向原生后端发起调用。这两部分之间通过 WebSocket 通信。前端代码很像写普通网页但在 window 对象上会多出一个Neutralino全局对象你调用的Neutralino.window.setTitle()、Neutralino.os.showOpenDialog()这些 API最终都会被打包成一条消息发给后端进程由后端去真正调用操作系统能力。理解了这一点你就能明白为什么 Neutralinojs 的体积这么小——系统能力不是由框架预先塞进去的而是按需通过这个轻量通信管道临时调用的。2.2 和 Electron、Tauri 放到一起对比很多人选型时会在这三个框架之间纠结我整理了一张表直接看差异维度NeutralinojsElectronTauri打包体积Hello World2~5MB150MB 左右3~10MB是否内置浏览器否用系统 WebView是捆绑 Chromium否用系统 WebView后端语言JavaScriptNode.jsNode.jsRust低版本 Windows 兼容性良好良好需额外处理 WebView2生态成熟度较小还在发展最成熟快速发展中入门门槛低中中高Rust 编译链在对比里你会发现Electron 的优势是生态和稳定性Tauri 的优势是安全性和性能而 Neutralinojs 的最大优势是“简单”。它没有复杂的构建体系配置就是一个 JSON 文件没有编译步骤连打包都只是一条命令。如果你只是给团队做个内部工具、个人效率小软件、教学演示程序或者想在 Web 技术上快速验证桌面端想法Neutralinojs 是非常合适的选择。但如果你要做大型商业级应用需要复杂的系统集成或庞大的第三方库生态那还是老老实实选 Electron。2.3 哪些项目适合用它哪些不适合根据我的实际使用体验适合的场景大概有三类。第一类是内部工具比如运维面板、脱水版数据库客户端、日志查看器第二类是“网页套壳但比纯浏览器好用”的工具比如给某个线上系统做一个独立的桌面图标入口第三类是教学和演示让学生用熟悉的前端技术快速体验桌面应用开发。不太适合的场景是涉及大量文件系统读写、复杂原生交互、视频处理等重逻辑的应用。不是说做不到而是要写很多自定义扩展代码性价比就低了。另外如果目标用户中有大量老旧的 Windows 7/8 系统也要注意 WebView 兼容性问题。3. 国内环境搭建实操从镜像配置到跑通第一个窗口3.1 环境准备Node.js 和 npm 镜像Neutralinojs 的 CLI 和脚手架都依赖 Node.js建议安装 16 或更高的 LTS 版本这个没什么争议。真正要提醒的是国内网络环境下npm 官方源经常让大家卡在依赖安装那一步所以第一步先检查并切换镜像源。# 查看当前 npm 镜像地址 npm config get registry # 如果输出的是 https://registry.npmjs.org/建议切换到国内镜像 npm config set registry https://registry.npmmirror.com这一步非常关键因为后续脚手架创建项目、安装 CLI 依赖都走 npm。切换镜像后下载速度会有肉眼可见的提升。如果你在公司内网环境也可以用公司自建的 npm 私服原理一样。3.2 用官方脚手架创建项目Neutralinojs 官方推荐用脚手架直接生成项目模板命令为npm create neutralinojslatest myapp执行后CLI 会让你选一套模板。新手选默认的 JavaScript 模板就行TypeScript 模板也可以只是多做一步编译配置。创建完成后进入项目目录cd myapp项目里会有一个 package.json如果有neu相关的依赖先执行npm install把命令行工具装好。之后检查一下neu命令是否可用npx neu --version如果能输出版本号说明 CLI 环境正常可以进入下一步。3.3 最容易卡住的点二进制文件下载失败这是国内环境搭建时最大的坑。脚手架创建完项目后会默认调用neu update去 GitHub Releases 下载对应平台的 Neutralinojs 运行时二进制文件并存放到项目的.bin目录。但很多人在这一步会遇到超时、报错或者干脆卡住不动。遇到这种情况首先检查.bin目录里有没有生成对应的二进制文件。比如在 Windows 上应该有neutralino-win_x64.exeLinux 上应该有neutralino-linux_x64。如果没有那就需要手动处理。最稳妥的办法是直接本机浏览器打开 GitHub Releases 页面手动下载与你当前平台匹配的二进制文件。文件命名规则大概是下面这样平台文件名Windows x64neutralino-win_x64.exemacOS Intelneutralino-mac_x64macOS Apple Siliconneutralino-mac_arm64Linux x64neutralino-linux_x64Linux ARM64neutralino-linux_arm64下载好之后把它放到项目的.bin目录下并保持文件名与列表中的一致。然后再次运行npx neu update如果 CLI 检测到本地已经有匹配的二进制且版本正确就会跳过下载直接完成更新。这一步国内环境几乎必踩提前知道处理方式能省很多时间。3.4 跑通第一个窗口neu run二进制备好后运行开发模式非常简单npx neu run默认配置下它会以一个原生窗口的形式打开你的应用窗口里加载的就是resources目录下的页面。如果你希望先在浏览器里调试可以把neutralino.config.json里的mode改为browser这样neu run会在默认浏览器里打开应用地址调试工具也更方便。开发模式下改动前端文件页面会自动刷新这一点和网页开发体验很接近。看到那个空白窗口里出现默认页面时整个搭建流程就算真正跑通了。4. 开发调试的核心机制配置、端口和权限白名单4.1 neu run 背后做了什么neu run看起来只是启动了一个窗口实际上它后台做了三件事启动一个本地 WebSocket 服务用于前后端通信在指定端口启动静态资源服务把resources目录暴露出来监听resources目录下的文件变化并向前端发送刷新消息。理解这个机制后很多运行期问题都能定位。比如你改了neutralino.config.json里的端口号却发现没生效原因就是配置文件不会热加载必须终止进程后重新neu run。再比如你在resources目录外新建了文件页面不会自动刷新因为监听范围就在这个目录内。4.2 neutralino.config.json 的关键字段这个文件是整个项目的中枢值得花时间逐字段理解。我把最常用的字段列出来配置字段作用applicationId应用唯一标识跨平台安装和配置读写依赖它modewindow / browser / cloud决定运行形式port开发服务器的端口默认 8080冲突时手动改url入口页面路径一般指向 /resources/nativeAllowList允许前端调用的原生 API 模块白名单globalVariables需要注入到前端的全局变量cli.binaryName运行时二进制的名称也会成为打包后的可执行文件名cli.binaryVersion锁定运行时二进制版本升级时改这里cli.resourcesPath打包时要压缩进 resources.neu 的目录cli.extensionsPath扩展进程的存放目录port字段可能是开发时第一个要动的配置。如果你本机 8080 端口被其他服务占用neu run会报端口冲突这时候直接修改port: 8080为其他值即可。前端页面里如果有写死的接口地址记得同步修改。4.3 nativeAllowList 白名单不是摆设很多新手初学时图省事直接把nativeAllowList配成通配符什么模块都放行。这个习惯很危险。nativeAllowList的语义是前端页面可以调用哪些原生能力模块。如果你引入了不受信任的前端依赖比如某个第三方 JS 库它理论上也能通过这些 API 读取文件、执行命令。正确做法是最小权限原则只用哪些就放开哪些。默认模板一般会给出nativeAllowList: [app, os, window, computer, debug]之类的集合。如果你用不到os模块就把它从白名单里删掉。后面引入自定义扩展时同样要控制扩展之间的数据流。4.4 开发期离不开的调试技巧开发工具方面Neutralinojs 没有 Electron 那种可以直接 CtrlShiftI 打开的官方调试器但有个替代方案在窗口创建时调用Neutralino.debug.log()日志会输出到终端或者干脆把mode切到browser用浏览器 F12 调试页面前端逻辑。一个比较顺手的流程是平时用mode: browser调前端样式和交互功能稳定后再切回mode: window验证原生窗口表现。切换时注意本地存储、窗口尺寸这些状态不同运行模式下行为会有差异。5. 打包发布全流程与跨平台产物的正确姿势5.1 neu build 到底做了什么打包命令只有一条npx neu build但这背后也有讲究。CLI 会做两件关键的事第一把cli.resourcesPath指向的目录整体压缩成一个resources.neu文件这个文件本质上是一个特殊命名的 zip 包里面装着你所有的前端页面和静态资源第二把当前平台的运行时二进制复制到dist目录下并按照cli.binaryName重命名。最终产物结构大致如下dist/ └── myapp/ ├── myapp.exe # Windows 可执行文件 └── resources.neu # 前端资源包应用启动时二进制程序会读取同目录下的resources.neu解压到临时目录并加载入口页面。所以分发部署时这两个文件必须放在一起缺一不可。把资源整体打包成单文件还有一个好处你的前端代码不是以明文散落的虽然仍可被解包分析但至少避免了随手翻目录就能看到源码的情况。5.2 打包时再遇二进制下载问题的处理思路neu build在执行过程中如果检测到.bin目录里的二进制版本与cli.binaryVersion不一致会尝试从 GitHub 重新下载。这一步在国内网络环境同样可能失败。我的处理习惯是在开发环境跑通后先确认.bin里已经放好了对应平台的二进制并且版本和cli.binaryVersion一致然后再执行neu build。如果打包时仍然尝试下载检查两个地方neutralino.config.json中cli.binaryVersion填写的版本号是否正确.bin目录下的二进制文件名是否与平台匹配。还有一个实用技巧把下载好的二进制文件留在项目里并提交到内部版本管理仓库如果你用的是私有仓库团队其他成员 clone 项目后就不需要再去 GitHub 重新下载了。这在多人协作时能节省大量时间。5.3 跨平台打包不要幻想一条命令通吃Neutralinojs 有一个限制它不会像 Electron 那样支持你在 Windows 上直接打出 macOS 的安装包。因为运行时二进制依赖特定操作系统和架构而且resources.neu虽然与平台无关但没有对应平台的二进制就没法运行。实现跨平台分发主流做法有两种。第一种最直接在哪个平台发布就在哪个平台执行neu build。Windows 发布走 Windows 机器macOS 发布在 macOS 机器上打包。第二种是手动组合产物在一个平台构建出resources.neu然后在对应的目标平台上手动下载对应二进制放在同一目录下改名即可。前者适合有 CI 条件或本机刚好有多个系统的场景后者适合临时应急。5.4 一个容易吓到新手的提示未签名警告打包好的 Windows exe 在分发时经常遇到 SmartScreen 拦截提示“Windows protected your PC”。这完全正常因为应用没有代码签名证书。“更多信息 - 仍要运行”就能绕过去但正式面向外部用户发布时建议购买证书对二进制做签名。这一步不是框架层面的问题是所有桌面应用都要面对的分发现实。至此从开发到出包的完整链路已经走通。如果只是做简单工具你已经可以停在这里了。但如果你想进一步压榨 Neutralinojs 的能力接入自己的后端逻辑就绕不开自定义扩展。6. 用自定义扩展突破官方 API 的天花板6.1 为什么需要自定义扩展官方提供的 API 覆盖了窗口管理、系统信息、文件对话框这些常用操作但你迟早会遇到它没有覆盖的能力。比如我需要读取应用目录下某个 JSON 配置文件并解析成菜单数据官方 API 里没有直接暴露读取任意文件的方法出于安全考虑也不会暴露。这时候就需要自定义扩展。Neutralinojs 的自定义扩展机制本质上是通过一个独立子进程来跑你的 Node.js 逻辑这个子进程与主进程通过 stdin/stdout 交换 JSON 格式的消息。前端通过Neutralino.extensions.dispatch()把事件发给扩展扩展处理完后再把结果送回前端。理解成“用 Node.js 写一个与页面异步通信的本地服务”就很形象。6.2 一个读取配置文件的扩展实战下面我以“读取应用同目录下的 settings.json”为例走一遍完整流程。先创建扩展目录和脚本mkdir -p extensions touch extensions/read-config.jsread-config.js的内容如下const readline require(readline); const fs require(fs); const rl readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false }); rl.on(line, (line) { const msg JSON.parse(line); // 主进程启动扩展时会传入初始参数先不做业务处理 if (msg.event processArgs) { return; } if (msg.event readConfig) { try { const content fs.readFileSync(msg.data.path, utf8); console.log(JSON.stringify({ id: msg.id, event: readConfig, data: content })); } catch (e) { console.log(JSON.stringify({ id: msg.id, event: readConfig, error: String(e) })); } } });然后在neutralino.config.json中注册扩展extensions: [ { id: js.read-config, command: node extensions/read-config.js, stdio: [ stdin, stdout ] } ]前端页面里这样调用Neutralino.extensions.dispatch(js.read-config, readConfig, { path: ./settings.json });注意这里的path默认是相对于扩展进程当前工作目录的实际项目中要处理好相对路径和绝对路径的换算。收到事件后前端通过Neutralino.events.on(extensions, ...)监听扩展发来的消息。这个例子虽然短但它涵盖了自定义扩展的全部核心知识点子进程启动、JSON 消息协议、事件名映射、异步回传。你完全可以在这个基础上扩展出数据库访问、调用本机命令行工具等功能。6.3 扩展开发的安全底线扩展进程的能力比页面大得多因为它本质上是 Node.js 环境能读文件、能执行命令。所以扩展的输入参数必须严格校验。比如上面那个读取配置的例子至少要做两件事校验传入路径确实在允许的目录范围内确认文件类型是 JSON 而不是其他格式。不要因为前端是自己写的就放松校验在桌面应用里XSS 漏洞同样可能成为攻击入口。另一个容易忽略的点扩展进程失效时neu run和打包后的应用行为不完全相同。开发模式如果扩展挂了你通常能在终端看到报错但打包后扩展异常可能只是静默失败。所以上线前一定要在打包产物里完整测一遍所有扩展功能。7. 一份经过实战检验的踩坑清单和提效玩法7.1 高频问题速查表现象原因解决办法neu run报端口冲突8080 被其他进程占用修改 config 中的 port窗口打开后白屏url 配置指向错误或资源未加载检查 url 是否为 /resources/修改 config 不生效配置文件不参与热更新重启neu runWindows 双击程序后无响应杀毒软件/防火墙拦截未签名程序添加信任目录或申请签名Windows 精简系统白屏缺少 WebView2 Runtime安装 Microsoft Edge WebView2 RuntimeLinux 下窗口白屏系统缺少 WebKitGTK 运行库安装对应包的运行库前端调 API 被拒绝nativeAllowList 未开放对应模块按需添加模块白名单打包时卡在下载阶段需要从 GitHub 获取二进制手动下载并放入 .binarch 不匹配在 64 位设备打包给 32 位机器用x64/arm64 分别构建其中 Linux 白屏那个问题外网文档提得比较多国内搜到的资料反而少。如果你的 Linux 测试环境白屏第一反应别去查代码先确认系统装没装 WebKitGTK。Ubuntu 系的包名通常是 libwebkit2gtk-4.0 或 4.1 系列装上运行库再试绝大多数情况能解决。7.2 常用命令速查npm create neutralinojslatest myapp创建新项目npm install安装项目依赖neu update更新运行时二进制文件neu run启动开发模式neu build打包发布产物neu --version查看 CLI 版本7.3 前端工程化Vite/Vue/React 怎么接入团队里用 Vue 或 React 的人往往会问能不能继续用组件化开发。答案是可以但要处理两个点。第一利用前端构建工具把页面打包成纯静态资源然后把这些静态资源全部放进resources目录。第二确保资源路径是相对路径而不是绝对路径。以 Vite 为例你需要在vite.config.js里设置base: ./这样构建产物的 js、css 引用都是相对路径Neutralinojs 通过file://协议加载时不会因为路径问题而白屏。开发阶段体验很直接先用 Vite 的热更新调 UI最后构建一次把产物同步到 resources 目录再切回 Neutralinojs 验证原生窗口行为。我个人的习惯是写一个 npm script 把 Vite 的 build 输出自动同步到 resources 目录比如sync: vite build rm -rf resources/* cp -r dist/* resources/这样每次发布都是一条命令完成。7.4 版本锁定的个人经验最后补充一个很多人吃过亏的点cli.binaryVersion这个版本号最好手动固定不要随便升级。Neutralinojs 处于快速迭代期不同版本之间配置字段可能有微调。项目一旦跑通把cli.binaryVersion锁住升级时单独验证后再改。否则你某天执行neu update后可能只是升级了个二进制版本页面就出现莫名的兼容问题。同样的版本谨慎态度也适用于neutralino.js客户端库。它需要和二进制版本匹配才能正常通信模板脚手架一般会处理好两者的一致性你自己单独更新的时候要留意版本对应关系。我自己的经验是先跑通最小 demo再上 Vite 工程化最后才考虑加扩展。三步走下来踩坑最少。如果你也是从 Electron 转过来的刚开始看到那个几兆的打包体积确实会有点不习惯——但这就是轻量框架该有的样子。
