257 lines
7.2 KiB
Markdown
257 lines
7.2 KiB
Markdown
# Nex
|
||
|
||
基于 [NeutralinoJS](https://neutralino.js.org) 的轻量级桌面应用框架，前端使用 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](https://go.dev/dl/) >= 1.22
|
||
- [Bun](https://bun.sh/)（推荐）或 Node.js >= 18
|
||
- [Neutralino CLI](https://neutralino.js.org/docs/cli/neu-cli/)：`npm install -g @neutralinojs/neu`
|
||
|
||
### 1. 安装前端依赖
|
||
|
||
```bash
|
||
cd frontend
|
||
bun install
|
||
```
|
||
|
||
### 2. 编译 Go 后端
|
||
|
||
```bash
|
||
cd backend
|
||
|
||
# macOS / Linux
|
||
./build.sh
|
||
|
||
# Windows
|
||
build.cmd
|
||
```
|
||
|
||
构建产物 `nex`（或 `nex.exe`）输出到 `backend/` 目录下。
|
||
|
||
### 3. 安装 Neutralino 二进制
|
||
|
||
```bash
|
||
neu update
|
||
```
|
||
|
||
### 4. 开发模式运行
|
||
|
||
```bash
|
||
neu run
|
||
```
|
||
|
||
此命令会启动 Vite 开发服务器（端口 5173）和 Neutralino 窗口，前端改动自动热更新。
|
||
|
||
### 5. 构建生产包
|
||
|
||
```bash
|
||
# 构建前端
|
||
cd frontend && bun run build
|
||
|
||
# 构建 Neutralino 应用
|
||
neu build
|
||
```
|
||
|
||
## 前端开发指引
|
||
|
||
### 路径别名
|
||
|
||
项目配置了 `@` 指向 `src/` 目录，在导入时可直接使用：
|
||
|
||
```ts
|
||
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） |
|
||
|
||
### 代码质量工具
|
||
|
||
```bash
|
||
# 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 后端通信：
|
||
|
||
```ts
|
||
// 发送事件到 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` 回调中添加新的函数分支：
|
||
|
||
```go
|
||
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)` | 向前端发送字符串事件 |
|
||
|
||
修改后端代码后需重新编译：
|
||
|
||
```bash
|
||
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 白名单 |
|
||
|
||
## 参考链接
|
||
|
||
- [NeutralinoJS 官方文档](https://neutralino.js.org/docs/)
|
||
- [React 官方文档](https://react.dev/)
|
||
- [Vite 官方文档](https://vite.dev/)
|
||
- [Go 官方文档](https://go.dev/doc/)
|