React构建的Electron应用集成Node.js服务器后异步函数失效排查

1. 修正数据库路径配置 #

如果使用SQLite这类文件型数据库，开发环境的相对路径在打包后会失效（Electron打包后资源会被放入只读的app.asar包）。改用Electron提供的userData目录（用户可读写的系统目录）存储数据库文件：

// electron主进程文件（electron.js）
const { app } = require('electron');
const path = require('path');
// 全局声明数据库路径，供Express服务器调用
global.dbFilePath = path.join(app.getPath('userData'), 'app_database.db');

在Express的数据库连接代码中使用该路径：

// server/db.js
const sqlite3 = require('sqlite3').verbose();
const { promisify } = require('util');

// 初始化连接池（以SQLite为例）
const db = new sqlite3.Database(global.dbFilePath);
db.getAsync = promisify(db.get);
db.allAsync = promisify(db.all);

async function getConnection() {
  // SQLite本身基于单连接模型，直接返回promisified的实例即可
  return db;
}

module.exports = { getConnection };

2. 确保连接池初始化完成后启动服务 #

不要在require('server')时直接启动Express，先验证数据库连接可用性，再启动服务：

// electron.js
async function initApp() {
  try {
    // 先验证数据库连接
    const { getConnection } = require('./server/db');
    await getConnection();
    console.log('数据库连接初始化成功');
    
    // 再启动Express服务器
    require('./server');
    
    // 最后创建Electron窗口
    createWindow();
  } catch (err) {
    console.error('初始化失败:', err);
    app.quit();
  }
}

app.whenReady().then(initApp);

3. 补全接口错误捕获 #

在登录接口中添加完整的错误捕获，避免异步异常被静默：

// server/routes/login.js
app.post('/login', async (req, res) => {
  try {
    const db = await getConnection();
    const user = await db.getAsync('SELECT * FROM users WHERE username = ?', [req.body.username]);
    
    if (!user) {
      return res.status(401).json({ success: false, message: '用户不存在' });
    }
    
    res.json({ success: true, data: user });
  } catch (err) {
    console.error('登录接口异常:', err);
    res.status(500).json({ success: false, message: '服务器内部错误' });
  }
});

4. 排查权限问题 #

如果应用安装到C:\Program Files这类系统目录，默认没有写入权限，会导致数据库文件无法创建/读写。解决方式：

• 打包时配置Electron Builder，将默认安装路径改为用户目录（如%USERPROFILE%\AppData\Local\YourApp）
• 强制将数据库文件放到userData目录（前面步骤已覆盖）

1. 架构分层规范 #

• 主进程（Electron）：负责系统级操作（数据库连接、窗口管理、文件读写、本地服务启动），作为业务逻辑和系统资源的中间层
• 渲染进程（React）：仅负责UI渲染和用户交互，通过IPC（进程间通信）与主进程交互，不直接操作数据库
• 服务层：将数据库操作、业务逻辑封装为独立模块，托管在主进程，避免渲染进程直接接触底层资源

2. 数据库选型建议 #

• 单机应用首选SQLite：文件型数据库，无需额外安装服务器，体积小、性能满足桌面场景需求
• 需多端同步或复杂查询场景，可选MySQL/MariaDB（可打包轻量版服务器随应用分发）
• ORM工具推荐Prisma或Sequelize：简化CRUD操作，支持多数据库，减少重复代码

3. 进程通信最佳方式 #

避免渲染进程直接调用数据库模块，使用Electron的IPC机制通信：

// 主进程IPC监听
const { ipcMain } = require('electron');
const dbService = require('./server/services/dbService');

ipcMain.handle('user:login', async (_, username) => {
  return await dbService.login(username);
});

// React组件中调用
const { ipcRenderer } = window.require('electron');

async function handleLogin(username) {
  try {
    const result = await ipcRenderer.invoke('user:login', username);
    // 处理登录结果
  } catch (err) {
    console.error(err);
  }
}

4. 打包优化要点 #

• 不要将数据库文件打包到app.asar（只读），运行时动态生成到userData目录
• 使用Electron Builder打包，配置extraResources将必要的数据库初始化脚本、依赖文件拷贝到安装目录
• 避免将Express服务器作为独立依赖安装，直接将server代码并入项目主进程模块，减少打包路径问题

5. 性能与稳定性优化 #

• 数据库连接池复用：对MySQL等客户端/服务器型数据库，初始化全局连接池避免频繁创建连接
• 数据库索引优化：对常用查询字段添加索引，提升查询速度
• 日志记录：将错误日志写入userData目录，方便排查线上问题
• 错误处理：给用户展示友好提示，避免暴露底层数据库错误信息

内容的提问来源于stack exchange，提问作者Haroun Darjaj