如何正确配置Neutralinojs与Vite HMR协同工作？

问题现状 #

尝试集成Neutralinojs与Vite实现HMR热更新，但在macOS和Windows上均失败；使用vite build --watch仅能触发全量页面刷新，无法实现局部热更新；通过双终端分别启动vite和npx @neutralinojs/neu run -- --frontend-lib-dev --window-enable-inspector后，热更新仍不生效。

核心配置修正 #

1. 更新 vite.config.js #

添加HMR跨域与WebSocket专属配置，确保Neutralino桌面窗口能正常连接Vite热更新服务：

import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    outDir: "dist",
    emptyOutDir: false
  },
  server: {
    port: 3000,
    strictPort: true, // 强制占用3000端口，避免端口冲突
    cors: true, // 允许跨域请求，适配Neutralino桌面环境的跨域限制
    hmr: {
      host: 'localhost',
      port: 3000,
      protocol: 'ws' // 明确指定WebSocket协议，避免自动适配时出现异常
    }
  }
});

2. 调整 neutralino.config.json #

修正开发模式下的资源加载配置，确保Neutralino正确指向Vite开发服务器：

{
  "applicationId": "js.neutralino.zero",
  "version": "1.0.0",
  "defaultMode": "window",
  "port": 0,
  "documentRoot": "/", // 开发模式下无需绑定dist目录，由frontendLibrary.devUrl接管资源加载
  "url": "/",
  "enableServer": true,
  "enableNativeAPI": true,
  "exportAuthInfo": true,
  "nativeAllowList": [
    "app.*"
  ],
  "modes": {
    "window": {
      "title": "neu-vite",
      "width": 800,
      "height": 500,
      "minWidth": 400,
      "minHeight": 200,
      "icon": "/public/appIcon.png"
    }
  },
  "cli": {
    "binaryName": "neu-vite",
    "resourcesPath": "/dist/",
    "extensionsPath": "/extensions/",
    "clientLibrary": "/public/neutralino.js",
    "binaryVersion": "4.12.0",
    "clientVersion": "3.10.0",
    "frontendLibrary": {
      "patchFile": "/index.html", // 确保指向项目根目录的index.html文件
      "devUrl": "http://localhost:3000"
    }
  }
}

正确操作流程 #

1. 清空项目根目录下的dist文件夹，避免旧编译文件干扰开发流程
2. 终端1启动Vite开发服务器：vite
3. 终端2启动Neutralino开发模式：npx @neutralinojs/neu run -- --frontend-lib-dev --window-enable-inspector
4. 打开Neutralino窗口的开发者工具（快捷键Ctrl+Shift+I/Cmd+Opt+I），检查Console面板是否存在WebSocket连接错误，若有则核对端口与配置的一致性

额外排查点 #

• 确保项目根目录的index.html中已正确引入Neutralino客户端脚本：<script src="/public/neutralino.js"></script>
• 关闭系统防火墙或允许Vite的3000端口进行网络通信
• 若使用Vue/React等框架，确认框架自带的HMR插件已正常启用

内容的提问来源于stack exchange，提问作者Jouni Kantola