个人桌面端

Appearance

常见问题 FAQ ​

安装和环境 ​

Q1: Electron 安装失败，提示 "Electron failed to install correctly" ​

问题描述：

Electron failed to install correctly, please delete node_modules/electron and try installing again

原因分析：

  • 网络问题导致 Electron 二进制文件下载失败
  • 国内访问 GitHub Releases 速度慢或被屏蔽
  • 缓存文件损坏

解决方案：

方案 1：使用项目提供的修复命令

bash
pnpm fix:electron-deps

方案 2：配置国内镜像

bash
# Windows PowerShell
$env:ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
pnpm install

# Windows CMD
set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
pnpm install

# Mac/Linux
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
pnpm install

方案 3：手动下载安装

bash
# 1. 删除 node_modules/electron
rm -rf node_modules/electron

# 2. 清除 pnpm 缓存
pnpm store prune

# 3. 重新安装
pnpm install

方案 4：使用代理

bash
# 如果有 HTTP 代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
pnpm install

Q2: Node.js 版本不符合要求 ​

问题描述：

ERROR: The engine "node" is incompatible with this module. Expected version ">=18.0.0". Got "16.14.0"

解决方案：

使用 nvm 管理 Node.js 版本：

bash
# Windows - 使用 nvm-windows
# 下载：https://github.com/coreybutler/nvm-windows/releases

# 安装 Node.js 18
nvm install 18

# 切换到 Node.js 18
nvm use 18

# Mac/Linux - 使用 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装并使用 Node.js 18
nvm install 18
nvm use 18

或直接下载安装：

Q3: pnpm 命令不存在 ​

问题描述：

bash
pnpm: command not found

解决方案：

bash
# 使用 npm 全局安装 pnpm
npm install -g pnpm

# 或使用 npx（临时使用）
npx pnpm install

# 验证安装
pnpm --version

开发调试 ​

Q4: 开发模式启动失败，窗口无法打开 ​

问题描述：

  • 执行 pnpm dev 后，命令行没有错误但窗口不出现
  • 或提示 "Error: Electron failed to load"

排查步骤：

1. 检查端口占用

bash
# Windows
netstat -ano | findstr :5173

# Mac/Linux
lsof -i :5173

# 如果端口被占用，修改 Vite 配置
# renderer/vite.config.js
export default defineConfig({
  server: {
    port: 5174  // 改为其他端口
  }
});

2. 检查防火墙

  • Windows：允许 Node.js 和 Electron 通过防火墙
  • Mac：系统偏好设置 -> 安全性与隐私 -> 防火墙

3. 查看详细日志

bash
# 开启详细日志
DEBUG=* pnpm dev

# 或分别启动查看具体错误
pnpm dev:renderer  # 先启动渲染进程
pnpm dev:main      # 再启动主进程

4. 清除缓存重试

bash
# 清除 node_modules
rm -rf node_modules
rm -rf packages/*/node_modules

# 清除 pnpm 缓存
pnpm store prune

# 重新安装
pnpm install

Q5: 页面加载空白，控制台无错误 ​

可能原因：

  1. Vue Router 路由配置错误
  2. 静态资源路径错误
  3. CSP（内容安全策略）限制

解决方案：

1. 检查路由配置

javascript
// renderer/src/router/index.js
const router = createRouter({
  history: createWebHashHistory(), // 使用 hash 模式
  routes: [
    {
      path: '/',
      component: () => import('../pages/Home.vue'),
    },
  ],
});

2. 检查 Vite 配置的 base

javascript
// renderer/vite.config.js
export default defineConfig({
  base: './', // 使用相对路径
  build: {
    outDir: 'dist',
  },
});

3. 检查 CSP 配置

html
<!-- renderer/index.html -->
<meta
  http-equiv="Content-Security-Policy"
  content="default-src 'self' 'unsafe-inline' 'unsafe-eval' data: blob:;"
/>

4. 打开开发者工具调试

javascript
// 在主进程中
mainWindow.webContents.openDevTools();

// 或使用快捷键
// Ctrl+Alt+D（已配置）

Q6: 热更新（HMR）不工作 ​

问题描述：

  • 修改 Vue 文件后，页面不自动刷新
  • 需要手动刷新才能看到更改

解决方案：

1. 检查 Vite HMR 配置

javascript
// renderer/vite.config.js
export default defineConfig({
  server: {
    hmr: {
      protocol: 'ws',
      host: 'localhost',
    },
  },
});

2. 确保使用开发模式加载

javascript
// main/src/core/window.js
const isDev = process.env.NODE_ENV === 'development';

if (isDev) {
  win.loadURL('http://localhost:5173'); // HMR 工作
} else {
  win.loadFile('renderer/dist/index.html');
}

3. 检查防火墙是否阻止 WebSocket 连接

打包部署 ​

Q7: 打包后应用无法启动 ​

问题描述：

  • 双击 exe 文件后，没有任何反应
  • 或闪退，没有错误提示

调试方法：

1. 使用命令行启动，查看错误信息

bash
cd dist/win-unpacked
./vue3-simple-electron.exe

# 或
start vue3-simple-electron.exe

2. 检查日志文件

bash
# Windows
%APPDATA%/vue3-simple-electron/logs/main.log

# Mac
~/Library/Application Support/vue3-simple-electron/logs/main.log

# Linux
~/.config/vue3-simple-electron/logs/main.log

3. 常见原因和解决方案：

原因 1：资源文件路径错误

javascript
// ❌ 错误：使用绝对路径
const iconPath = 'D:/project/resources/icon.ico';

// ✅ 正确：使用相对路径
const iconPath = path.join(__dirname, '../resources/icon.ico');

// ✅ 或使用 process.resourcesPath
const iconPath = path.join(process.resourcesPath, 'icon.ico');

原因 2：依赖未正确打包

javascript
// electron-builder.config.js
module.exports = {
  files: ['packages/main/dist/**/*', 'packages/renderer/dist/**/*', '!node_modules/**/*'],
  extraResources: [
    {
      from: 'resources',
      to: 'resources',
    },
  ],
  asarUnpack: [
    '**/*.node', // 原生模块
    'resources/**/*',
  ],
};

原因 3：配置文件缺失

  • 确保 resources/config/config.ini 被正确打包
  • 检查 electron-builder.config.js 中的 extraResources 配置

Q8: 打包后文件体积过大 ​

问题描述：

  • 安装包超过 200MB
  • 解压后文件夹超过 500MB

优化方案：

1. 排除不必要的依赖

javascript
// electron-builder.config.js
module.exports = {
  files: [
    '!**/*.map', // 排除 source map
    '!**/*.ts', // 排除 TypeScript 源文件
    '!**/README.md', // 排除文档
    '!**/test/**', // 排除测试文件
    '!**/docs/**', // 排除文档目录
  ],
};

2. 使用 asar 压缩

javascript
module.exports = {
  asar: true, // 启用 asar 打包
  asarUnpack: [
    '**/*.node', // 原生模块不能被 asar 打包
  ],
};

3. 压缩安装包

javascript
module.exports = {
  compression: 'maximum', // 最大压缩
  nsis: {
    oneClick: false,
    perMachine: false,
    allowToChangeInstallationDirectory: true,
  },
};

4. 分析依赖大小

bash
# 安装分析工具
pnpm add -D rollup-plugin-visualizer

# 构建时生成分析报告
pnpm build

# 查看 stats.html

5. 删除开发依赖

json
// package.json
{
  "devDependencies": {
    // 开发依赖不会被打包
  },
  "dependencies": {
    // 只保留生产依赖
  }
}

Q9: 打包失败，提示 "Cannot find module" ​

问题描述：

Error: Cannot find module '@/utils/logger'

原因：

  • Webpack/Vite 别名在打包后不生效
  • 动态 require 路径解析失败

解决方案：

1. 避免使用别名（主进程）

javascript
// ❌ 不推荐：使用别名
const logger = require('@/utils/logger');

// ✅ 推荐：使用相对路径
const logger = require('../utils/logger');

2. 避免动态 require

javascript
// ❌ 不推荐：动态路径
const moduleName = 'logger';
const logger = require(`../utils/${moduleName}`);

// ✅ 推荐：静态路径
const logger = require('../utils/logger');

3. 配置 Webpack externals

javascript
// webpack.config.js（如果使用）
module.exports = {
  externals: {
    electron: 'commonjs electron',
    fs: 'commonjs fs',
    path: 'commonjs path',
  },
};

功能使用 ​

Q10: 悬浮球不显示 ​

问题描述：

  • 点击托盘菜单"显示悬浮球"没有反应
  • 或使用快捷键 Ctrl+Alt+H 无效

排查步骤：

1. 检查悬浮球服务是否初始化

javascript
// main/src/apps/app-initializer.js
FloatingBallService.initialize(mainWindow);

2. 检查悬浮球 HTML 文件

bash
# 确保文件存在
packages/renderer/ball.html

# 检查是否被正确打包
dist/win-unpacked/resources/app.asar（或 app 目录）

3. 查看控制台错误

javascript
// 在悬浮球服务中添加日志
FloatingBallService.create = function () {
  try {
    logger.info('创建悬浮球窗口');
    // ...
  } catch (error) {
    logger.error('创建悬浮球失败:', error);
  }
};

4. 检查窗口是否被隐藏

javascript
// 尝试强制显示
const floatingWindow = FloatingBallService.floatingWindow;
if (floatingWindow) {
  floatingWindow.show();
  floatingWindow.focus();
}

Q11: 插件无法加载 ​

问题描述：

  • 上传插件后显示"加载失败"
  • 插件列表为空

解决方案：

1. 检查插件格式

my-plugin.zip
├── manifest.json    ✅ 必须包含
├── index.js         ✅ 入口文件
├── package.json     ⚠️  可选
└── assets/          ⚠️  可选

2. 验证 manifest.json

json
{
  "id": "my-plugin", // ✅ 必填，唯一标识
  "name": "我的插件", // ✅ 必填
  "version": "1.0.0", // ✅ 必填
  "main": "index.js", // ✅ 必填，入口文件
  "description": "插件描述", // ⚠️  可选
  "author": "作者", // ⚠️  可选
  "permissions": [] // ⚠️  可选
}

3. 检查入口文件

javascript
// index.js
module.exports = {
  // ✅ 必须导出 initialize 方法
  async initialize(context) {
    console.log('插件初始化', context);
  },

  // ⚠️  可选的生命周期方法
  async start() {
    console.log('插件启动');
  },

  async stop() {
    console.log('插件停止');
  },
};

4. 查看插件日志

javascript
// 插件目录
%APPDATA%/vue3-simple-electron/plugins/

// 查看插件日志
%APPDATA%/vue3-simple-electron/logs/plugin-{plugin-id}.log

Q12: 自动更新不工作 ​

问题描述：

  • 点击"检查更新"没有反应
  • 或始终提示"已是最新版本"

配置检查：

1. 确认配置文件

ini
# resources/config/config.ini
[Update]
autoCheckUpdate=true
updateUrl=https://your-server.com/update/latest.json

2. 更新服务器配置

json
// latest.json
{
  "version": "1.1.0",
  "releaseDate": "2025-01-15",
  "downloadUrl": "https://your-server.com/download/v1.1.0.zip",
  "releaseNotes": "更新说明..."
}

3. 检查更新处理器

javascript
// 确保更新处理器已注册
const updateHandler = new UpdateHandler(mainWindow);

// 手动触发更新检查
updateHandler.checkForUpdates();

4. 查看网络请求

javascript
// 添加请求日志
axios
  .get(updateUrl)
  .then((response) => {
    logger.info('更新检查响应:', response.data);
  })
  .catch((error) => {
    logger.error('更新检查失败:', error);
  });

Q13: 本地服务器代理不生效 ​

问题描述：

  • 配置了 proxy-rules.yaml 但代理不工作
  • API 请求返回 404

排查步骤：

1. 检查配置文件格式

yaml
# resources/config/proxy-rules.yaml
proxies:
  - path: /api # ✅ 正确
    target: https://api.example.com
    changeOrigin: true

  # ❌ 错误的格式
  - path: '/api' # 不要加引号（YAML 中可省略）
    target: https://api.example.com

2. 检查本地服务器是否启动

ini
# config.ini
[Server]
enableLocalServer=true    # 确保为 true
localServerPort=8080

3. 查看代理日志

javascript
// 在本地服务器中添加日志
app.use((req, res, next) => {
  logger.info(`${req.method} ${req.url}`);
  next();
});

4. 测试代理规则

javascript
// 在渲染进程控制台测试
fetch('/api/test')
  .then((res) => res.json())
  .then((data) => console.log('Success:', data))
  .catch((err) => console.error('Error:', err));

性能问题 ​

Q14: 应用启动缓慢 ​

问题描述：

  • 双击图标后，等待 10 秒以上才显示窗口
  • 启动时 CPU 占用很高

优化方案：

1. 使用异步初始化

javascript
async function initializeApp() {
  // ✅ 先创建窗口，立即显示
  const mainWindow = createWindow();

  // ✅ 并行初始化服务
  await Promise.all([MachineService.initialize(), PluginService.initialize()]);

  // ❌ 避免阻塞窗口显示
  // await heavyOperation();
}

2. 延迟加载非关键模块

javascript
// ✅ 窗口显示后再加载
mainWindow.webContents.once('did-finish-load', () => {
  // 加载非关键功能
  loadPlugins();
  checkUpdates();
});

3. 优化日志初始化

javascript
// ✅ 异步初始化日志清理
LoggerClean.getInstance()
  .initialize()
  .catch((err) => {
    console.error('日志初始化失败:', err);
  });

4. 减少同步 I/O 操作

javascript
// ❌ 避免：同步读取文件
const config = fs.readFileSync('config.ini', 'utf-8');

// ✅ 推荐：异步读取
const config = await fs.promises.readFile('config.ini', 'utf-8');

Q15: 内存占用过高 ​

问题描述：

  • 应用占用内存超过 500MB
  • 长时间运行后内存持续增长

排查方法：

1. 使用性能分析工具

javascript
// 在开发者工具中
// Performance -> Memory -> Take heap snapshot

2. 检查定时器泄漏

javascript
// ✅ 确保清理定时器
class MyService {
  start() {
    this.timer = setInterval(() => {
      this.doWork();
    }, 1000);
  }

  stop() {
    if (this.timer) {
      clearInterval(this.timer);
      this.timer = null;
    }
  }
}

3. 检查事件监听器泄漏

javascript
// ✅ 清理事件监听
app.on('before-quit', () => {
  ipcMain.removeAllListeners();
  mainWindow.webContents.removeAllListeners();
});

4. 清理缓存

javascript
// 定期清理缓存
setInterval(
  () => {
    CacheService.clearExpired();
  },
  60 * 60 * 1000,
); // 每小时

平台兼容 ​

Q16: Windows 7 无法运行 ​

问题描述：

  • Windows 7 上双击无反应
  • 或提示"不是有效的 Win32 应用程序"

解决方案：

当前项目使用 Electron 22，支持 Windows 7/8/10/11。

确认版本：

json
// package.json
{
  "devDependencies": {
    "electron": "^22.0.0" // ✅ 支持 Win7
    // "electron": "^28.0.0"  // ❌ 不支持 Win7
  }
}

其他检查：

  1. 确保 .NET Framework 4.5+ 已安装
  2. 确保 Visual C++ Redistributable 已安装
  3. 更新 Windows 7 到最新 Service Pack

其他问题 ​

Q17: 如何调试主进程？ ​

方法 1：使用 console.log

javascript
console.log('调试信息', data);
console.error('错误信息', error);

方法 2：使用 logger

javascript
logger.info('信息');
logger.error('错误', error);

// 查看日志文件
// %APPDATA%/vue3-simple-electron/logs/main.log

方法 3：使用 VS Code 调试

json
// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Main Process",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
      "windows": {
        "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
      },
      "args": ["."],
      "outputCapture": "std"
    }
  ]
}

方法 4：使用 Chrome DevTools

bash
# 启动时开启远程调试
electron --inspect=5858 .

# 在 Chrome 中访问
chrome://inspect

Q18: 获取更多帮助 ​

官方资源：

项目资源：

社区资源：

问题反馈 ​

如果以上 FAQ 未能解决您的问题，请通过以下方式反馈：

  1. GitHub Issues：https://github.com/your-repo/issues

    • 描述问题现象
    • 提供错误日志
    • 说明操作系统和版本
    • 附上复现步骤

  2. Email：lmxzqq@gmail.com

    • 详细描述问题
    • 附上日志文件
    • 说明期望的行为

  3. 提交 PR

    • 如果您找到了解决方案
    • 欢迎提交 Pull Request
    • 帮助改进项目

相关文档 ​

基于 MIT 许可发布

Copyright © 2024-2025 框架作者(LMX) 版权所有