做桌面小工具的这几年我在 Electron 和 Tauri 之间来回折腾过不少次Electron 打包出来动不动一百多 MB给同事分发内部小工具的时候特别痛苦。后来在一个临时需求里接触到了 Neutralinojs这个号称客户端二进制只有 2MB 的轻量桌面框架思路跟 Electron 完全不一样却足够支撑大多数内部工具和个人小工具。这篇文章我就把它的搭建、日常运行和打包流程完整过一遍重点聊聊国内环境下那些文档里不会写、但实操一定会撞上的坑。适合正在选型轻量桌面方案、或者已经被 Electron 体积烦到的同学参考。1. Neutralinojs 的定位为什么它能做到 2MB1.1 它到底是怎么工作的先搞清楚 Neutralinojs 和 Electron 的本质区别。Electron 是把一个完整的 Chromium 浏览器打包进应用所以你写一遍 Web 前端它帮你跑在浏览器引擎里代价是一个安装包动辄 80MB 起步内存占用常年几百 MB。Neutralinojs 的思路是反过来的它不打包浏览器而是调用操作系统自带的 WebView 组件来渲染界面。Windows 上用 WebView2 或 EdgeHTMLLinux 上用 WebKitGTKmacOS 上用 WKWebView这些组件系统里本来就有Neutralinojs 只需要提供一个很薄的客户端把原生能力和 Web 前端桥接起来就行。这个客户端二进制本身也就是 1.5MB 到 2.5MB 左右加上你的 HTML/CSS/JS 资源一个完整应用打包出来通常不超过 5MB。而且因为 WebView 是系统组件内存占用也比 Chromium 低得多。代价是不同操作系统上的 WebView 渲染能力有差异遇到比较新的 CSS 特性老版本系统上可能表现不一致。1.2 它和 Electron、Tauri 的直观对比很多人会拿它和 Tauri 比Tauri 也是轻量方案但 Tauri 的依赖链路长后端要 Rust 工具链前端构建体系也复杂一些。Neutralinojs 则几乎没有后端语言门槛前端写好了就能跑而且国内不管做偏门平台适配还是快速打包整个过程都很直接。对比维度ElectronTauriNeutralinojs安装包体积80MB 起3MB 左右2MB 左右后端语言Node.jsRust无原生客户端前端技术Web 技术Web 技术Web 技术内存占用高低低学习曲线低中高很低维护活跃度极高高中等1.3 什么场景我建议用 Neutralinojs我个人总结下来它最合适的场景是这些公司内部工具数据查看、日志分析、内部 API 调试面板装起来小分发方便。个人效率小工具一个托盘小应用、一个本地文件处理工具没有复杂 UI。Web 前端项目的桌面套壳团队本来就有现成的 Vite/React/Vue 构建产物不想为了桌面端引入 Electron 那套体系。教学演示或比赛 Demo需要桌面应用形态但不想在演示环境里浪费下载时间。不适合的场景包括重度视频编辑类对 GPU 和多媒体能力要求高、需要后台常驻多进程复杂调度的场景、依赖 Chromium 私有特性的场景。这些情况还是乖乖用 Electron 或者原生开发更稳。1.4 国内环境下的特殊性标题里特别提了国内环境不是没原因的。Neutralinojs 官方把客户端二进制放在 GitHub Releases 上分发CLI 在neu run和neu build的时候都需要按需下载对应平台的二进制文件。国内网络环境访问 GitHub Releases 经常出现连接超时、连到一半断流、或者下载速度只有几 KB 的情况这就导致不少人在第一步就没卡住。后文我会专门讲怎么绕开这个坑先按顺序来搭好基础环境再说。2. 国内环境下的搭建与项目初始化2.1 基础环境Node.js 和 npm 镜像源Neutralinojs 的 CLI 是通过 npm 分发的所以首先需要 Node.js 环境。这里我建议直接用 Node.js 的 LTS 版本太旧的版本容易遇到 CLI 依赖不支持的问题。装完 Node.js 后第一件事是把 npm 的 registry 切到国内镜像否则后面安装neutralinojs/neu时大概率会卡在下载阶段。我用的是 npmmirror 镜像执行一次配置就行npm config set registry https://registry.npmmirror.com验证是否生效npm config get registry看到输出是https://registry.npmmirror.com就说明切换成功。这一步虽然很多人已经做过但换电脑、换环境后容易漏掉建议写进团队的初始化文档里。另外Windows 上如果提示类似无法将 npm 识别为 cmdlet...那就是 Node.js 没正确加入 PATH。可以检查系统环境变量里的 Path 是否包含C:\Program Files\nodejs\没有的话手动加上然后重开一个终端窗口。2.2 安装 neu CLInpm 镜像配好后全局安装 Neutralinojs 的命令行工具npm install -g neutralinojs/neu安装完成后验证neu --version能输出版本号就说明 CLI 可用。如果 Linux/macOS 上遇到权限报错常见原因是全局目录没有写权限。推荐装一个 Node 版本管理工具nvm 或 fnm来管理 Node这样既不用 sudo 折腾全局目录后面切换 Node 版本也方便。2.3 创建项目并选择合适的模板使用neu create命令创建项目neu create myapp命令执行后会进入模板选择界面默认是纯 HTML/JS/CSS 的基础模板分别还提供 React、Vue、Svelte、Solid 等前端框架模板。初次使用我建议直接选default 模板这样能最快跑通链路先把 Neutralinojs 自身的机制搞清楚后面再迁移到框架模板就不难。选择模板后CLI 会自动创建项目目录。如果创建过程中卡在某个位置不动大概率又是网络问题在下载某个依赖换源后重试即可。2.4 项目目录结构解读创建完成后进入项目目录看一下结构一个典型的 Neutralinojs 项目长这样myapp/ ├── .gitignore ├── .vscode/ ├── bin/ # 客户端二进制目录首次运行时自动下载 ├── dist/ # 构建输出目录 ├── lib/ # 框架模板相关代码 ├── resources/ │ ├── css/ │ ├── js/ │ ├── img/ │ └── index.html # 前端入口 ├── neu.config.json # 核心配置文件 ├── auth.json # 本地 token 文件首次运行自动生成 └── package.json这里有三个文件要重点说明neu.config.json是核心里面定义了应用 ID、版本号、窗口属性、原生 API 权限、CLI 构建行为等。举个例子{ applicationId: js.neutralino.sample, version: 1.0.0, defaultPort: 0, serving: web, enableServer: true, enableNativeAPI: true, nativeAllowList: [ app.*, computer.*, filesystem.*, os.*, window.*, debug.* ], cli: { binaryName: neutralino, resourcesPath: /resources/, clientLibrary: resources/js/neutralino.js, binaryVersion: 5.4.0 } }nativeAllowList不是摆设它决定了前端页面能调用哪些原生能力。比如你要读本地文件就必须在列表里包含filesystem.*否则调用会被拦截并报错。我见过不少人改完前端代码跑起来发现 API 一直返回失败最后查半天才发现是这个权限列表没配好。bin/目录专门放客户端二进制文件。正常流程下neu run和neu build会自动检查该目录里面没有二进制文件时会尝试下载。这个目录在.gitignore里默认被忽略所以团队协作时每个成员第一次构建都要各自下载一次。auth.json会在首次运行时自动生成里面保存了一个 token用于客户端与本地服务之间的验证。这个文件也是默认被 git 忽略的不需要提交。2.5 前端框架模板和依赖安装策略如果你选的是 Vue 或 React 模板CLI 创建完项目后还需要在项目目录里执行一次npm install把前端依赖拉下来。这里要注意如果全局已经设置了 npmmirror 源npm install默认就会走国内镜像一般来说不会有问题。但有一个容易踩的坑是模板里可能锁定了某个较老的依赖版本在最新的 Node.js 下安装后运行会报语法错误或 API 不兼容。遇到这种情况我的处理方案是先去看模板的 package.json 要求什么 Node 版本再决定是升级模板依赖还是把 Node 版本切换到对应的 LTS 版本。尽量别在生产项目里强制忽略版本兼容性Web 构建链路过碎硬扛版本问题的成本很高。3. 本地运行与开发调试全解3.1neu run背后到底做了什么在项目根目录执行neu run这是开发阶段最常用的命令它的工作流程可以拆成三步检查bin/目录下是否存在当前平台对应的客户端二进制不存在就下载。启动一个本地 Web 服务默认地址类似于http://localhost:你的端口把resources/目录作为静态资源根目录。拉起客户端进程让系统 WebView 加载这个本地服务地址同时建立前端页面和原生 API 之间的桥接通道。看到这里你就明白了开发模式本质上是本地服务 WebView 加载所以你在resources/下改代码刷新一下界面就能看到效果完全没有后端编译步骤迭代非常快。国内环境下这一步最常见的卡点就是第一步下载二进制失败。关于这个问题的多种解决方案我在第 4 节和第 5 节会重点展开。3.2 通过 Native API 访问系统能力Neutralinojs 的核心价值在于它提供了一套统一的window.NeutralinoJavaScript API涵盖文件系统、命令执行、系统信息、窗口控制、托盘、剪贴板、对话框等能力。调用方式跟大多数前端 API 一样基于 Promise。一个简单的例子读取本地 JSON 文件。Neutralino.init(); async function loadConfig() { let data await Neutralino.filesystem.readFile(./config.json); let config JSON.parse(data); console.log(config.appName); }再比如设置窗口标题await Neutralino.window.setTitle(我的轻量应用);还有一个很实用的场景是托盘图标配合事件监听能做出类似最小化到托盘的交互Neutralino.events.on(trayIconClicked, () { Neutralino.window.show(); });这类 API 的使用门槛很低但前提是neu.config.json里的nativeAllowList必须包含对应模块。我建议项目早期就把需要用的模块一次性配好避免后面调试时反复改配置重启。3.3 开发调试的关键技巧开发时如果页面出问题我最常用的调试手段是通过Neutralino.debug.log输出消息或者在代码里主动调起 DevTools。注意Neutralinojs 默认不会在右键菜单里出现检查选项需要显式调用Neutralino.debug.show();或者把它绑到快捷键上。这一点和 Electron 的 F12 习惯差别很大刚迁移过来的同事经常在这里卡住。另一个很实用的技巧是注册window.onunload事件。Neutralinojs 的 WebView 有时会因为资源路径错误而导致窗口白屏清理不掉缓存时注册一个卸载事件做清理能减少不少稀奇古怪的问题。3.4 运行时的常见异常白屏还是端口冲突开发阶段我遇到最多的异常形态是窗口弹出来了但一直白屏。这类问题九成出在资源路径上尤其是neu.config.json的resourcesPath和前端页面里引用的 CSS/JS 路径不一致。Neutralinojs 对路径非常敏感我的经验是所有资源引用一律使用相对路径不要写以/开头的绝对路径也尽量不要引用 CDN 上的资源否则换环境后很容易变成离线白屏。另一个常见问题是端口被占用。defaultPort设为0表示自动分配端口如果你手动指定了端口比如8080而本机其他服务已经占了它客户端就会加载失败。解决办法一是杀掉占用的进程二是把defaultPort改回0让它自动选一个空闲端口。4. 打包从源代码到可分发文件4.1neu build的产物构成开发模式下的页面是通过本地服务加载的打包后的应用不能依赖这个服务所以neu build做的事就是把前端资源和配置固化到客户端二进制的目录里。执行构建命令neu build --release--release表示发布模式它会把resources/目录压缩成一个资源文件并和客户端二进制一起输出到dist/目录。最终你得到的是一堆文件其中最主要的两个是可执行文件Windows 下是.exeLinux 下是 ELF 可执行文件macOS 下是 Mach-O 可执行文件打包后的资源文件默认叫resources.neu结构大致如下dist/ ├── MyApp.exe ├── resources.neu ├── WebView2Loader.dll # Windows 平台相关 └── ... # 其他必要文件如果你没加--release资源会以源文件目录方式放在可执行文件旁边方便调试。两种方式都能跑区别只在资源是否被压缩。4.2 国内环境下客户端二进制下载失败的破解思路这是整个流程里最让人头疼的一环。neu build和neu run都会触发二进制下载下载源默认是 GitHub Releases。在国内网络环境下这个下载经常失败报错信息常常是Unable to download the Neutralinojs client binary或者干脆卡住不动。这里我提供一套按优先级排列的解决方案方案一手动下载并放进 bin 目录这是我最常用的方式适用于网络不稳定但浏览器还能访问 GitHub 的场景。第一步确认你要使用的版本。查看neu.config.json里的cli.binaryVersion记录下来比如5.4.0。第二步打开浏览器访问 GitHub 上 Neutralinojs 官方仓库的 Releases 页面找到对应版本。第三步在 release 资产里下载和你系统匹配的包。例如 Windows x64 对应neutralinojs-v5.4.0-win_x64.zipLinux x64 对应neutralinojs-v5.4.0-linux_x64.zip。第四步把下载的 zip 解压得到一个neutralino或类似名称的可执行文件。把它重命名成 CLI 期望的文件名再放到项目bin/目录下。不同平台下的命名规则如下平台架构文件名Windowsx64neutralino-win_x64.exeWindowsarm64neutralino-win_arm64.exeLinuxx64neutralino-linux_x64Linuxarm64neutralino-linux_arm64macOSx64neutralino-mac_x64macOSarm64neutralino-mac_arm64放入bin/目录后再执行neu run或neu buildCLI 检测到文件已存在就不会再走下载流程了。方案二使用支持断点续传的下载工具如果文件超过几十 MB浏览器直下容易中断可以用支持断点续传的下载工具先把 zip 拉到本地再手动放置。这个方式胜在简单不需要改代码。方案三从开源镜像站获取国内不少镜像站会同步常见开源软件的 release 资产如果你所在的区域访问 GitHub 实在困难可以优先试试镜像站。提示无论用哪种方式最后都要仔细核对二进制文件的版本和平台架构放错文件到bin/目录后运行时报错信息往往不太直观排查反而更浪费时间。4.3 Windows 平台打包成安装包neu build得到的是绿色可执行文件也就是解压即用不需要安装。如果你需要给非技术同事使用做一个安装包体验会好很多。我自己常用 NSIS 来做 Windows 安装程序。思路很简单先用neu build --release产出dist/目录然后用 NSIS 脚本把dist/下的所有文件装进一个安装包在桌面上创建快捷方式。写一个最简单的 NSIS 脚本Name MyApp OutFile MyApp-Setup.exe InstallDir $PROGRAMFILES\MyApp Page directory Page instfiles Section Install SetOutPath $INSTDIR File /r dist\* CreateShortcut $DESKTOP\MyApp.lnk $INSTDIR\MyApp.exe WriteUninstaller $INSTDIR\Uninstall.exe SectionEnd Section Uninstall RMDir /r $INSTDIR Delete $DESKTOP\MyApp.lnk SectionEnd如果你不想写脚本也有开源的第三方工具可以做向导式打包本质都是把文件收集好配置好快捷方式而已。要注意的是Neutralinojs 在 Windows 上依赖 WebView2 运行时。Win10 和 Win11 大部分系统已经自带但如果你要分发到 Win7 或某些精简版系统需要额外带上 WebView2 的安装器或者在安装包脚本里做检测。4.4 Linux 和 macOS 的打包注意事项Linux 平台下neu build生成的 ELF 可执行文件可以直接运行。需要给其他发行版用户分发时可以考虑打成 AppImage。用appimagetool工具把dist/目录整理成标准 AppImage 结构再执行一次工具命令就能得到一个通用的.AppImage文件。基本流程是创建MyApp.AppDir/usr/bin/把可执行文件和资源复制进去。添加.desktop启动文件和应用图标。执行appimagetool MyApp.AppDir。macOS 平台要注意签名问题。不走 App Store 分发的话用户可能需要在系统设置-隐私与安全性里手动允许运行如果你有开发者证书可以用codesign对可执行文件签名但这里涉及证书申请和公证就不展开了。内部团队使用的话让同事在首次打开时右键选择打开即可绕过 Gatekeeper 的限制。4.5 打包后的体积优化与资源策略很多人对 Neutralinojs 的期待就是小但实际打包出来的体积也受前端资源影响。如果你引入了比较大的 JS 库或图片体积照样会膨胀。优化思路有几点前端框架模板里用到的开发依赖在构建时做好 Tree Shaking避免打包进去。图片资源尽量压缩能 WebP 就 WebP。不要在前端里用script srchttps://cdn...引第三方库离线场景会白屏体积也没有变小的意义。合理使用resources.neu缺省策略大文件尽量从本地文件系统读取而不是全部塞进资源包。理论上一个基础模板的 Neutralinojs 应用打包后就在2MB 到 4MB之间这也是它最大的吸引力。5. 常见问题与排查技巧实录5.1 常见问题速查表这套流程跑下来我遇到过不少问题整理成一张速查表供你对照错误现象根本原因解决办法neu run提示下载二进制失败/超时GitHub Releases 访问不稳定手动下载 zip重命名后放入bin/目录neu run报Unable to load resourcesresourcesPath配置不对检查neu.config.json确认resourcesPath指向真实前端目录窗口白屏但无报错前端资源引用了绝对路径或 CDN改为相对路径引用本地资源页面能打开但原生 API 全部失败nativeAllowList缺少模块权限在配置中加入对应模块例如filesystem.*npm install -g权限不足Node 全局目录无写权限使用 nvm/fnm 管理 Node或修复目录权限Windows 打包后无法启动缺少 WebView2 运行时安装 WebView2 或安装包中带上 Runtime Bootstrapper端口被占用导致页面无法加载本地服务启动失败defaultPort设为 0让 CLI 自动选端口Linux 下运行提示缺少 GTK/WebKit 依赖系统缺少 WebKit2GTK安装webkit2gtk相关系统包GitHub 下载的文件放到bin/后仍提示版本错误文件名或版本不匹配核对binaryVersion按平台命名规则重命名5.2 一个值得收藏的排查思路碰到 Neutralinojs 应用异常我建议按这个顺序排查能省很多时间先确认能跑最基础模板。新建一个 default 项目不做任何改动直接neu run。如果基础项目能跑问题大概率出在你自己的代码或配置如果基础项目都跑不起来先解决环境问题。再确认资源路径。所有页面、图片、脚本尽量相对路径引用这是白屏问题第一大来源。检查nativeAllowList。不要一出问题就怀疑框架先看原生 API 的权限列表是否覆盖你调用的模块。最后看日志。Neutralinojs 的客户端会在终端输出不少启动日志别忽略它们。很多报错信息虽然不那么友好但关键信息都在里面。5.3 从 Electron 迁移过来时的认知纠正如果你是从 Electron 迁过来的最容易踩的坑是观念没转过来。Electron 里你能访问完整 Node.js 环境想读文件、跑命令、甚至开个子进程都很随意。Neutralinojs 不是一个大容器它只是给 WebView 提供了一层原生桥接你的前端代码还是运行在受限环境中不能直接写require(fs)只能通过Neutralino.filesystem这类 API 来实现。这带来的直接影响是一些在 Electron 里很轻量的操作在 Neutralinojs 里要重构成 API 调用甚至要借助官方扩展机制才能实现。遇到这种情况先别急着喷框架反思一下这个功能是不是必须放在客户端层。能放前端的尽量放前端放不了再通过扩展、或者起一个辅助进程来做。5.4 团队协作时的工程化建议当 Neutralinojs 项目进入团队协作阶段有几个实践我觉得很值得坚持在仓库里放一份.nvmrc锁定 Node.js 版本避免成员间版本不一致导致构建行为不同。把版本号和对应二进制下载方式写进 README尤其写清楚国内环境下如何获取二进制这是新成员上岗最卡的一步。尽量统一的neu.config.json基础配置不要每个成员各自改权、改端口提交前检查 diff。构建流程尽量接入 CI在 CI 上提前把 Windows、Linux 的产物都跑一遍避免本地能跑、别人拉下来就挂。我个人的体会是Neutralinojs 特别适合内部工具 轻量分发这个定位它解决了我之前用 Electron 做小工具时最头疼的体积和内存问题。虽然它的生态不如 Electron 丰富遇到冷门问题时要靠源码和社区自己抠但架不住它快、小、简单一旦把客户端的二进制下载这关过了开发体验其实非常清爽。后面如果你想更进一步可以去研究它的扩展机制官方文档里给出的扩展点可以让它跑更重的后台任务。不过对大部分人来说先用好我这里提到的搭建、运行、打包这条主线就足够支撑日常工作了。