7.2 KiB
7.2 KiB
Nex
基于 NeutralinoJS 的轻量级桌面应用框架，前端使用 React + TypeScript + Vite，后端使用 Go 作为 Native Extension。
项目结构
nex/
├── neutralino.config.json # Neutralino 主配置文件
├── README.md
├── bin/ # Neutralino 运行时二进制文件（各平台）
│ ├── neutralino-win_x64.exe
│ ├── neutralino-linux_x64
│ ├── neutralino-linux_arm64
│ ├── neutralino-linux_armhf
│ ├── neutralino-mac_x64
│ ├── neutralino-mac_arm64
│ └── neutralino-mac_universal
├── frontend/ # 前端项目（React + TypeScript + Vite）
│ ├── package.json
│ ├── index.html # Vite 入口 HTML
│ ├── vite.config.ts
│ ├── tsconfig.json
│ ├── biome.json # Biome 格式化配置
│ ├── eslint.config.js # ESLint 配置
│ ├── public/ # 静态资源
│ │ └── favicon.svg
│ ├── dist/ # 构建产物（由 vite build 生成）
│ └── src/
│ ├── main.tsx # 应用入口，初始化 React 和 Neutralino
│ ├── App.tsx # 根组件
│ ├── components/ # 可复用 UI 组件
│ ├── pages/ # 页面组件
│ ├── hooks/ # 自定义 React Hooks
│ ├── utils/ # 工具函数
│ ├── types/ # TypeScript 类型定义
│ └── styles/
│ └── global.scss # 全局样式
└── backend/ # 后端项目（Go Native Extension）
├── go.mod / go.sum # Go 模块依赖
├── build.sh # macOS / Linux 构建脚本
├── build.cmd # Windows 构建脚本
├── cmd/
│ └── nex/
│ └── main.go # Go 扩展入口，定义事件处理与业务逻辑
└── internal/
└── neutralino/
└── client.go # Neutralino WebSocket 客户端通信库
技术栈
| 层级 | 技术 |
|---|---|
| 桌面框架 | NeutralinoJS 6.7.0 |
| 前端 | React 19 + TypeScript 6 |
| 构建工具 | Vite 8 + Bun |
| 样式 | SCSS |
| 代码检查 | ESLint + Biome |
| 后端 | Go 1.22 |
| 后端通信 | WebSocket (gorilla/websocket) |
架构说明
本项目采用 Neutralino Extension 架构，前后端通过 WebSocket 进行异步通信：
┌─────────────────┐ WebSocket ┌──────────────┐
│ React Frontend │ ◄────────────► │ Go Backend │
│ (浏览器渲染) │ │ (Extension) │
└─────────────────┘ └──────────────┘
│ │
@neutralinojs/lib internal/neutralino
(JS API 调用) (WSClient)
- 前端 通过
@neutralinojs/lib的init()初始化 Neutralino 运行时，使用Neutralino.events发送和监听事件。 - 后端 作为 Neutralino Extension 启动，通过 WebSocket 与 Neutralino 核心通信，接收前端事件并响应。
- 所有事件通信均为异步，事件队列保证不丢失。
快速开始
环境要求
- Go >= 1.22
- Bun（推荐）或 Node.js >= 18
- Neutralino CLI：
npm install -g @neutralinojs/neu
1. 安装前端依赖
cd frontend
bun install
2. 编译 Go 后端
cd backend
# macOS / Linux
./build.sh
# Windows
build.cmd
构建产物 nex（或 nex.exe）输出到 backend/ 目录下。
3. 安装 Neutralino 二进制
neu update
4. 开发模式运行
neu run
此命令会启动 Vite 开发服务器（端口 5173）和 Neutralino 窗口，前端改动自动热更新。
5. 构建生产包
# 构建前端
cd frontend && bun run build
# 构建 Neutralino 应用
neu build
前端开发指引
路径别名
项目配置了 @ 指向 src/ 目录，在导入时可直接使用：
import App from "@/App.tsx";
import "@/styles/global.scss";
目录规范
| 目录 | 用途 |
|---|---|
src/components/ |
可复用 UI 组件，通过 index.ts 统一导出 |
src/pages/ |
页面级组件 |
src/hooks/ |
自定义 React Hooks |
src/utils/ |
工具函数 |
src/types/ |
TypeScript 类型定义 |
src/styles/ |
全局及局部样式（SCSS） |
代码质量工具
# ESLint 检查
bun run lint
# ESLint 自动修复
bun run lint:fix
# Biome 格式化检查
bun run format:check
# Biome 格式化（写入）
bun run format
# TypeScript 类型检查
bun run typecheck
调用 Go 后端
前端通过 Neutralino 事件系统与 Go 后端通信：
// 发送事件到 Go 后端
Neutralino.events.dispatch("runGo", {
function: "ping",
parameter: "Hello from Frontend",
});
// 监听 Go 后端返回的事件
Neutralino.events.on("pingResult", (event) => {
console.log(event.detail);
});
后端开发指引
目录结构
backend/
├── cmd/nex/main.go # 入口，注册事件回调
├── internal/neutralino/client.go # WSClient 通信库
├── build.sh / build.cmd # 构建脚本
└── go.mod / go.sum # 依赖管理
添加新的 Go 函数
在 cmd/nex/main.go 的 processAppEvent 回调中添加新的函数分支：
func processAppEvent(data neutralino.EventMessage) {
if ext.IsEvent(data, "runGo") {
if d, ok := data.Data.(map[string]interface{}); ok {
if d["function"] == "myFunc" {
result := make(map[string]interface{})
result["result"] = "处理结果"
ext.Send("myFuncResult", result)
}
}
}
}
WSClient API
| 方法 | 说明 |
|---|---|
Run(callback, debug) |
启动扩展主循环，每条消息触发 callback |
IsEvent(data, eventName) |
判断事件名是否匹配 |
Send(event, data) |
向前端发送结构化事件（map[string]interface{}） |
SendMessageString(event, data) |
向前端发送字符串事件 |
修改后端代码后需重新编译：
cd backend && ./build.sh # 或 build.cmd
Neutralino 配置说明
neutralino.config.json 关键配置：
| 字段 | 说明 |
|---|---|
applicationId |
应用标识 com.lanyuanxiaoyao.nex |
defaultMode |
默认以窗口模式运行 |
documentRoot |
前端资源根路径 /frontend/ |
cli.resourcesPath |
构建时打包的前端产物路径 /frontend/dist |
cli.extensionsPath |
后端扩展路径 /backend/ |
extensions |
扩展定义，指定各平台启动命令 |
nativeAllowList |
Native API 白名单 |