SerialAssist 串口调试助手 - 源码编译指南

SerialAssist 串口调试助手 - 源码编译指南

📋 编译环境要求

操作系统要求

• Windows: Windows 10 或更高版本
• macOS: macOS 10.14 或更高版本
• Linux: Ubuntu 18.04 或其他主流发行版

开发工具要求

• Node.js: 18.0.0 或更高版本
• npm: 8.0.0 或更高版本（随Node.js安装）
• Git: 用于克隆代码仓库
• Python: 3.7-3.11（用于编译native模块）
• Visual Studio Build Tools（Windows）或 Xcode Command Line Tools（macOS）

🚀 快速开始

附件下载-[SerialAssistCode-5410.rar](https://url66.ctfile.com/f/17802766-1523681980-49a8d0?p=1150 (访问密码: 1150)

1. 下载项目源码

# 通过附件下载源码-
SerialAssistCode.rar

2. 安装项目依赖

# 解压，进行到解压目录，安装所有依赖包
npm install

# 或者使用 yarn
yarn install

3. 重新编译Native模块

# 重新编译native模块以匹配当前Electron版本
npm run rebuild-native

Native模块编译 - 确保模块与Electron版本兼容

4. 开发环境运行

# 启动开发服务器
npm run electron-dev

开发环境启动 - 应用程序成功运行界面

🔧 详细编译步骤

步骤1：环境准备

1.1 安装Node.js

访问 Node.js官网 下载并安装LTS版本。

验证安装：

D:\>node --version
v18.20.4

D:\>npm --version
10.7.0

Node.js安装验证 - 确认版本信息

1.2 安装构建工具

Windows系统：

# 安装Visual Studio Build Tools
npm install --global windows-build-tools

# 或者安装Python和Visual Studio Build Tools
npm install --global --production windows-build-tools

macOS系统：

# 安装Xcode命令行工具
xcode-select --install

Linux系统：

# Ubuntu/Debian
sudo apt-get install build-essential

# CentOS/RHEL
sudo yum groupinstall "Development Tools"

构建工具安装 - Windows Visual Studio Build Tools

步骤2：获取源码

2.1 下载附件

# 进入项目目录
cd SerialAssist

2.2 检查项目结构

SerialAssist/
├── src/                    # 前端源码
│   ├── components/         # React组件
│   ├── contexts/          # Context上下文
│   ├── utils/             # 工具函数
│   └── main.jsx           # 主入口文件
├── electron/              # Electron主进程源码
│   ├── main.js            # 主进程入口
│   └── preload.js         # 预加载脚本
├── public/                # 静态资源
├── dist/                  # 前端构建输出
├── dist-electron/         # Electron构建输出
├── package.json           # 项目配置文件
├── vite.config.js         # Vite配置文件
└── README.md              # 项目说明

项目结构展示 - 完整的目录层次结构

步骤3：安装依赖

3.1 安装npm依赖

# 清理npm缓存（可选）
npm cache clean --force

# 安装所有依赖
npm install

3.2 验证依赖安装

# 查看依赖列表
npm list --depth=0

# 检查关键依赖
npm list electron
npm list serialport
npm list better-sqlite3

依赖验证结果 - 确认关键包正确安装

步骤4：编译Native模块

4.1 理解Native模块

项目中使用的Native模块：

• serialport: 串口通信库
• better-sqlite3: SQLite数据库驱动

4.2 重新编译模块

# 方法1：使用项目预配置的脚本
npm run rebuild-native

# 方法2：手动使用electron-rebuild
npx electron-rebuild --electron-version=28.3.3

# 方法3：只重新编译特定模块
npx electron-rebuild --electron-version=28.3.3 --only=better-sqlite3
npx electron-rebuild --electron-version=28.3.3 --only=serialport

Native模块编译成功 - 所有模块重新编译完成

4.3 处理编译错误

常见错误1：Python版本不兼容

# 检查Python版本
python --version

# 如果版本不对，可以指定Python路径
npm config set python /path/to/python3.x

常见错误2：构建工具缺失

# Windows - 重新安装构建工具
npm install --global windows-build-tools

# macOS - 重新安装Xcode工具
xcode-select --install

常见错误3：权限问题

# 清理node_modules重新安装
rm -rf node_modules
npm install

# 或使用sudo（Linux/macOS）
sudo npm install

步骤5：构建和运行

5.1 开发环境运行

# 启动开发服务器（前端热重载）
npm run dev

# 启动Electron应用（开发模式）
npm run electron-dev

5.2 生产环境构建

# 构建前端资源
npm run build

# 构建Electron应用
npm run electron-pack

# 构建发布版本
npm run dist

步骤6：打包发布

6.1 配置打包选项

编辑 package.json 中的 build 配置：

{
  "build": {
    "appId": "com.serialassist.app",
    "productName": "SerialAssist",
    "directories": {
      "output": "release"
    },
    "files": [
      "dist/**/*",
      "dist-electron/**/*"
    ],
    "win": {
      "target": "nsis",
      "icon": "build/icon.ico"
    },
    "mac": {
      "target": "dmg",
      "icon": "build/icon.icns"
    },
    "linux": {
      "target": "AppImage",
      "icon": "build/icon.png"
    }
  }
}

6.2 准备图标文件

build/
├── icon.ico      # Windows图标（256x256）
├── icon.icns     # macOS图标
└── icon.png      # Linux图标（512x512）

6.3 执行打包

# 打包当前平台
npm run dist

# 打包所有平台
npm run dist -- --win --mac --linux

# 打包特定平台
npm run dist -- --win
npm run dist -- --mac
npm run dist -- --linux

🐛 常见问题解决

问题1：better-sqlite3编译失败

错误信息：

Error: The module was compiled against a different Node.js version

解决方案：

# 删除node_modules和package-lock.json
rm -rf node_modules package-lock.json

# 重新安装依赖
npm install

# 重新编译native模块
npm run rebuild-native

问题2：serialport模块找不到

错误信息：

Error: Cannot find module 'serialport'

解决方案：

# 重新安装serialport
npm uninstall serialport
npm install serialport@13.0.0

# 重新编译
npx electron-rebuild --electron-version=28.3.3 --only=serialport

问题3：Electron应用无法启动

可能原因：

1. 前端资源未构建
2. 主进程文件缺失
3. 权限问题

解决方案：

# 重新构建前端
npm run build

# 检查dist目录是否存在
ls -la dist/

# 检查Electron主进程文件
ls -la dist-electron/

# 重新启动应用
npm run electron-dev

问题4：数据库访问错误

错误信息：

Error: SQLITE_CANTOPEN: unable to open database file

解决方案：

# 检查数据库文件权限
chmod 666 serialassist.db

# 或删除数据库文件重新创建
rm serialassist.db

📦 发布版本构建

构建配置优化

1. 生产环境优化

// vite.config.js
export default {
  build: {
    minify: 'terser',
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          electron: ['electron']
        }
      }
    }
  }
}

2. 代码签名（可选）

{
  "build": {
    "win": {
      "certificateFile": "path/to/certificate.p12",
      "certificatePassword": "password"
    },
    "mac": {
      "identity": "Developer ID Application: Your Name"
    }
  }
}

自动化构建脚本

创建 build.sh 脚本：

#!/bin/bash
echo "开始构建SerialAssist..."

# 清理旧文件
rm -rf dist dist-electron release

# 安装依赖
npm install

# 重新编译native模块
npm run rebuild-native

# 构建前端
npm run build

# 打包应用
npm run dist

echo "构建完成！输出目录：./release"

🔍 调试技巧

开发调试

# 启动调试模式
npm run electron-dev

# 查看控制台输出
# 在Electron应用中按F12打开开发者工具或CTRL+SHIFT+I

生产调试

# 启用详细日志
DEBUG=* npm run electron-dev

# 查看Electron主进程日志
tail -f electron.log

性能分析

# 启动性能分析
npm run electron-dev -- --inspect=9229

# 使用Chrome DevTools连接
# 打开chrome://inspect

📚 相关资源

官方文档

• Node.js官网
• Electron官网
• React官网
• Vite官网

社区资源

• Electron Builder文档
• SerialPort库文档
• Better-SQLite3文档

如果您在编译过程中遇到问题，请联系 itgather@163.com 获取技术支持。

附件下载-[SerialAssistCode-5410.rar](https://url66.ctfile.com/f/17802766-1523681980-49a8d0?p=1150 (访问密码: 1150)

相关文章

SerialAssist 串口调试助手 - 功能介绍